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

       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.


RETURN VALUE

       The process ID of the child which exited, -1 on  error  or
       zero  if  WNOHANG  was used and no child was available (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.)

       EINVAL if the options argument was invalid.

       ERESTARTSYS
              if WNOHANG was not set and an unblocked signal or a
              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)