Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎

stop


NAME
     jobs, fg, bg, stop, notify - control process execution

SYNOPSIS
  sh
     jobs [-p | -l]  [ % job_id...]

     jobs -x command [arguments]

     fg [ % job_id...]

     bg [ % job_id...]

     stop % job_id...

     stop pid...

  csh
     jobs [-l]

     fg [ % job_id]

     bg [ % job_id...]

     notify  [ % job_id]...

     stop % job_id...

     stop pid...

  ksh
     jobs [-lnp] [ % job_id...]

     fg [ % job_id...]

     bg [ % job_id...]

     stop % job_id...

     stop pid...

DESCRIPTION
  sh
     When Job Control is enabled, the Bourne shell built-in  jobs
     reports  all jobs that are stopped or executing in the back-
     ground. If %job_id is omitted, all jobs that are stopped  or
     running  in  the  background will be reported. The following
     options will modify/enhance the output of jobs:

     -l       Reports the process group ID and working  directory
              of the jobs.

     -p       Reports only the process group ID of the jobs.



     -x       Replaces any job_id found in command  or  arguments
              with  the  corresponding process group ID, and then
              executes command passing it arguments.



     When the shell is invoked as jsh, Job Control is enabled  in
     addition  to  all  of the functionality described previously
     for sh. Typically Job Control is enabled for the interactive
     shell  only. Non-interactive shells typically do not benefit
     from the added functionality of Job Control.

     With Job Control enabled every command or pipeline the  user
     enters at the terminal is called a job_id. All jobs exist in
     one of  the  following  states:  foreground,  background  or
     stopped. These terms are defined as follows:

     1.  A job in the foreground has read and write access to the
         controlling terminal.


     2.  A job in the background is denied read  access  and  has
         conditional  write  access  to  the controlling terminal
         (see stty(1))


     3.  A stopped job is  a  job  that  has  been  placed  in  a
         suspended state, usually as a result of a SIGTSTP signal
         (see signal.h(3HEAD)).


     Every job that the  shell  starts  is  assigned  a  positive
     integer,  called  a  job_id  number  which is tracked by the
     shell and will be  used  as  an  identifier  to  indicate  a
     specific  job.  Additionally,  the  shell keeps track of the
     current and previous jobs.  The  current  job  is  the  most
     recent  job  to be started or restarted. The previous job is
     the first non-current job.

     The acceptable syntax for a Job Identifier is of the form:

          %job_id


     where job_id may be specified in any of the  following  for-
     mats:


     % or +          for the current job



     -               for the previous job



     ?<string>       specify the job for which the  command  line
                     uniquely contains string.



     n               for job number n, where n is a job number



     pref            where pref is a unique prefix of the command
                     name (for example, if the command ls -l name
                     were running in the background, it could  be
                     referred  to  as  %ls);  pref cannot contain
                     blanks unless it is quoted.



     When Job Control is enabled, fg resumes the execution  of  a
     stopped job in the foreground, also moves an executing back-
     ground job into the foreground. If %job_id  is  omitted  the
     current job is assumed.

     When Job Control is enabled, bg resumes the execution  of  a
     stopped  job  in  the  background. If %job_id is omitted the
     current job is assumed.

     stop stops the execution of a background job(s) by using its
     job_id, or of any process by using its pid; see ps(1).

  csh
     The C shell built-in, jobs, without an argument,  lists  the
     active jobs under job control.

     -l       List process IDs, in addition to the normal  infor-
              mation.



     The shell associates a numbered  job_id  with  each  command
     sequence to keep track of those commands that are running in
     the background or have been stopped with TSTP signals (typi-
     cally  <Control-Z>).  When  a  command  or  command sequence
     (semicolon-separated list)  is  started  in  the  background
     using  the  &  metacharacter, the shell displays a line with
     the job number in brackets and a list of associated  process
     numbers:

          [1] 1234


     To see the current list of jobs, use the jobs built-in  com-
     mand.  The  job most recently stopped (or put into the back-
     ground if none are stopped) is referred to  as  the  current
     job  and  is indicated with a `+'. The previous job is indi-
     cated with a `-'; when the  current  job  is  terminated  or
     moved  to  the foreground, this job takes its place (becomes
     the new current job).

     To manipulate jobs, refer to the bg, fg, kill, stop,  and  %
     built-in commands.

     A reference to a job begins with a `%'. By itself, the  per-
     cent sign refers to the current job.

     % %+ %%         The current job.



     %-              The previous job.



     %j              Refer to job j as in: `kill -9 %j'. j can be
                     a  job  number,  or  a  string that uniquely
                     specifies the command line by which  it  was
                     started;  `fg  %vi' might bring a stopped vi
                     job to the foreground, for instance.



     %?string        Specify the job for which the  command  line
                     uniquely contains string.



     A job running in the background stops when  it  attempts  to
     read from the terminal. Background jobs can normally produce
     output, but this can be suppressed using the  `stty  tostop'
     command.

     fg brings the current or specified  job_id  into  the  fore-
     ground.

     bg runs the current or specified jobs in the background.


     stop stops the execution of a background job(s) by using its
     job_id, or of any process by using its pid; see ps(1).

     notify will notify the user asynchronously when  the  status
     of the current job or specified jobs changes.

  ksh
     jobs displays the status of the jobs that  were  started  in
     the  current shell environment. When jobs reports the termi-
     nation status of a job, the shell  removes  its  process  ID
     from the list of those "known in the current shell execution
     environment."

     job_id specifies the jobs for which  the  status  is  to  be
     displayed. If no job_id is given, the status information for
     all jobs will be displayed.

     The following options  will  modify/enhance  the  output  of
     jobs:

     -l       (The letter ell.) Provides more  information  about
              each  job listed. This information includes the job
              number, current job, process group  ID,  state  and
              the command that formed the job.



     -n       Displays only jobs  that  have  stopped  or  exited
              since last notified.



     -p       Displays only the process IDs for the process group
              leaders of the selected jobs.



     By default, jobs displays the  status  of  all  the  stopped
     jobs, running background jobs, and all jobs whose status has
     changed and have not been reported by the shell.

     If the monitor option of the set command is  turned  on,  an
     interactive  shell  associates  a job with each pipeline. It
     keeps a table of current jobs, printed by the jobs  command,
     and  assigns  them  small  integer  numbers.  When  a job is
     started asynchronously with &, the shell prints a line which
     looks like:

          [1] 1234



     indicating that the job, which was  started  asynchronously,
     was job number 1 and had one (top-level) process, whose pro-
     cess id was 1234.

     If you are running a job and wish to do something  else  you
     may hit the key <^Z> (<Control-Z>) which sends a STOP signal
     to the current job. The shell will  then  normally  indicate
     that  the  job  has  been  "Stopped" (see OUTPUT below), and
     print another prompt. You can then manipulate the  state  of
     this  job, putting it in the background with the bg command,
     or run some other commands and then eventually bring the job
     back  into  the foreground with the foreground command fg. A
     <^Z> takes effect immediately and is like an  interrupt,  in
     that  pending  output and unread input are discarded when it
     is typed.

     There are several ways to refer to jobs in the shell. A  job
     can  be  referred to by the process id of any process of the
     job or by one of the following:

     %number         The job with the given number.



     %string         Any  job  whose  command  line  begins  with
                     string;  works  only in the interactive mode
                     when the history file is active.



     %?string        Any job whose command line contains  string;
                     works  only in the interactive mode when the
                     history file is active.



     %%              Current job.



     %+              Equivalent to %%.



     %-              Previous job.



     The shell learns  immediately  whenever  a  process  changes
     state.  It  normally  informs  you  whenever  a  job becomes
     blocked so that no further progress is  possible,  but  only
     just before it prints a prompt. This is done so that it does
     not otherwise disturb your work. When the  monitor  mode  is
     on, each background job that completes triggers any trap set
     for CHLD. When you try to leave the  shell  while  jobs  are
     running  or  stopped,  you  will  be  warned  that `You have
     stopped (running) jobs.' You may use the jobs command to see
     what  they  are.  If  you do this or immediately try to exit
     again, the shell will not warn you a second  time,  and  the
     stopped jobs will be terminated.

     fg will move a background job from the  current  environment
     into  the  foreground.  Using fg to place a job in the fore-
     ground will remove its process ID from  the  list  of  those
     "known  in  the current shell execution environment." The fg
     command is available only on systems that support  job  con-
     trol. If job_id is not specified, the current job is brought
     into the foreground.

     bg resumes suspended jobs from the  current  environment  by
     running  them  as  background  jobs. If the job specified by
     job_id is already a running background job, bg has no effect
     and will exit successfully. Using bg to place a job into the
     background causes its process ID to become  ``known  in  the
     current  shell  execution  environment'',  as if it had been
     started as an asynchronous list. The bg command is available
     only  on  systems that support job control. If job_id is not
     specified, the current job is placed in the background.

     stop stops the execution of a background job(s) by using its
     job_id, or of any process by using its pid. See ps(1).

OUTPUT
     If the -p option is specified, the output  consists  of  one
     line for each process ID:

          "%d\n", "process ID"


     Otherwise, if the -l option is not specified, the output  is
     a series of lines of the form:

          "[%d] %c %s %s\n", job-number, current, state, command


     where the fields are as follows:

     current         The character  +  identifies  the  job  that
                     would  be used as a default for the fg or bg
                     commands. This job  can  also  be  specified
                     using  the job_id %+ or %% . The character -
                     identifies the job  that  would  become  the
                     default  if  the current default job were to
                     exit; this job can also be  specified  using
                     the  job_id  %- . For other jobs, this field
                     is a space character. At most, one  job  can
                     be identified with + and at most one job can
                     be  identified  with  -.  If  there  is  any
                     suspended  job, then the current job will be
                     a suspended job. If there are at  least  two
                     suspended  jobs,  then the previous job will
                     also be a suspended job.



     job-number      A number that can be used  to  identify  the
                     process  group to the wait, fg, bg, and kill
                     utilities. Using these  utilities,  the  job
                     can  be  identified  by  prefixing  the  job
                     number with %.



     state           One of the following strings (in  the  POSIX
                     Locale):

                     Running                 Indicates  that  the
                                             job   has  not  been
                                             suspended by a  sig-
                                             nal   and   has  not
                                             exited.




                     Done                    Indicates  that  the
                                             job   completed  and
                                             returned exit status
                                             zero.



                     Done(code)              Indicates  that  the
                                             job  completed  nor-
                                             mally  and  that  it
                                             exited    with   the
                                             specified   non-zero
                                             exit  status,  code,
                                             expressed    as    a
                                             decimal number.



                     Stopped


                     Stopped(SIGTSTP)        Indicates  that  the
                                             job was suspended by
                                             the SIGTSTP signal.



                     Stopped(SIGSTOP)        Indicates  that  the
                                             job was suspended by
                                             the SIGSTOP signal.



                     Stopped(SIGTTIN)        Indicates  that  the
                                             job was suspended by
                                             the SIGTTIN signal.



                     Stopped(SIGTTOU)        Indicates  that  the
                                             job was suspended by
                                             the SIGTTOU signal.



                     The implementation may substitute the string
                     Suspended  in  place  of Stopped. If the job
                     was terminated by a signal,  the  format  of
                     state is unspecified, but it will be visibly
                     distinct from all of the other state formats
                     shown  here  and  will  indicate the name or
                     description of the signal causing the termi-
                     nation.


     command         The associated command that was given to the
                     shell.



     If the -l option is specified, a field containing  the  pro-
     cess group ID is inserted before the state field. Also, more
     processes in a process  group  may  be  output  on  separate
     lines, using only the process ID and command fields.

ENVIRONMENT VARIABLES
     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution of jobs, fg, and bg:
     LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS
     The following exit values are returned for jobs, fg, and bg:

     0        Successful completion.



     >0       An error occurred.



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|


SEE ALSO
     csh(1),   kill(1),   ksh(1),    ps(1),    sh(1),    stop(1),
     shell_builtins(1), stty(1), wait(1), signal.h(3HEAD), attri-
     butes(5), environ(5), standards(5)










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments