wait.1p (10657B)
- '\" 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 .