WAIT(2)                              SysV                              WAIT(2)



NAME
     wait, waitpid - Wait for a child process to stop or terminate

SYNOPSIS
     #include <sys/types.h>
     #include <sys/wait.h>

     pid_t wait (status_location)
     int *status_location;

     pid_t waitpid (process_id, status_location, options)
     pid_t process_id;
     int *status_location, options;


DESCRIPTION
     The wait and waitpid functions allow the calling process to obtain status
     information on one of its child processes. Various options permit status
     information to be obtained for child processes that have terminated or
     stopped. If status information is available for two or more child
     processes, the order in which their status is reported is unspecified.

     The wait function suspends the calling process until it receives status
     information for one of the calling process' child processes. The wait
     function returns without waiting if a child process that has not been
     waited for has already stopped or terminated prior to the call.

     The waitpid function behaves identically to the wait function if the
     process_id argument has a value of -1 and the options argument has a
     value of 0 (zero).  Otherwise, its behavior is modified by the values of
     the process_id and options arguments.

     The process_id argument allows the calling process to gather status from
     a specific set of child processes for which status is requested.  The
     waitpid function will only return the status of a child process from this
     set.

     +    If the process_id argument is equal to -1, status is requested for
          any child process.  In this respect, the waitpid function is
          equivalent to the wait function.

     +    If the process_id argument is greater than 0 (zero), it specifies
          the process ID of a single child process for which status is
          requested.

     +    If the process_id argument is equal to 0 (zero), status is requested
          for any child process whose process group ID is equal to that of the
          calling process.

     +    If the process_id argument is less than -1, status is requested for
          any child process whose process group ID is equal to the absolute
          value of the process_id argument.

     The options argument to the waitpid function modifies the behavior of the
     function.  Two values are defined, WNOHANG and WUNTRACED, which can be
     combined by specifying their bitwise-inclusive OR. The WNOHANG option
     prevents the calling process from being suspended even if there are child
     processes to wait for.  In this case, 0 (zero) is returned indicating
     that there are no child processes that have stopped or terminated.  If
     the WUNTRACED option is set, the call also returns information when child
     processes of the current process are stopped.

     If the wait, or waitpid, function returns because the status of a child
     process is available, they return the process ID of the child process.
     In this case, if the status_location argument is not null, information
     will be stored in the location pointed to by status_location.

     The value stored at the location pointed to by status_location is 0
     (zero) if and only if the status returned is from a terminated child
     process that returned 0 (zero) from the main() routine, or passed 0
     (zero) as the status argument to the _exit(2) or exit(2) function.

     Regardless of its value, this information can be interpreted using the
     following macros, which are defined in the sys/wait.h header file and
     evaluate to integral expressions; the status_value argument is the
     integer value pointed to by status_location.

     WIFEXITED(status_value)
          Evaluates to a nonzero value if status was returned for a child
          process that terminated normally.

     WEXITSTATUS(status_value)
          If the value of WIFEXITED(status_value) is nonzero, this macro
          evaluates to the low-order 8 bits of the status argument that the
          child process passed to the _exit or exit functions, or the value
          the child process returned from the main routine.

     WIFSIGNALED(status_value)
          Evaluates to nonzero value if status was returned for a child
          process that terminated due to the receipt of a signal that was not
          caught.

     WTERMSIG(status_value)
          If the value of WIFSIGNALED(status_value) is nonzero, this macro
          evaluates to the number of the signal that caused the termination of
          the child process.

     WIFSTOPPED(status_value)
          Evaluates to a nonzero value if status was returned for a child
          process that is currently stopped.

     WSTOPSIG(status_value)
          If the value of WIFSTOPPED(status_value) is nonzero, this macro
          evaluates to the number of the signal that caused the child process
          to stop.

     If the information stored at the location pointed to by the
     status_location argument was stored there by a call to the waitpid
     function that specified the WUNTRACED flag, exactly one of the
     WIFEXITED(*status_location), WIFSIGNALED(*status_location), and
     WIFSTOPPED(*status_location) macros will evaluate to a nonzero value.  If
     the information stored at the location pointed to by the status_location
     function was stored there by a call to waitpid that did not specify the
     WUNTRACED flag or by a call to the wait function, exactly one of the
     WIFEXITED(*status_location) and WIFSIGNALED(*status_location) macros will
     evaluate to a nonzero value.

     If a parent process terminates without waiting for its child processes to
     terminate, the parent process ID of each child process is set to 1. This
     means the initialization process inherits the child processes (see
     intro(2))

DIAGNOSTICS
     If the wait or waitpid function returns because the status of a child
     process is available, the process ID of the child is returned to the
     calling process. If they return because a signal was caught by the
     calling process, -1 is returned and errno is set to [EINTR].

     If the WNOHANG option was specified, and there are no stopped or exited
     child processes, the waitpid function return a value of 0 (zero).
     Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS
     If one of the following occur, the wait function returns -1 and sets
     errno to one of the following values:

     [ECHILD]  The calling process has no existing unwaited-for child
               processes.

     [EINTR]   The function was terminated by receipt of a signal.

     If one of the following occur, the waitpid function returns -1 and sets
     errno to one of the following values:

     [ECHILD]  The process or process group ID specified by the process_id
               argument does not exist or is not a child process of the
               calling process.

     [EINVAL]  The value of the options argument is not valid.

     [EINTR]   The function was terminated by receipt of a signal.

SEE ALSO
     exec(2), exit(2), fork(2), pause(3), sigaction(3)