waitpid(3p) - phpMan

WAIT(3P)                   POSIX Programmer's Manual                  WAIT(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       wait, waitpid - wait for a child process to stop or terminate
SYNOPSIS
       #include <sys/wait.h>
       pid_t wait(int *stat_loc);
       pid_t waitpid(pid_t pid, int *stat_loc, int options);

DESCRIPTION
       The wait() and waitpid() functions shall obtain status information per-
       taining  to one of the caller's child processes. Various options permit
       status information to be obtained for child processes that have  termi-
       nated  or  stopped.  If status information is available for two or more
       child processes, the order in which their status is reported is unspec-
       ified.
       The wait() function shall suspend execution of the calling thread until
       status information for one of the terminated  child  processes  of  the
       calling  process  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 wait() or wait-
       pid() awaiting termination of the  same  process,  exactly  one  thread
       shall  return the process status at the time of the target process ter-
       mination. If status information is  available  prior  to  the  call  to
       wait(), return shall be immediate.
       The  waitpid()  function shall be equivalent to wait() if the pid argu-
       ment is (pid_t)-1 and the options argument is 0. Otherwise, its  behav-
       ior shall be modified by the values of the pid and options arguments.
       The pid argument specifies a set of child processes for which status is
       requested. The waitpid() function shall only return  the  status  of  a
       child process from this set:
        * If  pid  is  equal  to  (pid_t)-1, status is requested for any child
          process. In this respect, waitpid() is then equivalent to wait().
        * If pid is greater than 0, it specifies the process ID  of  a  single
          child process for which status is requested.
        * If pid is 0, status is requested for any child process whose process
          group ID is equal to that of the calling process.
        * 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.
       The options argument is constructed from the  bitwise-inclusive  OR  of
       zero  or  more  of  the  following  flags,  defined in the <sys/wait.h>
       header:
       WCONTINUED
              The waitpid() function shall report the status of any  continued
              child  process  specified  by  pid  whose  status  has  not been
              reported since it continued from a job control stop.
       WNOHANG
              The waitpid() function shall not suspend execution of the  call-
              ing thread if status is not immediately available for one of the
              child processes specified by pid.
       WUNTRACED
              The status of any child processes  specified  by  pid  that  are
              stopped,  and  whose status has not yet been reported since they
              stopped, shall also be reported to the requesting process.

       If the calling process has SA_NOCLDWAIT  set  or  has  SIGCHLD  set  to
       SIG_IGN,  and the process has no unwaited-for children that were trans-
       formed into zombie processes, the calling thread shall block until  all
       of the children of the process containing the calling thread terminate,
       and wait() and waitpid() shall fail and set errno to [ECHILD].
       If wait() or waitpid() return because the status of a child process  is
       available, these functions shall return a value equal to the process ID
       of the child process. In this  case,  if  the  value  of  the  argument
       stat_loc  is  not  a  null  pointer, information shall be stored in the
       location pointed to by stat_loc.  The  value  stored  at  the  location
       pointed to by stat_loc shall be 0 if and only if the status returned is
       from a terminated child process that terminated by one of the following
       means:
        1. The process returned 0 from main().
        2. The process called _exit() or exit() with a status argument of 0.
        3. The  process  was terminated because the last thread in the process
           terminated.
       Regardless of its value, this information may be interpreted using  the
       following  macros,  which  are  defined in <sys/wait.h> and evaluate to
       integral expressions;  the  stat_val  argument  is  the  integer  value
       pointed to by stat_loc.
       WIFEXITED(stat_val)
              Evaluates to a non-zero value if status was returned for a child
              process that terminated normally.
       WEXITSTATUS(stat_val)
              If the value of  WIFEXITED(stat_val)  is  non-zero,  this  macro
              evaluates  to  the  low-order 8 bits of the status argument that
              the child process passed to _exit() or exit(), or the value  the
              child process returned from main().
       WIFSIGNALED(stat_val)
              Evaluates to a non-zero value if status was returned for a child
              process that terminated due to the receipt of a signal that  was
              not caught (see <signal.h>).
       WTERMSIG(stat_val)
              If  the  value  of WIFSIGNALED(stat_val) is non-zero, this macro
              evaluates to the number of the signal that caused  the  termina-
              tion of the child process.
       WIFSTOPPED(stat_val)
              Evaluates to a non-zero value if status was returned for a child
              process that is currently stopped.
       WSTOPSIG(stat_val)
              If the value of WIFSTOPPED(stat_val)  is  non-zero,  this  macro
              evaluates  to  the  number  of  the signal that caused the child
              process to stop.
       WIFCONTINUED(stat_val)
              Evaluates to a non-zero value if status was returned for a child
              process that has continued from a job control stop.

       It  is unspecified whether the status value returned by calls to wait()
       or waitpid() for processes created by posix_spawn()  or  posix_spawnp()
       can  indicate  a WIFSTOPPED(stat_val) before subsequent calls to wait()
       or waitpid() indicate WIFEXITED(stat_val) as the  result  of  an  error
       detected before the new process image starts executing.
       It  is unspecified whether the status value returned by calls to wait()
       or waitpid() for processes created by posix_spawn()  or  posix_spawnp()
       can  indicate  a  WIFSIGNALED(stat_val) if a signal is sent to the par-
       ent's process group after posix_spawn() or posix_spawnp() is called.
       If the information pointed to by stat_loc was stored by a call to wait-
       pid()  that specified the WUNTRACED flag  and did not specify the WCON-
       TINUED flag,  exactly one of the macros  WIFEXITED(*stat_loc),  WIFSIG-
       NALED(*stat_loc),  and  WIFSTOPPED(*stat_loc)  shall evaluate to a non-
       zero value.
       If the information pointed to by stat_loc was stored by a call to wait-
       pid()  that specified the WUNTRACED  and WCONTINUED  flags, exactly one
       of  the  macros  WIFEXITED(*stat_loc),   WIFSIGNALED(*stat_loc),   WIF-
       STOPPED(*stat_loc),   and  WIFCONTINUED(*stat_loc)  shall evaluate to a
       non-zero value.
       If the information pointed to by stat_loc was stored by a call to wait-
       pid() that did not specify the WUNTRACED  or WCONTINUED  flags, or by a
       call  to  the  wait()  function,  exactly  one  of  the  macros  WIFEX-
       ITED(*stat_loc) and WIFSIGNALED(*stat_loc) shall evaluate to a non-zero
       value.
       If the information pointed to by stat_loc was stored by a call to wait-
       pid()  that did not specify the WUNTRACED flag  and specified the WCON-
       TINUED flag,  or by a call to the wait() function, exactly one  of  the
       macros  WIFEXITED(*stat_loc),  WIFSIGNALED(*stat_loc),   and WIFCONTIN-
       UED(*stat_loc)  shall evaluate to a non-zero value.
       If _POSIX_REALTIME_SIGNALS is defined, and  the  implementation  queues
       the  SIGCHLD  signal,  then  if wait() or waitpid() returns because the
       status of a child process is  available,  any  pending  SIGCHLD  signal
       associated with the process ID of the child process shall be discarded.
       Any other pending SIGCHLD signals shall remain pending.
       Otherwise, if SIGCHLD is blocked, if wait() or waitpid() return because
       the  status of a child process is available, any pending SIGCHLD signal
       shall be cleared unless the status of another child process  is  avail-
       able.
       For  all  other conditions, it is unspecified whether child status will
       be available when a SIGCHLD signal is delivered.
       There may  be  additional  implementation-defined  circumstances  under
       which  wait()  or waitpid() report status.  This shall not occur unless
       the calling process or one of its child processes explicitly makes  use
       of  a  non-standard extension. In these cases the interpretation of the
       reported status is implementation-defined.
       If a parent process terminates without waiting for  all  of  its  child
       processes to terminate, the remaining child processes shall be assigned
       a new parent process ID corresponding to an implementation-defined sys-
       tem process.
RETURN VALUE
       If wait() or waitpid() returns because the status of a child process is
       available, these functions shall return a value equal to the process ID
       of  the  child process for which status is reported. If wait() or wait-
       pid() returns due to the delivery of a signal to the  calling  process,
       -1 shall be returned and errno set to [EINTR]. If waitpid() was invoked
       with WNOHANG set in options, it has at least one child  process  speci-
       fied by pid for which status is not available, and status is not avail-
       able for any process specified  by  pid,  0  is  returned.   Otherwise,
       (pid_t)-1 shall be returned, and errno set to indicate the error.
ERRORS
       The wait() function shall fail if:
       ECHILD The  calling  process  has  no  existing unwaited-for child pro-
              cesses.
       EINTR  The function was interrupted by a signal. The value of the loca-
              tion pointed to by stat_loc is undefined.

       The waitpid() function shall fail if:
       ECHILD The process specified by pid does not exist or is not a child of
              the calling process, or the process group specified by pid  does
              not exist or does not have any member process that is a child of
              the calling process.
       EINTR  The function was interrupted by a signal. The value of the loca-
              tion pointed to by stat_loc is undefined.
       EINVAL The options argument is not valid.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       None.
RATIONALE
       A  call  to  the wait() or waitpid() function only returns status on an
       immediate child process of the calling process; that is, a  child  that
       was  produced  by  a single fork() call (perhaps followed by an exec or
       other function calls) from the parent. If a child  produces  grandchil-
       dren  by  further use of fork(), none of those grandchildren nor any of
       their descendants affect the behavior of a  wait()  from  the  original
       parent  process.   Nothing  in this volume of IEEE Std 1003.1-2001 pre-
       vents an implementation from providing extensions that permit a process
       to  get  status  from  a grandchild or any other process, but a process
       that does not use such extensions must be guaranteed to see status from
       only its direct children.
       The waitpid() function is provided for three reasons:
        1. To support job control
        2. To permit a non-blocking version of the wait() function
        3. To  permit a library routine, such as system() or pclose(), to wait
           for its children without interfering with other terminated children
           for which the process has not waited
       The  first  two  of  these facilities are based on the wait3() function
       provided by 4.3 BSD. The function uses the options argument,  which  is
       equivalent  to an argument to wait3().  The WUNTRACED flag is used only
       in conjunction with job control on systems supporting job control.  Its
       name comes from 4.3 BSD and refers to the fact that there are two types
       of stopped processes in that implementation: processes being traced via
       the ptrace() debugging facility and (untraced) processes stopped by job
       control  signals.  Since  ptrace()  is  not  part  of  this  volume  of
       IEEE Std 1003.1-2001,  only  the second type is relevant. The name WUN-
       TRACED was retained because its usage is the same, even though the name
       is not intuitively meaningful in this context.
       The  third  reason  for the waitpid() function is to permit independent
       sections of a process to spawn and wait for children without  interfer-
       ing  with  each  other.  For  example,  the following problem occurs in
       developing a portable shell, or command interpreter:

              stream = popen("/bin/true");
              (void) system("sleep 100");
              (void) pclose(stream);
       On all historical implementations, the final pclose() fails to reap the
       wait() status of the popen().
       The  status  values  are retrieved by macros, rather than given as spe-
       cific bit encodings as they are in most historical implementations (and
       thus  expected by existing programs). This was necessary to eliminate a
       limitation on the number of signals an implementation can support  that
       was   inherent   in   the   traditional   encodings.   This  volume  of
       IEEE Std 1003.1-2001 does require that a status value  of  zero  corre-
       sponds to a process calling _exit(0), as this is the most common encod-
       ing expected by existing programs. Some of the macro names were adopted
       from 4.3 BSD.
       These  macros syntactically operate on an arbitrary integer value.  The
       behavior is undefined unless that value is one stored by  a  successful
       call  to wait() or waitpid() in the location pointed to by the stat_loc
       argument. An early proposal attempted to make this clearer by  specify-
       ing  each argument as *stat_loc rather than stat_val. However, that did
       not follow the conventions of other specifications in  this  volume  of
       IEEE Std 1003.1-2001  or  traditional usage. It also could have implied
       that the argument to the macro must literally be  *stat_loc;  in  fact,
       that  value  can  be stored or passed as an argument to other functions
       before being interpreted by these macros.
       The extension that affects wait() and waitpid() and is common  in  his-
       torical  implementations  is  the  ptrace() function. It is called by a
       child process and causes that child to stop and return  a  status  that
       appears  identical to the status indicated by WIFSTOPPED. The status of
       ptrace() children is traditionally returned regardless of the WUNTRACED
       flag (or by the wait() function). Most applications do not need to con-
       cern themselves with such extensions because  they  have  control  over
       what  extensions  they  or  their children use.  However, applications,
       such as command interpreters, that invoke arbitrary processes  may  see
       this behavior when those arbitrary processes misuse such extensions.
       Implementations  that  support  core file creation or other implementa-
       tion-defined actions on termination  of  some  processes  traditionally
       provide  a  bit  in the status returned by wait() to indicate that such
       actions have occurred.
       Allowing the wait() family of functions to discard  a  pending  SIGCHLD
       signal  that is associated with a successfully waited-for child process
       puts them into the sigwait() and sigwaitinfo() category with respect to
       SIGCHLD.
       This  definition allows implementations to treat a pending SIGCHLD sig-
       nal as accepted by the process in wait(),  with  the  same  meaning  of
       "accepted"  as  when  that  word  is applied to the sigwait() family of
       functions.
       Allowing the wait() family of functions to behave this way  permits  an
       implementation to be able to deal precisely with SIGCHLD signals.
       In particular, an implementation that does accept (discard) the SIGCHLD
       signal can make the following  guarantees  regardless  of  the  queuing
       depth of signals in general (the list of waitable children can hold the
       SIGCHLD queue):
        1. If a SIGCHLD signal handler is established via sigaction()  without
           the  SA_RESETHAND  flag, SIGCHLD signals can be accurately counted;
           that is, exactly  one  SIGCHLD  signal  will  be  delivered  to  or
           accepted by the process for every child process that terminates.
        2. A single wait() issued from a SIGCHLD signal handler can be guaran-
           teed to return immediately with  status  information  for  a  child
           process.
        3. When  SA_SIGINFO  is  requested,  the SIGCHLD signal handler can be
           guaranteed to receive a non-NULL pointer to a  siginfo_t  structure
           that  describes  a  child process for which a wait via waitpid() or
           waitid() will not block or fail.
        4. The system() function will not cause a process' SIGCHLD handler  to
           be  called as a result of the fork()/ exec executed within system()
           because system() will accept the SIGCHLD signal when it performs  a
           waitpid()  for  its  child process. This is a desirable behavior of
           system() so that it can be used in a library without  causing  side
           effects to the application linked with the library.
       An  implementation  that does not permit the wait() family of functions
       to accept (discard) a pending SIGCHLD signal associated with a success-
       fully  waited-for child, cannot make the guarantees described above for
       the following reasons:
       Guarantee #1
              Although it might  be  assumed  that  reliable  queuing  of  all
              SIGCHLD signals generated by the system can make this guarantee,
              the counter-example is the case of a process that blocks SIGCHLD
              and performs an indefinite loop of fork()/ wait() operations. If
              the implementation supports queued signals, then eventually  the
              system  will run out of memory for the queue. The guarantee can-
              not be made because there must be some limit  to  the  depth  of
              queuing.
       Guarantees #2 and #3
              These cannot be guaranteed unless the wait() family of functions
              accepts the SIGCHLD signal. Otherwise, a fork()/ wait() executed
              while  SIGCHLD  is  blocked  (as  in the system() function) will
              result  in  an  invocation  of  the  handler  when  SIGCHLD   is
              unblocked, after the process has disappeared.
       Guarantee #4
              Although possible to make this guarantee, system() would have to
              set the SIGCHLD handler to SIG_DFL so that  the  SIGCHLD  signal
              generated  by its fork() would be discarded (the SIGCHLD default
              action is to be ignored), then restore it to its  previous  set-
              ting.  This would have the undesirable side effect of discarding
              all SIGCHLD signals pending to the process.

FUTURE DIRECTIONS
       None.
SEE ALSO
       exec(), exit(),  fork(),  waitid(),  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <signal.h>, <sys/wait.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                             WAIT(3P)