waitpid(3C)                                                Standard C Library Functions                                                waitpid(3C)

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(), wait(3C), or waitid(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 waitpid(), 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.

       One  instance  of  a SIGCHLD signal is queued for each child process whose status has changed. If waitpid() returns because the status of a
       child process is available, and WNOWAIT was not specified in options, any pending SIGCHLD signal associated with the  process  ID  of  that
       child process is discarded. Any other pending SIGCHLD signals remain pending.

       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
       wait.h(3HEAD)  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 continued, is also
                       reported to the calling process.

       WNOHANG         The waitpid() function 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 identi-
                       cal 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. WSTOPPED is a synonym for WUNTRACED.

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 waitpid() returns due to the delivery of a signal to the calling process, -1 is returned and errno is set
       to  EINTR.   If  waitpid() 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, waitpid() is identical to wait(3C).  The waitpid() function is implemented as  a  call
       to the more general waitid(2) function.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Interface Stability          |Standard                     |
       +-----------------------------+-----------------------------+
       |MT-Level                     |Async-Signal-Safe            |
       +-----------------------------+-----------------------------+

SEE ALSO

       intro(2),   exec(2),   exit(2),   fork(2),   pause(2),  sigaction(2),  ptrace(3C),  signal(3C),  siginfo.h(3HEAD),  wait(3C),  waitpid(3C),
       wait.h(3HEAD), attributes(5), standards(5)

SunOS 5.10                                                          19 Jun 2003                                                        waitpid(3C)