diff options
Diffstat (limited to 'upstream/archlinux/man1p/wait.1p')
| -rw-r--r-- | upstream/archlinux/man1p/wait.1p | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/wait.1p b/upstream/archlinux/man1p/wait.1p new file mode 100644 index 00000000..b200daa0 --- /dev/null +++ b/upstream/archlinux/man1p/wait.1p @@ -0,0 +1,348 @@ +'\" et +.TH WAIT "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 +wait +\(em await process completion +.SH SYNOPSIS +.LP +.nf +wait \fB[\fIpid\fR...\fB]\fR +.fi +.SH DESCRIPTION +When an asynchronous list (see +.IR "Section 2.9.3.1" ", " "Examples") +is started by the shell, the process ID of the last command in each +element of the asynchronous list shall become known in the current +shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +If the +.IR wait +utility is invoked with no operands, it shall wait until all process +IDs known to the invoking shell have terminated and exit with a zero +exit status. +.P +If one or more +.IR pid +operands are specified that represent known process IDs, the +.IR wait +utility shall wait until all of them have terminated. If one or more +.IR pid +operands are specified that represent unknown process IDs, +.IR wait +shall treat them as if they were known process IDs that exited with +exit status 127. The exit status returned by the +.IR wait +utility shall be the exit status of the process requested by the last +.IR pid +operand. +.P +The known process IDs are applicable only for invocations of +.IR wait +in the current shell execution environment. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIpid\fR" 10 +One of the following: +.RS 10 +.IP " 1." 4 +The unsigned decimal integer process ID of a command, for which the +utility is to wait for the termination. +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.204" ", " "Job Control Job ID") +that identifies a background process group to be waited for. The job +control job ID notation is applicable only for invocations of +.IR wait +in the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +The exit status of +.IR wait +shall be determined by the last command in the pipeline. +.RS 4 +.TP 10 +.BR Note: +The job control job ID type of +.IR pid +is only available on systems supporting the User Portability Utilities +option. +.P +.RE +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR wait : +.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. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If one or more operands were specified, all of them have terminated or +were not known by the invoking shell, and the status of the last +operand specified is known, then the exit status of +.IR wait +shall be the exit status information of the command indicated by the +last operand specified. If the process terminated abnormally due to +the receipt of a signal, the exit status shall be greater than 128 and +shall be distinct from the exit status generated by other signals, but +the exact value is unspecified. (See the +.IR kill +.BR \-l +option.) Otherwise, the +.IR wait +utility shall exit with one of the following values: +.IP "\0\0\0\00" 8 +The +.IR wait +utility was invoked with no operands and all process IDs known by the +invoking shell have terminated. +.IP "1\(hy126" 8 +The +.IR wait +utility detected an error. +.IP "\0\0127" 8 +The command identified by the last +.IR pid +operand specified is unknown. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On most implementations, +.IR wait +is a shell built-in. If it is called in a subshell or separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf + +(wait) +nohup wait ... +find . -exec wait ... \e; +.fi +.P +.RE +.P +it returns immediately because there are no known process IDs to wait +for in those environments. +.P +Historical implementations of interactive shells have discarded the +exit status of terminated background processes before each shell +prompt. Therefore, the status of background processes was usually lost +unless it terminated while +.IR wait +was waiting for it. This could be a serious problem when a job that +was expected to run for a long time actually terminated quickly with a +syntax or initialization error because the exit status returned was +usually zero if the requested process ID was not found. This volume of POSIX.1\(hy2017 requires +the implementation to keep the status of terminated jobs available +until the status is requested, so that scripts like: +.sp +.RS 4 +.nf + +j1& +p1=$! +j2& +wait $p1 +echo Job 1 exited with status $? +wait $! +echo Job 2 exited with status $? +.fi +.P +.RE +.P +work without losing status on any of the jobs. The shell is allowed to +discard the status of any process if it determines that the application +cannot get the process ID for that process from the shell. It is also +required to remember only +{CHILD_MAX} +number of processes in this way. Since the only way to get the process +ID from the shell is by using the +.BR '!' +shell parameter, the shell is allowed to discard the status of an +asynchronous list if +.BR \(dq$!\(dq +was not referenced before another asynchronous list was started. (This +means that the shell only has to keep the status of the last +asynchronous list started if the application did not reference +.BR \(dq$!\(dq . +If the implementation of the shell is smart enough to determine that a +reference to +.BR \(dq$!\(dq +was not saved anywhere that the application can retrieve it later, it +can use this information to trim the list of saved information. Note +also that a successful call to +.IR wait +with no operands discards the exit status of all asynchronous lists.) +.P +If the exit status of +.IR wait +is greater than 128, there is no way for the application to know if the +waited-for process exited with that value or was killed by a signal. +Since most utilities exit with small values, there is seldom any +ambiguity. Even in the ambiguous cases, most applications just need to +know that the asynchronous job failed; it does not matter whether it +detected an error and failed or was killed and did not complete its job +normally. +.SH EXAMPLES +Although the exact value used when a process is terminated by a signal +is unspecified, if it is known that a signal terminated a process, a +script can still reliably determine which signal by using +.IR kill +as shown by the following script: +.sp +.RS 4 +.nf + +sleep 1000& +pid=$! +kill -kill $pid +wait $pid +echo $pid was terminated by a SIG$(kill -l $?) signal. +.fi +.P +.RE +.P +If the following sequence of commands is run in less than 31 seconds: +.sp +.RS 4 +.nf + +sleep 257 | sleep 31 & +jobs -l %% +.fi +.P +.RE +.P +either of the following commands returns the exit status of the second +.IR sleep +in the pipeline: +.sp +.RS 4 +.nf + +wait \fI<pid of sleep 31>\fP +wait %% +.fi +.P +.RE +.SH RATIONALE +The description of +.IR wait +does not refer to the +\fIwaitpid\fR() +function from the System Interfaces volume of POSIX.1\(hy2017 because that would needlessly overspecify this +interface. However, the wording means that +.IR wait +is required to wait for an explicit process when it is given an +argument so that the status information of other processes is not +consumed. Historical implementations use the +\fIwait\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017 until +\fIwait\fR() +returns the requested process ID or finds that the requested process +does not exist. Because this means that a shell script could not +reliably get the status of all background children if a second +background job was ever started before the first job finished, it is +recommended that the +.IR wait +utility use a method such as the functionality provided by the +\fIwaitpid\fR() +function. +.P +The ability to wait for multiple +.IR pid +operands was adopted from the KornShell. +.P +This new functionality was added because it is needed to determine the +exit status of any asynchronous list accurately. The only +compatibility problem that this change creates is for a script like +.sp +.RS 4 +.nf + +while sleep 60 do + job& echo Job started $(date) as $! done +.fi +.P +.RE +.P +which causes the shell to monitor all of the jobs started until the +script terminates or runs out of memory. This would not be a problem +if the loop did not reference +.BR \(dq$!\(dq +or if the script would occasionally +.IR wait +for jobs it started. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIkill\fR\^", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIwait\fR\^(\|)" +.\" +.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 . |