Manual Pages for UNIX Operating System command usage for man waitpid

Standard C Library Functions                          waitpid(3C)



NAME
     waitpid - wait for child process to change state

SYNOPSIS
     #include 
     #include 

     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 ter-
     mination of the same process, exactly one thread will return
     the  process status at the time of the target process termi-
     nation. 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 less than (pid_t)-1, status is  requested
              for  any  child  process whose process group  ID is
              equal to the absolute value of pid.

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

         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 greater than (pid_t)0, it specifies  the
              process ID of the child process for which status is
              requested.


     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 pend-
     ing.






SunOS 5.11           Last change: 7 Dec 2007                    1






Standard C Library Functions                          waitpid(3C)



     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  :

     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 execu-
                   tion  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. 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  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



SunOS 5.11           Last change: 7 Dec 2007                    2






Standard C Library Functions                          waitpid(3C)



     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(3C). The waitpid() function is
     implemented as a call to the more  general  waitid(2)  func-
     tion.

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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


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









SunOS 5.11           Last change: 7 Dec 2007                    3