wait(2)

NAME

     wait - wait for child process to stop or terminate

SYNOPSIS

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

     pid_t wait(int *stat_loc);

DESCRIPTION

     The wait() 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  wait()  or waitpid(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 wait(),
     return will be immediate.

     If wait() returns because the status of a child  process  is
     available,  it  returns the process ID of the child process.
     If the  calling  process  specified  a  non-zero  value  for
     stat_loc,  the  status of the child process is stored in the
     location  pointed  to  by  stat_loc.  That  status  may   be
     evaluated  with  the  macros  described  on  the wstat(3XFN)
     manual page.

     In the  following,  status  is  the  object  pointed  to  by
     stat_loc:

        o  If the child process stopped, the high order 8 bits of
           status  will  contain  the  number  of the signal that
           caused the process to stop and the low  order  8  bits
           will be set equal to WSTOPFLG.

        o  If the child process  terminated  due  to  an  _exit()
           call, the low order 8 bits of status will be 0 and the
           high order 8 bits will contain the low order 8 bits of
           the argument that the child process passed to _exit();
           see exit(2).

        o  If the child process terminated due to a  signal,  the
           high  order  8  bits  of  status will be 0 and the low
           order 8 bits will contain the  number  of  the  signal
           that caused the termination. In addition, if  WCOREFLG
           is set, a "core image" will have been   produced;  see
           signal(3HEAD) and wstat(3XFN).

     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 wait() will fail
     and set errno to ECHILD.

     If a parent process terminates without waiting for its child
     processes  to terminate, the parent process ID of each child
     process is set to 1, with the initialization process  inher-
     iting the child processes; see intro(2).

RETURN VALUES

     When wait() returns due to a terminated child  process,  the
     process  ID of the child is returned to the calling process.
     Otherwise, -1 is returned and errno is set to  indicate  the
     error.

ERRORS

     The wait() function will fail if:

     ECHILD
           The calling process has no existing unwaited-for child
           processes.

     EINTR The function was interrupted by a signal.

USAGE

     Since wait() blocks on a stopped child,  a  calling  process
     wishing  to see the return results of such a call should use
     waitid(2) or waitpid(2) instead of wait().

ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO

     intro(2), exec(2), exit(2),  fork(2),  pause(2),  ptrace(2),
     waitid(2),     waitpid(2),     signal(3C),    attributes(5),
     signal(3HEAD), wstat(3XFN)