WAIT(2)                              BSD                               WAIT(2)



NAME
     wait, wait3 - wait for process to terminate

SYNOPSIS
     #include <sys/wait.h>

     pid = wait(status)
     int pid;
     union wait *status;

     #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 causes its caller to delay until a signal is received or 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, wait
     returns immediately with the value -1.

     On return from a successful wait call, status is nonzero.  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 the following:

     WNOHANG     The call should not block if there are no processes that wish
                 to report status.

     WUNTRACED   Children of the current process that are stopped due to a
                 SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should also have
                 their status reported.

     If rusage is nonzero, 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 0.  The WNOHANG and WUNTRACED options can
     be combined by ORing the two values.

     Passing a null pointer to wait or wait3 results in the usual behavior,
     with the exception that no status is returned.

ERRORS
     wait will fail and return immediately if one or both 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.

SEE ALSO
     exit(2)

DIAGNOSTICS
     If wait returns due to a stopped or terminated child process, the process
     ID of the child is returned to the calling process.  Otherwise, a value
     of -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 0 if WNOHANG is specified and there are no stopped or exited
     children.

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 (see
     ptrace(2)).  If the 0200 bit of the termination status is set, a core
     image of the process was produced by the system.  (Since Domain/OS BSD
     doesn't produce core images, this bit has no meaning in that
     environment.)

     If the parent process terminates without waiting on its children, the
     initialization process (process ID = 1) inherits the children.

     wait and wait3 are automatically restarted when a process receives a
     signal while awaiting termination of a child process.