diff options
Diffstat (limited to 'man1p/jobs.1p')
| -rw-r--r-- | man1p/jobs.1p | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/man1p/jobs.1p b/man1p/jobs.1p new file mode 100644 index 000000000..3dac15e59 --- /dev/null +++ b/man1p/jobs.1p @@ -0,0 +1,313 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "JOBS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" jobs +.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 +\fIShell Execution Environment\fP , \fIbg\fP , \fIfg\fP , \fIkill\fP() +, \fIwait\fP() +.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 . |