WAIT

PROLOG

NAME

SYNOPSIS

wait [pid...]

DESCRIPTION

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

OPERANDS

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

INPUT FILES

ENVIRONMENT VARIABLES

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

STDOUT

STDERR

OUTPUT FILES

EXTENDED DESCRIPTION

EXIT STATUS

    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

The following sections are informative.  

APPLICATION USAGE

(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

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 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

SEE ALSO

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

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 .

Index

PROLOG

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

OPERANDS

STDIN

INPUT FILES

ENVIRONMENT VARIABLES

ASYNCHRONOUS EVENTS

STDOUT

STDERR

OUTPUT FILES

EXTENDED DESCRIPTION

EXIT STATUS

CONSEQUENCES OF ERRORS

APPLICATION USAGE

EXAMPLES

RATIONALE

FUTURE DIRECTIONS

SEE ALSO

COPYRIGHT