1WAIT(3P) POSIX Programmer's Manual WAIT(3P)
2
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
12 wait, waitpid - wait for a child process to stop or terminate
13
15 #include <sys/wait.h>
16 pid_t wait(int *stat_loc);
18 pid_t waitpid(pid_t pid, int *stat_loc, int options);
19
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 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 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 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 * 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 * If pid is greater than 0, it specifies the process ID of a single
51 child process for which status is requested.
52 * 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 * 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 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 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 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 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 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 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 1. The process returned 0 from main().
96 2. The process called _exit() or exit() with a status argument of 0.
98 3. The process was terminated because the last thread in the process
100 terminated.
101 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 WIFEXITED(stat_val)
108 Evaluates to a non-zero value if status was returned for a child
110 process that terminated normally.
111 WEXITSTATUS(stat_val)
113 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 WIFSIGNALED(stat_val)
120 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 WTERMSIG(stat_val)
126 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 WIFSTOPPED(stat_val)
132 Evaluates to a non-zero value if status was returned for a child
134 process that is currently stopped.
135 WSTOPSIG(stat_val)
137 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 WIFCONTINUED(stat_val)
143 Evaluates to a non-zero value if status was returned for a child
145 process that has continued from a job control stop.
146 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 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 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 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 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 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 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 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 For all other conditions, it is unspecified whether child status will
195 be available when a SIGCHLD signal is delivered.
196 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 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
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
220 The wait() function shall fail if:
221 ECHILD The calling process has no existing unwaited-for child pro‐
223 cesses.
224 EINTR The function was interrupted by a signal. The value of the loca‐
226 tion pointed to by stat_loc is undefined.
227 The waitpid() function shall fail if:
230 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 EINTR The function was interrupted by a signal. The value of the loca‐
237 tion pointed to by stat_loc is undefined.
238 EINVAL The options argument is not valid.
240 The following sections are informative.
243
245 None.
246
248 None.
249
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 The waitpid() function is provided for three reasons:
264 1. To support job control
266 2. To permit a non-blocking version of the wait() function
268 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 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 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 stream = popen("/bin/true");
292 (void) system("sleep 100");
293 (void) pclose(stream);
294 On all historical implementations, the final pclose() fails to reap the
296 wait() status of the popen().
297 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 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 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 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 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 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 Allowing the wait() family of functions to behave this way permits an
346 implementation to be able to deal precisely with SIGCHLD signals.
347 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 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 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 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 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 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 Guarantee #1
380 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 Guarantees #2 and #3
391 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 Guarantee #4
399 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
409 None.
410
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 .
425IEEE/The Open Group 2003 WAIT(3P)