2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "JOBS" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" jobs
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
jobs \- display status of jobs in the current session
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBjobs\fP \fB[\fP\fB-l| -p\fP\fB][\fP\fIjob_id\fP\fB...\fP\fB]\fP\fB\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIjobs\fP utility shall display the status of jobs that were
|
|
|
|
started in the current shell environment; see \fIShell Execution Environment\fP
|
|
|
|
\&.
|
|
|
|
.LP
|
|
|
|
When \fIjobs\fP reports the termination status of a job, the shell
|
|
|
|
shall remove its process ID from the list of those "known
|
|
|
|
in the current shell execution environment''; see \fIAsynchronous
|
|
|
|
Lists\fP .
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fIjobs\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following options shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fB-l\fP
|
|
|
|
(The letter ell.) Provide more information about each job listed.
|
|
|
|
This information shall include the job number, current job,
|
|
|
|
process group ID, state, and the command that formed the job.
|
|
|
|
.TP 7
|
|
|
|
\fB-p\fP
|
|
|
|
Display only the process IDs for the process group leaders of the
|
|
|
|
selected jobs.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
By default, the \fIjobs\fP utility shall display the status of all
|
|
|
|
stopped jobs, running background jobs and all jobs whose
|
|
|
|
status has changed and have not been reported by the shell.
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operand shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIjob_id\fP
|
|
|
|
Specifies the jobs for which the status is to be displayed. If no
|
|
|
|
\fIjob_id\fP is given, the status information for all jobs
|
|
|
|
shall be displayed. The format of \fIjob_id\fP is described in the
|
|
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.203,
|
|
|
|
Job Control Job ID.
|
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fIjobs\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
Provide a default value for the internationalization variables that
|
|
|
|
are unset or null. (See the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
|
|
for
|
|
|
|
the precedence of internationalization variables used to determine
|
|
|
|
the values of locale categories.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
|
|
of text data as characters (for example, single-byte as
|
|
|
|
opposed to multi-byte characters in arguments).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard error and
|
|
|
|
informative messages written to standard output.
|
|
|
|
.TP 7
|
|
|
|
\fINLSPATH\fP
|
|
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
|
|
\&.\fP
|
|
|
|
.sp
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
If the \fB-p\fP option is specified, the output shall consist of one
|
|
|
|
line for each process ID:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%d\\n", <\fP\fIprocess ID\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
Otherwise, if the \fB-l\fP option is not specified, the output shall
|
|
|
|
be a series of lines of the form:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"[%d] %c %s %s\\n", <\fP\fIjob-number\fP\fB>, <\fP\fIcurrent\fP\fB>, <\fP\fIstate\fP\fB>, <\fP\fIcommand\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
where the fields shall be as follows:
|
|
|
|
.TP 7
|
|
|
|
<\fIcurrent\fP>
|
|
|
|
The character \fB'+'\fP identifies the job that would be used as a
|
|
|
|
default for the \fIfg\fP or \fIbg\fP utilities; this job can also
|
|
|
|
be specified
|
|
|
|
using the \fIjob_id\fP %+ or \fB"%%"\fP . The character \fB'-'\fP
|
|
|
|
identifies the job that would become the default if the
|
|
|
|
current default job were to exit; this job can also be specified using
|
|
|
|
the \fIjob_id\fP %-. For other jobs, this field is a
|
|
|
|
<space>. At most one job can be identified with \fB'+'\fP and at most
|
|
|
|
one job can be identified with \fB'-'\fP . If
|
|
|
|
there is any suspended job, then the current job shall be a suspended
|
|
|
|
job. If there are at least two suspended jobs, then the
|
|
|
|
previous job also shall be a suspended job.
|
|
|
|
.TP 7
|
|
|
|
<\fIjob-number\fP>
|
|
|
|
A number that can be used to identify the process group to the \fIwait\fP,
|
|
|
|
\fIfg\fP, \fIbg\fP, and \fIkill\fP utilities. Using these utilities,
|
|
|
|
the job can be identified by prefixing the job number
|
|
|
|
with \fB'%'\fP .
|
|
|
|
.TP 7
|
|
|
|
<\fIstate\fP>
|
|
|
|
One of the following strings (in the POSIX locale):
|
|
|
|
.TP 7
|
|
|
|
\fBRunning\fP
|
|
|
|
.RS
|
|
|
|
Indicates that the job has not been suspended by a signal and has
|
|
|
|
not exited.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBDone\fP
|
|
|
|
.RS
|
|
|
|
Indicates that the job completed and returned exit status zero.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBDone\fP(\fIcode\fP)
|
|
|
|
.RS
|
|
|
|
Indicates that the job completed normally and that it exited with
|
|
|
|
the specified non-zero exit status, \fIcode\fP, expressed as
|
|
|
|
a decimal number.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBStopped\fP
|
|
|
|
.RS
|
|
|
|
Indicates that the job was suspended by the SIGTSTP signal.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBStopped\fP\ (\fBSIGTSTP\fP)
|
|
|
|
.RS
|
|
|
|
.sp
|
|
|
|
Indicates that the job was suspended by the SIGTSTP signal.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBStopped\fP\ (\fBSIGSTOP\fP)
|
|
|
|
.RS
|
|
|
|
.sp
|
|
|
|
Indicates that the job was suspended by the SIGSTOP signal.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBStopped\fP\ (\fBSIGTTIN\fP)
|
|
|
|
.RS
|
|
|
|
.sp
|
|
|
|
Indicates that the job was suspended by the SIGTTIN signal.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBStopped\fP\ (\fBSIGTTOU\fP)
|
|
|
|
.RS
|
|
|
|
.sp
|
|
|
|
Indicates that the job was suspended by the SIGTTOU signal.
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
The implementation may substitute the string \fBSuspended\fP in place
|
|
|
|
of \fBStopped\fP. If the job was terminated by a signal,
|
|
|
|
the format of <\fIstate\fP> is unspecified, but it shall be visibly
|
|
|
|
distinct from all of the other <\fIstate\fP>
|
|
|
|
formats shown here and shall indicate the name or description of the
|
|
|
|
signal causing the termination.
|
|
|
|
.TP 7
|
|
|
|
<\fIcommand\fP>
|
|
|
|
The associated command that was given to the shell.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If the \fB-l\fP option is specified, a field containing the process
|
|
|
|
group ID shall be inserted before the <\fIstate\fP>
|
|
|
|
field. Also, more processes in a process group may be output on separate
|
|
|
|
lines, using only the process ID and
|
|
|
|
<\fIcommand\fP> fields.
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
The following exit values shall be returned:
|
|
|
|
.TP 7
|
|
|
|
\ 0
|
|
|
|
Successful completion.
|
|
|
|
.TP 7
|
|
|
|
>0
|
|
|
|
An error occurred.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
The \fB-p\fP 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 $( \fIjobs\fP \fB-p\fP) provides a way of referring
|
|
|
|
to the process group of the job in an implementation-independent way.
|
|
|
|
.LP
|
|
|
|
The \fIjobs\fP utility does not work as expected when it is operating
|
|
|
|
in its own utility execution environment because that
|
|
|
|
environment has no applicable jobs to manipulate. See the APPLICATION
|
|
|
|
USAGE section for \fIbg\fP . For this
|
|
|
|
reason, \fIjobs\fP is generally implemented as a shell regular built-in.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
Both \fB"%%"\fP and \fB"%+"\fP are used to refer to the current job.
|
|
|
|
Both forms are of equal validity-the \fB"%%"\fP
|
|
|
|
mirroring \fB"$$"\fP and \fB"%+"\fP mirroring the output of \fIjobs\fP.
|
|
|
|
Both forms reflect historical practice of the
|
|
|
|
KornShell and the C shell with job control.
|
|
|
|
.LP
|
|
|
|
The job control features provided by \fIbg\fP, \fIfg\fP,
|
|
|
|
and \fIjobs\fP are based on the KornShell. The standard developers
|
|
|
|
examined the characteristics of the C shell versions of these
|
|
|
|
utilities and found that differences exist. Despite widespread use
|
|
|
|
of the C shell, the KornShell versions were selected for this
|
|
|
|
volume of IEEE\ Std\ 1003.1-2001 to maintain a degree of uniformity
|
|
|
|
with the rest of the KornShell features selected (such
|
|
|
|
as the very popular command line editing features).
|
|
|
|
.LP
|
|
|
|
The \fIjobs\fP utility is not dependent on the job control option,
|
|
|
|
as are the seemingly related \fIbg\fP and \fIfg\fP utilities because
|
|
|
|
\fIjobs\fP is useful for
|
|
|
|
examining background jobs, regardless of the condition of job control.
|
|
|
|
When the user has invoked a \fIset\fP \fB+m\fP command and job control
|
|
|
|
has been turned off, \fIjobs\fP can still be
|
|
|
|
used to examine the background jobs associated with that current session.
|
|
|
|
Similarly, \fIkill\fP can then be used to kill background jobs with
|
|
|
|
\fIkill\fP% <\fIbackground job number\fP>.
|
|
|
|
.LP
|
|
|
|
The output for terminated jobs is left unspecified to accommodate
|
|
|
|
various historical systems. The following formats have been
|
|
|
|
witnessed:
|
|
|
|
.IP " 1." 4
|
|
|
|
\fBKilled\fP( \fIsignal name\fP)
|
|
|
|
.LP
|
|
|
|
.IP " 2." 4
|
|
|
|
\fIsignal name\fP
|
|
|
|
.LP
|
|
|
|
.IP " 3." 4
|
|
|
|
\fIsignal name\fP( \fBcoredump\fP)
|
|
|
|
.LP
|
|
|
|
.IP " 4." 4
|
|
|
|
\fIsignal description\fP- \fBcore dumped\fP
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
Most users should be able to understand these formats, although it
|
|
|
|
means that applications have trouble parsing them.
|
|
|
|
.LP
|
|
|
|
The calculation of job IDs was not described since this would suggest
|
|
|
|
an implementation, which may impose unnecessary
|
|
|
|
restrictions.
|
|
|
|
.LP
|
|
|
|
In an early proposal, a \fB-n\fP option was included to "Display the
|
|
|
|
status of jobs that have changed, exited, or stopped
|
|
|
|
since the last status report". It was removed because the shell always
|
|
|
|
writes any changed status of jobs before each prompt.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 17:56:19 +00:00
|
|
|
\fIShell Execution Environment\fP, \fIbg\fP, \fIfg\fP, \fIkill\fP(),
|
|
|
|
\fIwait\fP()
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|