diff options
Diffstat (limited to 'upstream/archlinux/man1p/jobs.1p')
| -rw-r--r-- | upstream/archlinux/man1p/jobs.1p | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/jobs.1p b/upstream/archlinux/man1p/jobs.1p new file mode 100644 index 00000000..dbe5004d --- /dev/null +++ b/upstream/archlinux/man1p/jobs.1p @@ -0,0 +1,345 @@ +'\" et +.TH JOBS "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.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. +.\" +.SH NAME +jobs +\(em display status of jobs in the current session +.SH SYNOPSIS +.LP +.nf +jobs \fB[\fR-l|-p\fB] [\fIjob_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR jobs +utility shall display the status of jobs that were started in the +current shell environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +When +.IR jobs +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 +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +The +.IR jobs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-l\fP" 10 +(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. +.IP "\fB\-p\fP" 10 +Display only the process IDs for the process group leaders of the +selected jobs. +.P +By default, the +.IR jobs +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 +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specifies the jobs for which the status is to be displayed. If no +.IR job_id +is given, the status information for all jobs shall be displayed. The +format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR jobs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +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. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \-p +option is specified, the output shall consist of one line for each +process ID: +.sp +.RS 4 +.nf + +"%d\en", <\fIprocess ID\fR> +.fi +.P +.RE +.P +Otherwise, if the +.BR \-l +option is not specified, the output shall be a series of lines of the +form: +.sp +.RS 4 +.nf + +"[%d] %c %s %s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fIstate\fR>, <\fIcommand\fR> +.fi +.P +.RE +.P +where the fields shall be as follows: +.IP "<\fIcurrent\fP>" 10 +The character +.BR '\(pl' +identifies the job that would be used as a default for the +.IR fg +or +.IR bg +utilities; this job can also be specified using the +.IR job_id +%+ or +.BR \(dq%%\(dq . +The character +.BR '\-' +identifies the job that would become the default if the current default +job were to exit; this job can also be specified using the +.IR job_id +%\-. For other jobs, this field is a +<space>. +At most one job can be identified with +.BR '\(pl' +and at most one job can be identified with +.BR '\-' . +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. +.IP "<\fIjob-number\fP>" 10 +A number that can be used to identify the process group to the +.IR wait , +.IR fg , +.IR bg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIstate\fP>" 10 +One of the following strings (in the POSIX locale): +.RS 10 +.IP "\fBRunning\fR" 10 +Indicates that the job has not been suspended by a signal and has not +exited. +.IP "\fBDone\fR" 10 +Indicates that the job completed and returned exit status zero. +.IP "\fBDone\fR(\fIcode\fR)" 10 +Indicates that the job completed normally and that it exited with the +specified non-zero exit status, +.IR code , +expressed as a decimal number. +.IP "\fBStopped\fR" 10 +Indicates that the job was suspended by the SIGTSTP signal. +.IP "\fBStopped\fR\ (\fBSIGTSTP\fR)" 10 +.br +Indicates that the job was suspended by the SIGTSTP signal. +.IP "\fBStopped\fR\ (\fBSIGSTOP\fR)" 10 +.br +Indicates that the job was suspended by the SIGSTOP signal. +.IP "\fBStopped\fR\ (\fBSIGTTIN\fR)" 10 +.br +Indicates that the job was suspended by the SIGTTIN signal. +.IP "\fBStopped\fR\ (\fBSIGTTOU\fR)" 10 +.br +Indicates that the job was suspended by the SIGTTOU signal. +.P +The implementation may substitute the string +.BR Suspended +in place of +.BR Stopped . +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. +.RE +.IP "<\fIcommand\fR>" 10 +The associated command that was given to the shell. +.P +If the +.BR \-l +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 +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \-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 $(\c +.IR jobs +.BR \-p ) +provides a way of referring to the process group of the job in an +implementation-independent way. +.P +The +.IR jobs +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 +.IR "\fIbg\fR\^". +For this reason, +.IR jobs +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +Both +.BR \(dq%%\(dq +and +.BR \(dq%+\(dq +are used to refer to the current job. Both forms are of equal +validity\(emthe +.BR \(dq%%\(dq +mirroring +.BR \(dq$$\(dq +and +.BR \(dq%+\(dq +mirroring the output of +.IR jobs . +Both forms reflect historical practice of the KornShell and the C shell +with job control. +.P +The job control features provided by +.IR bg , +.IR fg , +and +.IR jobs +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 POSIX.1\(hy2017 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.P +The +.IR jobs +utility is not dependent on the job control option, as are the +seemingly related +.IR bg +and +.IR fg +utilities because +.IR jobs +is useful for examining background jobs, regardless of the condition of +job control. When the user has invoked a +.IR set +.BR +m +command and job control has been turned off, +.IR jobs +can still be used to examine the background jobs associated with that +current session. Similarly, +.IR kill +can then be used to kill background jobs with +.IR kill +%<\fIbackground job number\fP>. +.P +The output for terminated jobs is left unspecified to accommodate +various historical systems. The following formats have been witnessed: +.IP " 1." 4 +.BR Killed (\c +.IR "signal name" ) +.IP " 2." 4 +.IR "signal name" +.IP " 3." 4 +.IR "signal name" (\c +.BR coredump ) +.IP " 4." 4 +.IR "signal description" \- +.BR "core dumped" +.P +Most users should be able to understand these formats, although it +means that applications have trouble parsing them. +.P +The calculation of job IDs was not described since this would suggest +an implementation, which may impose unnecessary restrictions. +.P +In an early proposal, a +.BR \-n +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" +None. +.SH "SEE ALSO" +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIbg\fR\^", +.IR "\fIfg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |