Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The wait command is a POSIX-compliant shell built-in that suspends the execution of the current shell environment until specified child processes (background jobs) terminate. If a specified process has already terminated prior to the invocation of wait, the command does not block; instead, it immediately reaps the cached exit status from the shell’s internal job table. Upon resumption or immediate return, it yields the exit status of the awaited process, allowing the parent shell to synchronize with asynchronous execution threads.

​
Syntax

wait [-fn] [-p varname] [id ...]
  • id: A Process ID (PID) or a job specification (jobspec, e.g., %1). If multiple id arguments are provided, the shell waits for all specified processes to terminate.
  • -n: (Bash 4.3+) Instructs the shell to wait for the next single background job to complete and return its exit status, rather than waiting for a specific job or all jobs.
  • -p varname: (Bash 5.1+) Assigns the PID or jobspec of the process that triggered the return to the variable varname. This is the standard mechanism used to identify exactly which background job terminated when waiting on multiple processes.
  • -f: (Bash 4.4+) Forces wait to block until the specified job actually terminates, ignoring intermediate job control state changes (such as a process being suspended via SIGSTOP).

​
Execution Mechanics

Without Arguments Invoking wait without any id arguments causes the parent shell to block until all currently active background processes invoked by that shell have terminated. When used this way, the exit status of wait is 0, unless the command is interrupted by a signal (such as SIGINT via Ctrl+C), in which case it returns an exit status greater than 128 (e.g., 130). 
command1 &
command2 &
wait
With Specific Arguments When provided with one or more id arguments, the shell blocks until all specified processes terminate. The command relies on the shell’s internal job table to track these processes and retrieve their exit codes, even if they finished before wait was called. 
command1 &
PID1=$!
command2 &
PID2=$!

wait $PID1 $PID2
Using Job Specifications Instead of raw PIDs, wait accepts jobspecs managed by the shell’s job control. 
command1 &
wait %1

​
Exit Status Propagation

The exit status of the wait command is strictly tied to the processes it monitors:
  1. If a single id is specified, wait returns the exact exit status of that child process.
  2. If multiple id arguments are specified, wait returns the exit status of the last id provided in the argument list.
  3. If the specified id does not exist, or is not a child process of the current shell, wait immediately returns an exit status of 127.
  4. If wait is interrupted by a signal, it returns an exit status greater than 128.

​
The -n and -p Flags Behavior

When using wait -n, the shell does not wait for all jobs or a specific job. Instead, it unblocks as soon as any single background job terminates. If wait -n is provided with specific id arguments, it unblocks when the first process among those specific arguments terminates. Because -n returns on the first completed job, the -p varname option is required to programmatically determine which process finished. 
command1 &
PID1=$!
command2 &
PID2=$!

wait -n -p FINISHED_PID $PID1 $PID2
In this execution, wait unblocks as soon as either command1 or command2 completes. The shell populates the FINISHED_PID variable with the exact PID of the terminated process, while the wait command itself returns that process’s exit status.
Master Bash with Deep Grasping Methodology!Learn More