Provided by: manpages-posix_2017a-2_all 
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.
NAME
wait — await process completion
SYNOPSIS
wait [pid...]
DESCRIPTION
When an asynchronous list (see 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 Section 2.12, Shell Execution Environment.
If the 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.
If one or more pid operands are specified that represent known process IDs, the wait
utility shall wait until all of them have terminated. If one or more pid operands are
specified that represent unknown process IDs, wait shall treat them as if they were known
process IDs that exited with exit status 127. The exit status returned by the wait utility
shall be the exit status of the process requested by the last pid operand.
The known process IDs are applicable only for invocations of wait in the current shell
execution environment.
OPTIONS
None.
OPERANDS
The following operand shall be supported:
pid One of the following:
1. The unsigned decimal integer process ID of a command, for which the utility
is to wait for the termination.
2. A job control job ID (see the Base Definitions volume of POSIX.1‐2017,
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 wait in the current shell execution environment; see
Section 2.12, Shell Execution Environment. The exit status of wait shall be
determined by the last command in the pipeline.
Note: The job control job ID type of pid is only available on systems
supporting the User Portability Utilities option.
STDIN
Not used.
INPUT FILES
None.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of wait:
LANG Provide a default value for the internationalization variables that are unset or
null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2,
Internationalization Variables for the precedence of internationalization
variables used to determine the values of locale categories.)
LC_ALL If set to a non-empty string value, override the values of all the other
internationalization variables.
LC_CTYPE 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).
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of
diagnostic messages written to standard error.
NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES.
ASYNCHRONOUS EVENTS
Default.
STDOUT
Not used.
STDERR
The standard error shall be used only for diagnostic messages.
OUTPUT FILES
None.
EXTENDED DESCRIPTION
None.
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 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 kill -l option.)
Otherwise, the wait utility shall exit with one of the following values:
0 The wait utility was invoked with no operands and all process IDs known by the
invoking shell have terminated.
1‐126 The wait utility detected an error.
127 The command identified by the last pid operand specified is unknown.
CONSEQUENCES OF ERRORS
Default.
The following sections are informative.
APPLICATION USAGE
On most implementations, wait is a shell built-in. If it is called in a subshell or
separate utility execution environment, such as one of the following:
(wait)
nohup wait ...
find . -exec wait ... \;
it returns immediately because there are no known process IDs to wait for in those
environments.
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 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‐2017 requires the implementation to keep the status of terminated jobs available
until the status is requested, so that scripts like:
j1&
p1=$!
j2&
wait $p1
echo Job 1 exited with status $?
wait $!
echo Job 2 exited with status $?
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 '!' shell parameter, the shell is allowed to discard the status of an asynchronous
list if "$!" 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 "$!". If the implementation of the shell is smart enough to
determine that a reference to "$!" 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 wait with no operands discards the exit status of all
asynchronous lists.)
If the exit status of 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.
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 kill as shown by the following script:
sleep 1000&
pid=$!
kill -kill $pid
wait $pid
echo $pid was terminated by a SIG$(kill -l $?) signal.
If the following sequence of commands is run in less than 31 seconds:
sleep 257 | sleep 31 &
jobs -l %%
either of the following commands returns the exit status of the second sleep in the
pipeline:
wait <pid of sleep 31>
wait %%
RATIONALE
The description of wait does not refer to the waitpid() function from the System
Interfaces volume of POSIX.1‐2017 because that would needlessly overspecify this
interface. However, the wording means that 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 wait() function defined in the System
Interfaces volume of POSIX.1‐2017 until wait() 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 wait utility use a
method such as the functionality provided by the waitpid() function.
The ability to wait for multiple pid operands was adopted from the KornShell.
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
while sleep 60 do
job& echo Job started $(date) as $! done
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 "$!" or if
the script would occasionally wait for jobs it started.
FUTURE DIRECTIONS
None.
SEE ALSO
Chapter 2, Shell Command Language, kill, sh
The Base Definitions volume of POSIX.1‐2017, Section 3.204, Job Control Job ID, Chapter 8,
Environment Variables
The System Interfaces volume of POSIX.1‐2017, wait()
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 .
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 .