waitpid(2)

NAME

     waitpid - wait for child process to change state

SYNOPSIS

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

     pid_t waitpid(pid_t pid, int *stat_loc, int options);

DESCRIPTION

     The waitpid() function will suspend execution of the calling
     thread  until  status  information for one of its terminated
     child processes is available, or until delivery of a  signal
     whose action is either to execute a signal-catching function
     or to terminate the process. If  more  than  one  thread  is
     suspended  in  waitpid()  or wait(2) awaiting termination of
     the same process, exactly one thread will return the process
     status  at  the  time  of the target process termination. If
     status information is available prior to the call  to  wait-
     pid(), return will be immediate.

     The pid argument specifies a  set  of  child  processes  for
     which status is requested, as follows:

        o  If  pid is equal to (pid_t)-1, status is requested for
           any child process.

     If  pid is greater than (pid_t)0, it specifies  the  process
     ID of the child process for which status is requested.

        o  If  pid is equal to (pid_t)0 status is  requested  for
           any  child process whose process group  ID is equal to
           that of the calling process.

        o  If pid is less than (pid_t)-1, status is requested for
           any  child process whose process group  ID is equal to
           the absolute value of pid.

     If the calling process has SA_NOCLDWAIT set or  has  SIGCHLD
     set to SIG_IGN and the process has no unwaited children that
     were transformed into zombie processes, it will block  until
     all  of  its children terminate, and waitpid() will fail and
     set errno to ECHILD.

     If waitpid() returns because the status of a  child  process
     is  available,  then  that  status may be evaluated with the
     macros defined by wstat(3XFN) If  the  calling  process  had
     specified  a  non-zero  value of stat_loc, the status of the
     child process will be stored in the location pointed  to  by
     stat_loc.

     The  options  argument  is  constructed  from  the   bitwise
     inclusive OR of zero or more of the following flags, defined
     in the header  <sys/wait.h>:

     WCONTINUED
           The status of any continued child process specified by
           pid,  whose status has not been reported since it con-
           tinued, is also reported to the calling process.

     WNOHANG
           waitpid() will not suspend execution  of  the  calling
           process if status is not immediately available for one
           of the child processes specified by  pid.

     WNOWAIT
           Keep the process whose status is returned in  stat_loc
           in  a  waitable  state.  The process may be waited for
           again with identical results.

     WUNTRACED
           The status of any child  processes  specified  by  pid
           that  are  stopped,  and whose status has not yet been
           reported since they stopped, is also reported  to  the
           calling process.

RETURN VALUES

     If waitpid() returns because the status of a  child  process
     is available,  it returns a value equal to the process ID of
     the child process for which status is  reported.   If  wait-
     pid() returns due to the delivery of a signal to the calling
     process, -1 is returned and errno is set to EINTR.  If wait-
     pid()  was  invoked  with  WNOHANG set in options, it has at
     least one child process specified by pid for which status is
     not  available,  and status is not available for any process
     specified by pid, then 0  is  returned.   Otherwise,  -1  is
     returned and errno is set to indicate the error.

ERRORS

     The waitpid() function will fail if:

     ECHILD
           The process or process group specified by pid does not
           exist  or is not a child of the calling process or can
           never be in the states specified by options.

     EINTR The waitpid() function  was  interrupted  due  to  the
           receipt of a signal sent by the calling process.

     EINVAL
           An invalid value was specified for options.

USAGE

     With options equal to 0 and  pid equal to  (pid_t)-1,  wait-
     pid() is identical to  wait(2).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO

     intro(2), exec(2), exit(2),  fork(2),  pause(2),  ptrace(2),
     sigaction(2),     wait(2),     signal(3C),    attributes(5),
     siginfo(3HEAD), wstat(3XFN)