jobs(1)jobs(1)NAMEjobs - display status of jobs in the current session
SYNOPSISjobs [ -l | -p][job_id...]
DESCRIPTION
The jobs utility displays the status of jobs that were started in the
current shell environment; see Shell Execution Environment.
When jobs reports the termination status of a job, the shell removes its
process ID from the list of those "known in the current shell execution
environment".
OPTIONS
The jobs utility supports the XBD specification, Utility Syntax
Guidelines.
The following options are supported:
-l (The letter ell.) Provide 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.
-p Display only the process IDs for the process group leaders of the
selected jobs.
By default, the jobs utility displays the status of all stopped jobs,
running background jobs and all jobs whose status has changed and have
not been reported by the shell.
OPERANDS
The following operand is supported:
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 format of job_id is described in the entry for
job control job ID in the sh(1) manpage.
STDOUT
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>
Page 1
jobs(1)jobs(1)
where the fields are as follows:
<current> The character "+" identifies the job that would be used as
a default for the fg or bg utilities; 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 signal and has not
exited.
Done Indicates that the job completed and
returned exit status zero.
Done(code) Indicates that the job completed
normally 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
Page 2
jobs(1)jobs(1)
all of the other <state> formats shown
here and will indicate the name or
description of the signal causing the
termination.
<command> The associated command that was given to the shell.
If the -l option is specified, a field containing the process 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.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
APPLICATION USAGE
The -p option is the only portable way to find out the process group of a
job because different implementations have different strategies for
defining the process group of the job. Usage such as $(jobs -p) provides
a way of referring to the process group of the job in an implementation-
independent way.
The jobs utility will not work as expected when it is operating in its
own utility execution environment because that environment will have no
applicable jobs to manipulate. See the APPLICATION USAGE section for bg.
For this reason, jobs is generally implemented as a shell regular built-
in.
SEE ALSObg(1), fg(1), kill(1), sh(1), wait(1), job_limits(5).
Page 3
