WAIT(1P) POSIX Programmer's Manual WAIT(1P)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.
NAMEwait - await process completion
SYNOPSISwait [pid...]
DESCRIPTION
When an asynchronous list (see Asynchronous Lists ) is started by the
shell, the process ID of the last command in each element of the asyn‐
chronous list shall become known in the current shell execution envi‐
ronment; see 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 util‐
ity 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
IEEE Std 1003.1-2001, Section 3.203, Job Control Job ID)
that identifies a background process group to be waited for.
The job control job ID notation is applicable only for invo‐
cations of wait in the current shell execution environment;
see 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
IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
ables 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 oper‐
and specified is known, then the exit status of wait shall be the exit
status information of the command indicated by the last operand speci‐
fied. If the process terminated abnormally due to the receipt of a sig‐
nal, 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 . -execwait ... \;
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 IEEE Std 1003.1-2001 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 asynchro‐
nous 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 appli‐
cations 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 IEEE Std 1003.1-2001 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 con‐
sumed. Historical implementations use the wait() function defined in
the System Interfaces volume of IEEE Std 1003.1-2001 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 reli‐
ably 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
Shell Command Language, kill(), sh, the System Interfaces volume of
IEEE Std 1003.1-2001, wait(), waitpid()COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .
IEEE/The Open Group 2003 WAIT(1P)
