1WAIT(3P)                   POSIX Programmer's Manual                  WAIT(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       wait, waitpid - wait for a child process to stop or terminate
13

SYNOPSIS

15       #include <sys/wait.h>
16
17       pid_t wait(int *stat_loc);
18       pid_t waitpid(pid_t pid, int *stat_loc, int options);
19
20

DESCRIPTION

22       The wait() and waitpid() functions shall obtain status information per‐
23       taining  to one of the caller's child processes. Various options permit
24       status information to be obtained for child processes that have  termi‐
25       nated  or  stopped.  If status information is available for two or more
26       child processes, the order in which their status is reported is unspec‐
27       ified.
28
29       The wait() function shall suspend execution of the calling thread until
30       status information for one of the terminated  child  processes  of  the
31       calling  process  is  available,  or  until  delivery of a signal whose
32       action is either to execute a signal-catching function or to  terminate
33       the  process.  If  more than one thread is suspended in wait() or wait‐
34       pid() awaiting termination of the  same  process,  exactly  one  thread
35       shall  return the process status at the time of the target process ter‐
36       mination. If status information is  available  prior  to  the  call  to
37       wait(), return shall be immediate.
38
39       The  waitpid()  function shall be equivalent to wait() if the pid argu‐
40       ment is (pid_t)-1 and the options argument is 0. Otherwise, its  behav‐
41       ior shall be modified by the values of the pid and options arguments.
42
43       The pid argument specifies a set of child processes for which status is
44       requested. The waitpid() function shall only return  the  status  of  a
45       child process from this set:
46
47        * If  pid  is  equal  to  (pid_t)-1, status is requested for any child
48          process. In this respect, waitpid() is then equivalent to wait().
49
50        * If pid is greater than 0, it specifies the process ID  of  a  single
51          child process for which status is requested.
52
53        * If pid is 0, status is requested for any child process whose process
54          group ID is equal to that of the calling process.
55
56        * If pid is less than (pid_t)-1, status is  requested  for  any  child
57          process  whose  process  group  ID is equal to the absolute value of
58          pid.
59
60       The options argument is constructed from the  bitwise-inclusive  OR  of
61       zero  or  more  of  the  following  flags,  defined in the <sys/wait.h>
62       header:
63
64       WCONTINUED
65              The waitpid() function shall report the status of any  continued
66              child  process  specified  by  pid  whose  status  has  not been
67              reported since it continued from a job control stop.
68
69       WNOHANG
70              The waitpid() function shall not suspend execution of the  call‐
71              ing thread if status is not immediately available for one of the
72              child processes specified by pid.
73
74       WUNTRACED
75              The status of any child processes  specified  by  pid  that  are
76              stopped,  and  whose status has not yet been reported since they
77              stopped, shall also be reported to the requesting process.
78
79
80       If the calling process has SA_NOCLDWAIT  set  or  has  SIGCHLD  set  to
81       SIG_IGN,  and the process has no unwaited-for children that were trans‐
82       formed into zombie processes, the calling thread shall block until  all
83       of the children of the process containing the calling thread terminate,
84       and wait() and waitpid() shall fail and set errno to [ECHILD].
85
86       If wait() or waitpid() return because the status of a child process  is
87       available, these functions shall return a value equal to the process ID
88       of the child process. In this  case,  if  the  value  of  the  argument
89       stat_loc  is  not  a  null  pointer, information shall be stored in the
90       location pointed to by stat_loc.  The  value  stored  at  the  location
91       pointed to by stat_loc shall be 0 if and only if the status returned is
92       from a terminated child process that terminated by one of the following
93       means:
94
95        1. The process returned 0 from main().
96
97        2. The process called _exit() or exit() with a status argument of 0.
98
99        3. The  process  was terminated because the last thread in the process
100           terminated.
101
102       Regardless of its value, this information may be interpreted using  the
103       following  macros,  which  are  defined in <sys/wait.h> and evaluate to
104       integral expressions;  the  stat_val  argument  is  the  integer  value
105       pointed to by stat_loc.
106
107       WIFEXITED(stat_val)
108
109              Evaluates to a non-zero value if status was returned for a child
110              process that terminated normally.
111
112       WEXITSTATUS(stat_val)
113
114              If the value of  WIFEXITED(stat_val)  is  non-zero,  this  macro
115              evaluates  to  the  low-order 8 bits of the status argument that
116              the child process passed to _exit() or exit(), or the value  the
117              child process returned from main().
118
119       WIFSIGNALED(stat_val)
120
121              Evaluates to a non-zero value if status was returned for a child
122              process that terminated due to the receipt of a signal that  was
123              not caught (see <signal.h>).
124
125       WTERMSIG(stat_val)
126
127              If  the  value  of WIFSIGNALED(stat_val) is non-zero, this macro
128              evaluates to the number of the signal that caused  the  termina‐
129              tion of the child process.
130
131       WIFSTOPPED(stat_val)
132
133              Evaluates to a non-zero value if status was returned for a child
134              process that is currently stopped.
135
136       WSTOPSIG(stat_val)
137
138              If the value of WIFSTOPPED(stat_val)  is  non-zero,  this  macro
139              evaluates  to  the  number  of  the signal that caused the child
140              process to stop.
141
142       WIFCONTINUED(stat_val)
143
144              Evaluates to a non-zero value if status was returned for a child
145              process that has continued from a job control stop.
146
147
148       It  is unspecified whether the status value returned by calls to wait()
149       or waitpid() for processes created by posix_spawn()  or  posix_spawnp()
150       can  indicate  a WIFSTOPPED(stat_val) before subsequent calls to wait()
151       or waitpid() indicate WIFEXITED(stat_val) as the  result  of  an  error
152       detected before the new process image starts executing.
153
154       It  is unspecified whether the status value returned by calls to wait()
155       or waitpid() for processes created by posix_spawn()  or  posix_spawnp()
156       can  indicate  a  WIFSIGNALED(stat_val) if a signal is sent to the par‐
157       ent's process group after posix_spawn() or posix_spawnp() is called.
158
159       If the information pointed to by stat_loc was stored by a call to wait‐
160       pid()  that specified the WUNTRACED flag  and did not specify the WCON‐
161       TINUED flag,  exactly one of the macros  WIFEXITED(*stat_loc),  WIFSIG‐
162       NALED(*stat_loc),  and  WIFSTOPPED(*stat_loc)  shall evaluate to a non-
163       zero value.
164
165       If the information pointed to by stat_loc was stored by a call to wait‐
166       pid()  that specified the WUNTRACED  and WCONTINUED  flags, exactly one
167       of  the  macros  WIFEXITED(*stat_loc),   WIFSIGNALED(*stat_loc),   WIF‐
168       STOPPED(*stat_loc),   and  WIFCONTINUED(*stat_loc)  shall evaluate to a
169       non-zero value.
170
171       If the information pointed to by stat_loc was stored by a call to wait‐
172       pid() that did not specify the WUNTRACED  or WCONTINUED  flags, or by a
173       call  to  the  wait()  function,  exactly  one  of  the  macros  WIFEX‐
174       ITED(*stat_loc) and WIFSIGNALED(*stat_loc) shall evaluate to a non-zero
175       value.
176
177       If the information pointed to by stat_loc was stored by a call to wait‐
178       pid()  that did not specify the WUNTRACED flag  and specified the WCON‐
179       TINUED flag,  or by a call to the wait() function, exactly one  of  the
180       macros  WIFEXITED(*stat_loc),  WIFSIGNALED(*stat_loc),   and WIFCONTIN‐
181       UED(*stat_loc)  shall evaluate to a non-zero value.
182
183       If _POSIX_REALTIME_SIGNALS is defined, and  the  implementation  queues
184       the  SIGCHLD  signal,  then  if wait() or waitpid() returns because the
185       status of a child process is  available,  any  pending  SIGCHLD  signal
186       associated with the process ID of the child process shall be discarded.
187       Any other pending SIGCHLD signals shall remain pending.
188
189       Otherwise, if SIGCHLD is blocked, if wait() or waitpid() return because
190       the  status of a child process is available, any pending SIGCHLD signal
191       shall be cleared unless the status of another child process  is  avail‐
192       able.
193
194       For  all  other conditions, it is unspecified whether child status will
195       be available when a SIGCHLD signal is delivered.
196
197       There may  be  additional  implementation-defined  circumstances  under
198       which  wait()  or waitpid() report status.  This shall not occur unless
199       the calling process or one of its child processes explicitly makes  use
200       of  a  non-standard extension. In these cases the interpretation of the
201       reported status is implementation-defined.
202
203       If a parent process terminates without waiting for  all  of  its  child
204       processes to terminate, the remaining child processes shall be assigned
205       a new parent process ID corresponding to an implementation-defined sys‐
206       tem process.
207

RETURN VALUE

209       If wait() or waitpid() returns because the status of a child process is
210       available, these functions shall return a value equal to the process ID
211       of  the  child process for which status is reported. If wait() or wait‐
212       pid() returns due to the delivery of a signal to the  calling  process,
213       -1 shall be returned and errno set to [EINTR]. If waitpid() was invoked
214       with WNOHANG set in options, it has at least one child  process  speci‐
215       fied by pid for which status is not available, and status is not avail‐
216       able for any process specified  by  pid,  0  is  returned.   Otherwise,
217       (pid_t)-1 shall be returned, and errno set to indicate the error.
218

ERRORS

220       The wait() function shall fail if:
221
222       ECHILD The  calling  process  has  no  existing unwaited-for child pro‐
223              cesses.
224
225       EINTR  The function was interrupted by a signal. The value of the loca‐
226              tion pointed to by stat_loc is undefined.
227
228
229       The waitpid() function shall fail if:
230
231       ECHILD The process specified by pid does not exist or is not a child of
232              the calling process, or the process group specified by pid  does
233              not exist or does not have any member process that is a child of
234              the calling process.
235
236       EINTR  The function was interrupted by a signal. The value of the loca‐
237              tion pointed to by stat_loc is undefined.
238
239       EINVAL The options argument is not valid.
240
241
242       The following sections are informative.
243

EXAMPLES

245       None.
246

APPLICATION USAGE

248       None.
249

RATIONALE

251       A  call  to  the wait() or waitpid() function only returns status on an
252       immediate child process of the calling process; that is, a  child  that
253       was  produced  by  a single fork() call (perhaps followed by an exec or
254       other function calls) from the parent. If a child  produces  grandchil‐
255       dren  by  further use of fork(), none of those grandchildren nor any of
256       their descendants affect the behavior of a  wait()  from  the  original
257       parent  process.   Nothing  in this volume of IEEE Std 1003.1-2001 pre‐
258       vents an implementation from providing extensions that permit a process
259       to  get  status  from  a grandchild or any other process, but a process
260       that does not use such extensions must be guaranteed to see status from
261       only its direct children.
262
263       The waitpid() function is provided for three reasons:
264
265        1. To support job control
266
267        2. To permit a non-blocking version of the wait() function
268
269        3. To  permit a library routine, such as system() or pclose(), to wait
270           for its children without interfering with other terminated children
271           for which the process has not waited
272
273       The  first  two  of  these facilities are based on the wait3() function
274       provided by 4.3 BSD. The function uses the options argument,  which  is
275       equivalent  to an argument to wait3().  The WUNTRACED flag is used only
276       in conjunction with job control on systems supporting job control.  Its
277       name comes from 4.3 BSD and refers to the fact that there are two types
278       of stopped processes in that implementation: processes being traced via
279       the ptrace() debugging facility and (untraced) processes stopped by job
280       control  signals.  Since  ptrace()  is  not  part  of  this  volume  of
281       IEEE Std 1003.1-2001,  only  the second type is relevant. The name WUN‐
282       TRACED was retained because its usage is the same, even though the name
283       is not intuitively meaningful in this context.
284
285       The  third  reason  for the waitpid() function is to permit independent
286       sections of a process to spawn and wait for children without  interfer‐
287       ing  with  each  other.  For  example,  the following problem occurs in
288       developing a portable shell, or command interpreter:
289
290
291              stream = popen("/bin/true");
292              (void) system("sleep 100");
293              (void) pclose(stream);
294
295       On all historical implementations, the final pclose() fails to reap the
296       wait() status of the popen().
297
298       The  status  values  are retrieved by macros, rather than given as spe‐
299       cific bit encodings as they are in most historical implementations (and
300       thus  expected by existing programs). This was necessary to eliminate a
301       limitation on the number of signals an implementation can support  that
302       was   inherent   in   the   traditional   encodings.   This  volume  of
303       IEEE Std 1003.1-2001 does require that a status value  of  zero  corre‐
304       sponds to a process calling _exit(0), as this is the most common encod‐
305       ing expected by existing programs. Some of the macro names were adopted
306       from 4.3 BSD.
307
308       These  macros syntactically operate on an arbitrary integer value.  The
309       behavior is undefined unless that value is one stored by  a  successful
310       call  to wait() or waitpid() in the location pointed to by the stat_loc
311       argument. An early proposal attempted to make this clearer by  specify‐
312       ing  each argument as *stat_loc rather than stat_val. However, that did
313       not follow the conventions of other specifications in  this  volume  of
314       IEEE Std 1003.1-2001  or  traditional usage. It also could have implied
315       that the argument to the macro must literally be  *stat_loc;  in  fact,
316       that  value  can  be stored or passed as an argument to other functions
317       before being interpreted by these macros.
318
319       The extension that affects wait() and waitpid() and is common  in  his‐
320       torical  implementations  is  the  ptrace() function. It is called by a
321       child process and causes that child to stop and return  a  status  that
322       appears  identical to the status indicated by WIFSTOPPED. The status of
323       ptrace() children is traditionally returned regardless of the WUNTRACED
324       flag (or by the wait() function). Most applications do not need to con‐
325       cern themselves with such extensions because  they  have  control  over
326       what  extensions  they  or  their children use.  However, applications,
327       such as command interpreters, that invoke arbitrary processes  may  see
328       this behavior when those arbitrary processes misuse such extensions.
329
330       Implementations  that  support  core file creation or other implementa‐
331       tion-defined actions on termination  of  some  processes  traditionally
332       provide  a  bit  in the status returned by wait() to indicate that such
333       actions have occurred.
334
335       Allowing the wait() family of functions to discard  a  pending  SIGCHLD
336       signal  that is associated with a successfully waited-for child process
337       puts them into the sigwait() and sigwaitinfo() category with respect to
338       SIGCHLD.
339
340       This  definition allows implementations to treat a pending SIGCHLD sig‐
341       nal as accepted by the process in wait(),  with  the  same  meaning  of
342       "accepted"  as  when  that  word  is applied to the sigwait() family of
343       functions.
344
345       Allowing the wait() family of functions to behave this way  permits  an
346       implementation to be able to deal precisely with SIGCHLD signals.
347
348       In particular, an implementation that does accept (discard) the SIGCHLD
349       signal can make the following  guarantees  regardless  of  the  queuing
350       depth of signals in general (the list of waitable children can hold the
351       SIGCHLD queue):
352
353        1. If a SIGCHLD signal handler is established via sigaction()  without
354           the  SA_RESETHAND  flag, SIGCHLD signals can be accurately counted;
355           that is, exactly  one  SIGCHLD  signal  will  be  delivered  to  or
356           accepted by the process for every child process that terminates.
357
358        2. A single wait() issued from a SIGCHLD signal handler can be guaran‐
359           teed to return immediately with  status  information  for  a  child
360           process.
361
362        3. When  SA_SIGINFO  is  requested,  the SIGCHLD signal handler can be
363           guaranteed to receive a non-NULL pointer to a  siginfo_t  structure
364           that  describes  a  child process for which a wait via waitpid() or
365           waitid() will not block or fail.
366
367        4. The system() function will not cause a process' SIGCHLD handler  to
368           be  called as a result of the fork()/ exec executed within system()
369           because system() will accept the SIGCHLD signal when it performs  a
370           waitpid()  for  its  child process. This is a desirable behavior of
371           system() so that it can be used in a library without  causing  side
372           effects to the application linked with the library.
373
374       An  implementation  that does not permit the wait() family of functions
375       to accept (discard) a pending SIGCHLD signal associated with a success‐
376       fully  waited-for child, cannot make the guarantees described above for
377       the following reasons:
378
379       Guarantee #1
380
381              Although it might  be  assumed  that  reliable  queuing  of  all
382              SIGCHLD signals generated by the system can make this guarantee,
383              the counter-example is the case of a process that blocks SIGCHLD
384              and performs an indefinite loop of fork()/ wait() operations. If
385              the implementation supports queued signals, then eventually  the
386              system  will run out of memory for the queue. The guarantee can‐
387              not be made because there must be some limit  to  the  depth  of
388              queuing.
389
390       Guarantees #2 and #3
391
392              These cannot be guaranteed unless the wait() family of functions
393              accepts the SIGCHLD signal. Otherwise, a fork()/ wait() executed
394              while  SIGCHLD  is  blocked  (as  in the system() function) will
395              result  in  an  invocation  of  the  handler  when  SIGCHLD   is
396              unblocked, after the process has disappeared.
397
398       Guarantee #4
399
400              Although possible to make this guarantee, system() would have to
401              set the SIGCHLD handler to SIG_DFL so that  the  SIGCHLD  signal
402              generated  by its fork() would be discarded (the SIGCHLD default
403              action is to be ignored), then restore it to its  previous  set‐
404              ting.  This would have the undesirable side effect of discarding
405              all SIGCHLD signals pending to the process.
406
407

FUTURE DIRECTIONS

409       None.
410

SEE ALSO

412       exec(), exit(),  fork(),  waitid(),  the  Base  Definitions  volume  of
413       IEEE Std 1003.1-2001, <signal.h>, <sys/wait.h>
414
416       Portions  of  this text are reprinted and reproduced in electronic form
417       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
418       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
419       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
420       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
421       event of any discrepancy between this version and the original IEEE and
422       The  Open Group Standard, the original IEEE and The Open Group Standard
423       is the referee document. The original Standard can be  obtained  online
424       at http://www.opengroup.org/unix/online.html .
425
426
427
428IEEE/The Open Group                  2003                             WAIT(3P)
Impressum