Wait built-in
The wait built-in waits for jobs to finish.
Synopsis
wait [job_id_or_process_id…]
Description
See Job control for an overview of job control in yash-rs, though this built-in can also be used for asynchronous commands without job control. If you specify one or more operands, the built-in waits for the specified jobs to finish. Otherwise, the built-in waits for all existing jobs. If the jobs are already finished, the built-in returns without waiting.
If you attempt to wait for a suspended job, the built-in will wait indefinitely until the job is resumed and completes. Currently, there is no way to cancel a wait in progress. When job control is enabled, it is often preferable to use fg instead of wait, as fg allows you to interact with the job—including suspending or interrupting it.
In the future, the shell may provide a way to cancel a wait in progress or treat a suspended job as if it were finished.
Options
None.
Operands
An operand can be a job ID or decimal process ID, specifying which job to wait for. A process ID is a non-negative decimal integer.
If there is no job matching the operand, the built-in assumes that the job has already finished with exit status 127.
Errors
The following error conditions causes the built-in to return a non-zero exit status without waiting for any job:
If the shell receives a signal that has a trap action set, the trap action is executed and the built-in returns immediately.
Exit status
If you specify one or more operands, the built-in returns the exit status of the job specified by the last operand. If there is no operand, the exit status is 0 regardless of the awaited jobs.
If the built-in was interrupted by a signal, the exit status indicates the signal.
The exit status is between 1 and 126 (inclusive) for any other error.
Examples
See The wait utility for an example of using the wait built-in without job control.
Using wait with job control and examining the exit status:
$ set -m
$ sleep 10&
$ kill %
$ wait %
$ echo "Exit status $? corresponds to SIG$(kill -l $?)"
Exit status 399 corresponds to SIGTERM
Subshells cannot wait for jobs in the parent shell environment:
In the above example, wait treats the job % as an unknown job and returns exit status 127.
Compatibility
The wait built-in is specified in POSIX.1-2024.
Many existing shells behave differently on various errors. POSIX requires that an unknown process ID be treated as a process that has already exited with exit status 127, but the behavior for other errors should not be considered portable.