WAIT(2)
NAME
wait, wait3 − wait for process to terminate
USAGE
#include <sys/wait.h>
pid = wait(status) int pid; union wait *status;
pid = wait(0) int pid;
#include <sys/time.h> #include <sys/resource.h>
pid = wait3(status, options, rusage) int pid; union wait *status; int options; struct rusage *rusage;
DESCRIPTION
Wait forces its caller to delay until a signal is received or until one of its child processes terminates. If any child process has died since the last wait, wait returns immediately and gives the process ID and exit status of one of the terminated children. If there are no children, the caller also returns immediately with the value -1.
Upon return from a successful wait call, status is nonzero, and the high byte of status contains the low byte of the argument to exit supplied by the child process; the low byte of status contains the termination status of the process. A more precise definition of the status word is given in <sys/wait.h>.
Wait3 provides an alternate interface for programs that must not block when collecting the status of child processes. The status parameter is defined as above. The options parameter is one of
WNOHANG the call should not block if there are no processes that wish to report status.
WUNTRACED only children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should have their status reported.
If rusage is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes).
When the WNOHANG option is specified and no processes wish to report status, wait3 returns a PID of zero. The WNOHANG and WUNTRACED options may be combined by OR’ing the two values.
NOTES
See sigvec(2) for a list of termination statuses (signals); zero status indicates normal termination. A special status (0177) is returned for a stopped process that has not terminated and can be restarted.
If the parent process terminates without waiting on its children, the children become orphans. On DOMAIN Systems, the parent process ID of all orphan processes is set to that of the Display Manager (process 1), even though no real parent-child relationship exists between the two (e.g., the DM cannot be made to wait on these “children”).
Wait and wait3 are automatically restarted when a process receives a signal while awaiting termination of a child process.
RETURN VALUE
If wait returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, -1 is returned and errno is set to indicate the error.
Wait3 returns -1 if there are no children not previously waited for. It returns zero if WNOHANG is specified and there are no stopped or exited children.
ERRORS
Wait will fail and return immediately if one or more of the following are true:
[ECHILD] The calling process has no existing unwaited-for child processes.
[EFAULT] The status or rusage arguments point to an illegal address.