1WAIT(2)                       System Calls Manual                      WAIT(2)


6       wait, waitpid, wait4, wait3 - wait for process terminatation


9       #include <sys/types.h>
10       #include <sys/wait.h>
12       pid = wait(status)
13       int pid;
14       union wait *status;
16       #include <sys/time.h>
17       #include <sys/resource.h>
19       pid = waitpid(wpid, status, options);
20       int pid;
21       int wpid;
22       union wait *status;
23       int options;
25       pid = wait3(status, options, rusage);
26       int pid;
27       union wait *status;
28       int options;
29       struct rusage *rusage;
31       pid = wait4(wpid, status, options, rusage);
32       int pid;
33       int wpid;
34       union wait *status;
35       int options;
36       struct rusage *rusage;


39       The  wait function suspends execution of its calling process until sta‐
40       tus information is available for a terminated child process, or a  sig‐
41       nal  is  received.   On  return from a successful wait call, the status
42       area contains termination information about the process that exited  as
43       defined below.
45       The wait4 call provides a more general interface for programs that need
46       to wait for certain child processes,  that  need  resource  utilization
47       statistics  accummulated  by  child processes, or that require options.
48       The other wait functions are implemented using wait4 .
50       The wpid parameter specifies the set of child processes  for  which  to
51       wait.  If wpid is -1, the call waits for any child process.  If wpid is
52       0, the call waits for any child process in the  process  group  of  the
53       caller.   If  wpid is greater than zero, the call waits for the process
54       with process id wpid .  If wpid is less than -1, the call waits for any
55       process whose process group id equals the absolute value of wpid .
57       The  status parameter is defined below.  The options parameter contains
58       the bitwise OR of any of the following options.  The WNOHANG option  is
59       used  to  indicate  that the call should not block if there are no pro‐
60       cesses that wish to report status.  If the  WUNTRACED  option  is  set,
61       children  of  the  current  process that are stopped due to a SIGTTIN ,
62       SIGTTOU , SIGTSTP , or SIGSTOP signal also have their status reported.
64       If rusage is non-zero, a summary of the resources used  by  the  termi‐
65       nated  process  and  all  its children is returned (this information is
66       currently not available for stopped processes).
68       When the WNOHANG option is specified and no processes  wish  to  report
69       status, wait4 returns a process id of 0.
71       The  waitpid  call  is identical to wait4 with an rusage value of zero.
72       The older wait3 call is the same as wait4 with a wpid value of -1.
74       The following macros may be used to test the  manner  of  exit  of  the
75       process.   One  of  the  first three macros will evaluate to a non-zero
76       (true) value:
78       WIFEXITED(status) - True if the process terminated normally by  a  call
79       to _exit(2) or exit(2) .
81       WIFSIGNALED(status)  - True if the process terminated due to receipt of
82       a signal.
84       WIFSTOPPED(status) - True if the process has not  terminated,  but  has
85       stopped  and can be restarted.  This macro can be true only if the wait
86       call specified the WUNTRACED option or if the child  process  is  being
87       traced (see ptrace(2)).
89       Depending  on  the values of those macros, the following macros produce
90       the remaining status information about the child process:
92       WEXITSTATUS(status) - If WIFEXITED(status) is true,  evaluates  to  the
93       low-order  8  bits of the argument passed to _exit(2) or exit(2) by the
94       child.
96       WTERMSIG(status) - If WIFSIGNALED(status) is  true,  evaluates  to  the
97       number of the signal that caused the termination of the process.
99       WCOREDUMP(status)  If WIFSIGNALED(status) is true, evaluates as true if
100       the termination of the process was accompanied by  the  creation  of  a
101       core  file  containing  an  image  of  the  process when the signal was
102       received.
104       WSTOPSIG(status) If WIFSTOPPED(status) is true, evaluates to the number
105       of the signal that caused the process to stop.


108       See  sigvec(2)  for a list of termination signals.  A status of 0 indi‐
109       cates normal termination.
111       If a parent process terminates without waiting for  all  of  its  child
112       processes  to terminate, the remaining child processes are assigned the
113       parent process 1 ID (the init process ID).
115       If a signal is caught while any of the wait calls is pending, the  call
116       may  be  interrupted  or  restarted  when  the  signal-catching routine
117       returns, depending on  the  options  in  effect  for  the  signal;  see
118       intro(2), System call restart.


121       If  wait()  returns  due  to a stopped or terminated child process, the
122       process ID of the child is returned to the calling process.  Otherwise,
123       a value of -1 is returned and errno is set to indicate the error.
125       If wait4(), wait3() or waitpid() returns due to a stopped or terminated
126       child process, the process ID of the child is returned to  the  calling
127       process.   If  there  are  no  children  not  previously awaited, -1 is
128       returned with errno set to [ECHILD].  Otherwise, if WNOHANG  is  speci‐
129       fied and there are no stopped or exited children, 0 is returned.  If an
130       error is detected or a caught signal aborts the call, a value of -1  is
131       returned and errno is set to indicate the error.


134       Wait() will fail and return immediately if:
136       [ECHILD]       The  calling  process has no existing unwaited-for child
137                      processes.
139       [EFAULT]       The status or  rusage  arguments  point  to  an  illegal
140                      address.   (May  not  be detected before exit of a child
141                      process.)
143       [EINTR]        The call was interrupted by a caught signal, or the sig‐
144                      nal had the SV_INTERRUPT flag set.


147       The  wait  and  waitpid functions are defined by POSIX; wait4 and wait3
148       are not specified by POSIX.  The WCOREDUMP macro  and  the  ability  to
149       restart a pending wait call are extensions to the POSIX interface.


152       exit(2)  ,  sigvec(2)  A  wait function call appeared in Version 6 AT&T
153       UNIX.
1574th Berkeley Distribution       March 12, 1993                         WAIT(2)