Section: POSIX Programmer's Manual (1P)
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.
--- await process completion
When an asynchronous list (see
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
, Shell Execution Environment.
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
If one or more
operands are specified that represent known process IDs, the
utility shall wait until all of them have terminated. If one or more
operands are specified that represent unknown process IDs,
shall treat them as if they were known process IDs that exited with
exit status 127. The exit status returned by the
utility shall be the exit status of the process requested by the last
The known process IDs are applicable only for invocations of
in the current shell execution environment.
The following operand shall be supported:
One of the following:
The unsigned decimal integer process ID of a command, for which the
utility is to wait for the termination.
A job control job ID (see the Base Definitions volume of POSIX.1-2008,
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
in the current shell execution environment; see
Section 2.12, Shell Execution Environment.
The exit status of
shall be determined by the last command in the pipeline.
The job control job ID type of
is only available on systems supporting the User Portability Utilities
The following environment variables shall affect the execution of
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1-2008,
Section 8.2, Internationalization Variables
for the precedence of internationalization variables used to determine
the values of locale categories.)
If set to a non-empty string value, override the values of all the
other internationalization variables.
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).
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
Determine the location of message catalogs for the processing of
The standard error shall be used only for diagnostic messages.
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
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
option.) Otherwise, the
utility shall exit with one of the following values:
utility was invoked with no operands and all process IDs known by the
invoking shell have terminated.
utility detected an error.
The command identified by the last
operand specified is unknown.
CONSEQUENCES OF ERRORS
The following sections are informative.
On most implementations,
is a shell built-in. If it is called in a subshell or separate utility
execution environment, such as one of the following:
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
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-2008 requires
the implementation to keep the status of terminated jobs available
until the status is requested, so that scripts like:
echo Job 1 exited with status $?
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
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
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
with no operands discards the exit status of all asynchronous lists.)
If the exit status of
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
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
as shown by the following script:
kill -kill $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
in the pipeline:
wait <pid of sleep 31>
The description of
does not refer to the
function from the System Interfaces volume of POSIX.1-2008 because that would needlessly overspecify this
interface. However, the wording means that
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
function defined in the System Interfaces volume of POSIX.1-2008 until
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
utility use a method such as the functionality provided by the
The ability to wait for multiple
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
for jobs it started.
, Shell Command Language,
The Base Definitions volume of POSIX.1-2008,
Section 3.204, Job Control Job ID,
Chapter 8, Environment Variables
The System Interfaces volume of POSIX.1-2008,
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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
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