wait, waitpid - wait for process termination


SYNOPSIS

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

       pid_t wait(int *status)
       pid_t waitpid(pid_t pid, int *status, int options);


DESCRIPTION

       The  wait  function suspends execution of the current pro­
       cess until a child has exited, or until a signal is deliv­
       ered  whose  action is to terminate the current process or
       to call a  signal  handling  function.   If  a  child  has
       already  exited by the time of the call (a so-called "zom­
       bie" process), the function returns immediately.  Any sys­
       tem resources used by the child are freed.

       The  waitpid  function  suspends  execution of the current
       process until a child as specified by the pid argument has
       exited,  or until a signal is delivered whose action is to
       terminate the current process or to call a signal handling
       function.   If  a  child  as  requested by pid has already
       exited by the time of the call (a so-called "zombie"  pro­
       cess),  the  function  returns  immediately.   Any  system
       resources used by the child are freed.

       The value of pid can be one of:

       < -1   which means to wait for  any  child  process  whose
              process  group ID is equal to the absolute value of
              pid.

       -1     which means to wait for any child process; this  is
              the same behaviour which wait exhibits.

       0      which  means  to  wait  for any child process whose
              process group ID is equal to that  of  the  calling
              process.

       > 0    which  means to wait for the child whose process ID
              is equal to the value of pid.

       The value of options is an OR of zero or more of the  fol­
       lowing constants:

       WNOHANG
              which  means  to return immediately if no child has
              exited.

       WUNTRACED
              which means to also return for children  which  are
              stopped, and whose status has not been reported.

       mation in the location pointed to by status.

       This status can be evaluated  with  the  following  macros
       (these macros take the stat buffer (an int) as an argument
       -- not a pointer to the buffer!):

       WIFEXITED(status)
              is non-zero if the child exited normally.

       WEXITSTATUS(status)
              evaluates to the least significant  eight  bits  of
              the  return  code  of  the  child which terminated,
              which may have been set as the argument to  a  call
              to exit() or as the argument for a return statement
              in the main program.  This macro can only be evalu­
              ated if WIFEXITED returned non-zero.

       WIFSIGNALED(status)
              returns true if the child process exited because of
              a signal which was not caught.

       WTERMSIG(status)
              returns the number of the signal  that  caused  the
              child  process to terminate. This macro can only be
              evaluated if WIFSIGNALED returned non-zero.

       WIFSTOPPED(status)
              returns true if the child process which caused  the
              return  is currently stopped; this is only possible
              if the call was done using WUNTRACED.

       WSTOPSIG(status)
              returns the number of the signal which  caused  the
              child to stop.  This macro can only be evaluated if
              WIFSTOPPED returned non-zero.

       Some versions of Unix (e.g. Linux, Solaris, but  not  AIX,
       SunOS)  also  define  a  macro  WCOREDUMP(status)  to test
       whether the child  process  dumped  core.  Only  use  this
       enclosed in #ifdef WCOREDUMP ... #endif.


RETURN VALUE

       The  process ID of the child which exited, or zero if WNO­
       HANG was used and no child was available, or -1  on  error
       (in which case errno is set to an appropriate value).


ERRORS

       ECHILD if  the  process specified in pid does not exist or
              is not a child of the calling process.   (This  can
              happen  for  one's  own  child  if  the  action for
              SIGCHLD is set to SIG_IGN. See also the NOTES  sec­
              tion about threads.)


       ERESTARTSYS
              if WNOHANG was not set and an unblocked signal or a
              SIGCHLD was caught. This error is returned  by  the
              system  call.  The library interface is not allowed
              to return ERESTARTSYS, but will return EINTR.


NOTES

       The Single Unix Specification describes a  flag  SA_NOCLD­
       WAIT  (not  present  under Linux) such that if either this
       flag is set, or the action for SIGCHLD is set  to  SIG_IGN
       (which,  by  the way, is not allowed by POSIX), then chil­
       dren that exit do not become zombies and a call to  wait()
       or  waitpid()  will  block until all children have exited,
       and then fail with errno set to ECHILD.

       In the Linux kernel, a kernel-scheduled thread  is  not  a
       distinct  construct  from  a process. Instead, a thread is
       simply a process that is created  using  the  Linux-unique
       clone(2)  system call; other routines such as the portable
       pthread_create(3) call  are  implemented  using  clone(2).
       Thus,  if  two threads A and B are siblings, then thread A
       cannot wait on any processes forked by  thread  B  or  its
       descendents,  because an uncle cannot wait on his nephews.
       In some other Unix-like systems,  where  multiple  threads
       are implemented as belonging to a single process, thread A
       can wait on any processes forked by sibling thread B;  you
       will  have  to rewrite any code that makes this assumption
       for it to work on Linux.


CONFORMING TO

       SVr4, POSIX.1


SEE ALSO

       clone(2),  signal(2),  wait4(2),  pthread_create(3),  sig­
       nal(7)


Man(1) output converted with man2html