1WAIT(P) POSIX Programmer's Manual WAIT(P)
2
6 wait, waitpid - wait for a child process to stop or terminate
7
9 #include <sys/wait.h>
10 pid_t wait(int *stat_loc);
12 pid_t waitpid(pid_t pid, int *stat_loc, int options);
13
16 The wait() and waitpid() functions shall obtain status information per‐
17 taining to one of the caller's child processes. Various options permit
18 status information to be obtained for child processes that have termi‐
19 nated or stopped. If status information is available for two or more
20 child processes, the order in which their status is reported is unspec‐
21 ified.
22 The wait() function shall suspend execution of the calling thread until
24 status information for one of the terminated child processes of the
25 calling process is available, or until delivery of a signal whose
26 action is either to execute a signal-catching function or to terminate
27 the process. If more than one thread is suspended in wait() or wait‐
28 pid() awaiting termination of the same process, exactly one thread
29 shall return the process status at the time of the target process ter‐
30 mination. If status information is available prior to the call to
31 wait(), return shall be immediate.
32 The waitpid() function shall be equivalent to wait() if the pid argu‐
34 ment is (pid_t)-1 and the options argument is 0. Otherwise, its behav‐
35 ior shall be modified by the values of the pid and options arguments.
36 The pid argument specifies a set of child processes for which status is
38 requested. The waitpid() function shall only return the status of a
39 child process from this set:
40 * If pid is equal to (pid_t)-1, status is requested for any child
42 process. In this respect, waitpid() is then equivalent to wait().
43 * If pid is greater than 0, it specifies the process ID of a single
45 child process for which status is requested.
46 * If pid is 0, status is requested for any child process whose process
48 group ID is equal to that of the calling process.
49 * If pid is less than (pid_t)-1, status is requested for any child
51 process whose process group ID is equal to the absolute value of
52 pid.
53 The options argument is constructed from the bitwise-inclusive OR of
55 zero or more of the following flags, defined in the <sys/wait.h>
56 header:
57 WCONTINUED
59 The waitpid() function shall report the status of any continued
60 child process specified by pid whose status has not been
61 reported since it continued from a job control stop.
62 WNOHANG
64 The waitpid() function shall not suspend execution of the call‐
65 ing thread if status is not immediately available for one of the
66 child processes specified by pid.
67 WUNTRACED
69 The status of any child processes specified by pid that are
70 stopped, and whose status has not yet been reported since they
71 stopped, shall also be reported to the requesting process.
72 If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to
75 SIG_IGN, and the process has no unwaited-for children that were trans‐
76 formed into zombie processes, the calling thread shall block until all
77 of the children of the process containing the calling thread terminate,
78 and wait() and waitpid() shall fail and set errno to [ECHILD].
79 If wait() or waitpid() return because the status of a child process is
81 available, these functions shall return a value equal to the process ID
82 of the child process. In this case, if the value of the argument
83 stat_loc is not a null pointer, information shall be stored in the
84 location pointed to by stat_loc. The value stored at the location
85 pointed to by stat_loc shall be 0 if and only if the status returned is
86 from a terminated child process that terminated by one of the following
87 means:
88 1. The process returned 0 from main().
90 2. The process called _exit() or exit() with a status argument of 0.
92 3. The process was terminated because the last thread in the process
94 terminated.
95 Regardless of its value, this information may be interpreted using the
97 following macros, which are defined in <sys/wait.h> and evaluate to
98 integral expressions; the stat_val argument is the integer value
99 pointed to by stat_loc.
100 WIFEXITED(stat_val)
102 Evaluates to a non-zero value if status was returned for a child
104 process that terminated normally.
105 WEXITSTATUS(stat_val)
107 If the value of WIFEXITED(stat_val) is non-zero, this macro
109 evaluates to the low-order 8 bits of the status argument that
110 the child process passed to _exit() or exit(), or the value the
111 child process returned from main().
112 WIFSIGNALED(stat_val)
114 Evaluates to a non-zero value if status was returned for a child
116 process that terminated due to the receipt of a signal that was
117 not caught (see <signal.h>).
118 WTERMSIG(stat_val)
120 If the value of WIFSIGNALED(stat_val) is non-zero, this macro
122 evaluates to the number of the signal that caused the termina‐
123 tion of the child process.
124 WIFSTOPPED(stat_val)
126 Evaluates to a non-zero value if status was returned for a child
128 process that is currently stopped.
129 WSTOPSIG(stat_val)
131 If the value of WIFSTOPPED(stat_val) is non-zero, this macro
133 evaluates to the number of the signal that caused the child
134 process to stop.
135 WIFCONTINUED(stat_val)
137 Evaluates to a non-zero value if status was returned for a child
139 process that has continued from a job control stop.
140 It is unspecified whether the status value returned by calls to wait()
143 or waitpid() for processes created by posix_spawn() or posix_spawnp()
144 can indicate a WIFSTOPPED(stat_val) before subsequent calls to wait()
145 or waitpid() indicate WIFEXITED(stat_val) as the result of an error
146 detected before the new process image starts executing.
147 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 WIFSIGNALED(stat_val) if a signal is sent to the par‐
151 ent's process group after posix_spawn() or posix_spawnp() is called.
152 If the information pointed to by stat_loc was stored by a call to wait‐
154 pid() that specified the WUNTRACED flag and did not specify the WCON‐
155 TINUED flag, exactly one of the macros WIFEXITED(*stat_loc), WIFSIG‐
156 NALED(*stat_loc), and WIFSTOPPED(*stat_loc) shall evaluate to a non-
157 zero value.
158 If the information pointed to by stat_loc was stored by a call to wait‐
160 pid() that specified the WUNTRACED and WCONTINUED flags, exactly
161 one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), WIF‐
162 STOPPED(*stat_loc), and WIFCONTINUED(*stat_loc) shall evaluate to a
163 non-zero value.
164 If the information pointed to by stat_loc was stored by a call to wait‐
166 pid() that did not specify the WUNTRACED or WCONTINUED flags, or by a
167 call to the wait() function, exactly one of the macros WIFEX‐
168 ITED(*stat_loc) and WIFSIGNALED(*stat_loc) shall evaluate to a non-zero
169 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 flag and specified the WCON‐
173 TINUED flag, or by a call to the wait() function, exactly one of the
174 macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and WIFCONTIN‐
175 UED(*stat_loc) shall evaluate to a non-zero value.
176 If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues
178 the SIGCHLD signal, then if wait() or waitpid() returns because the
179 status of a child process is available, any pending SIGCHLD signal
180 associated with the process ID of the child process shall be discarded.
181 Any other pending SIGCHLD signals shall remain pending.
182 Otherwise, if SIGCHLD is blocked, if wait() or waitpid() return because
184 the status of a child process is available, any pending SIGCHLD signal
185 shall be cleared unless the status of another child process is avail‐
186 able.
187 For all other conditions, it is unspecified whether child status will
189 be available when a SIGCHLD signal is delivered.
190 There may be additional implementation-defined circumstances under
192 which wait() or waitpid() report status. This shall not occur unless
193 the calling process or one of its child processes explicitly makes use
194 of a non-standard extension. In these cases the interpretation of the
195 reported status is implementation-defined.
196 If a parent process terminates without waiting for all of its child
198 processes to terminate, the remaining child processes shall be assigned
199 a new parent process ID corresponding to an implementation-defined sys‐
200 tem process.
201
203 If wait() or waitpid() returns because the status of a child process is
204 available, these functions shall return a value equal to the process ID
205 of the child process for which status is reported. If wait() or wait‐
206 pid() returns due to the delivery of a signal to the calling process,
207 -1 shall be returned and errno set to [EINTR]. If waitpid() was invoked
208 with WNOHANG set in options, it has at least one child process speci‐
209 fied by pid for which status is not available, and status is not avail‐
210 able for any process specified by pid, 0 is returned. Otherwise,
211 (pid_t)-1 shall be returned, and errno set to indicate the error.
212
214 The wait() function shall fail if:
215 ECHILD The calling process has no existing unwaited-for child pro‐
217 cesses.
218 EINTR The function was interrupted by a signal. The value of the loca‐
220 tion pointed to by stat_loc is undefined.
221 The waitpid() function shall fail if:
224 ECHILD The process specified by pid does not exist or is not a child of
226 the calling process, or the process group specified by pid does
227 not exist or does not have any member process that is a child of
228 the calling process.
229 EINTR The function was interrupted by a signal. The value of the loca‐
231 tion pointed to by stat_loc is undefined.
232 EINVAL The options argument is not valid.
234 The following sections are informative.
237
239 None.
240
242 None.
243
245 A call to the wait() or waitpid() function only returns status on an
246 immediate child process of the calling process; that is, a child that
247 was produced by a single fork() call (perhaps followed by an exec or
248 other function calls) from the parent. If a child produces grandchil‐
249 dren by further use of fork(), none of those grandchildren nor any of
250 their descendants affect the behavior of a wait() from the original
251 parent process. Nothing in this volume of IEEE Std 1003.1-2001 pre‐
252 vents an implementation from providing extensions that permit a process
253 to get status from a grandchild or any other process, but a process
254 that does not use such extensions must be guaranteed to see status from
255 only its direct children.
256 The waitpid() function is provided for three reasons:
258 1. To support job control
260 2. To permit a non-blocking version of the wait() function
262 3. To permit a library routine, such as system() or pclose(), to wait
264 for its children without interfering with other terminated children
265 for which the process has not waited
266 The first two of these facilities are based on the wait3() function
268 provided by 4.3 BSD. The function uses the options argument, which is
269 equivalent to an argument to wait3(). The WUNTRACED flag is used only
270 in conjunction with job control on systems supporting job control. Its
271 name comes from 4.3 BSD and refers to the fact that there are two types
272 of stopped processes in that implementation: processes being traced via
273 the ptrace() debugging facility and (untraced) processes stopped by job
274 control signals. Since ptrace() is not part of this volume of
275 IEEE Std 1003.1-2001, only the second type is relevant. The name WUN‐
276 TRACED was retained because its usage is the same, even though the name
277 is not intuitively meaningful in this context.
278 The third reason for the waitpid() function is to permit independent
280 sections of a process to spawn and wait for children without interfer‐
281 ing with each other. For example, the following problem occurs in
282 developing a portable shell, or command interpreter:
283 stream = popen("/bin/true");
286 (void) system("sleep 100");
287 (void) pclose(stream);
288 On all historical implementations, the final pclose() fails to reap the
290 wait() status of the popen().
291 The status values are retrieved by macros, rather than given as spe‐
293 cific bit encodings as they are in most historical implementations (and
294 thus expected by existing programs). This was necessary to eliminate a
295 limitation on the number of signals an implementation can support that
296 was inherent in the traditional encodings. This volume of
297 IEEE Std 1003.1-2001 does require that a status value of zero corre‐
298 sponds to a process calling _exit(0), as this is the most common encod‐
299 ing expected by existing programs. Some of the macro names were adopted
300 from 4.3 BSD.
301 These macros syntactically operate on an arbitrary integer value. The
303 behavior is undefined unless that value is one stored by a successful
304 call to wait() or waitpid() in the location pointed to by the stat_loc
305 argument. An early proposal attempted to make this clearer by specify‐
306 ing each argument as *stat_loc rather than stat_val. However, that did
307 not follow the conventions of other specifications in this volume of
308 IEEE Std 1003.1-2001 or traditional usage. It also could have implied
309 that the argument to the macro must literally be *stat_loc; in fact,
310 that value can be stored or passed as an argument to other functions
311 before being interpreted by these macros.
312 The extension that affects wait() and waitpid() and is common in his‐
314 torical implementations is the ptrace() function. It is called by a
315 child process and causes that child to stop and return a status that
316 appears identical to the status indicated by WIFSTOPPED. The status of
317 ptrace() children is traditionally returned regardless of the WUNTRACED
318 flag (or by the wait() function). Most applications do not need to con‐
319 cern themselves with such extensions because they have control over
320 what extensions they or their children use. However, applications,
321 such as command interpreters, that invoke arbitrary processes may see
322 this behavior when those arbitrary processes misuse such extensions.
323 Implementations that support core file creation or other implementa‐
325 tion-defined actions on termination of some processes traditionally
326 provide a bit in the status returned by wait() to indicate that such
327 actions have occurred.
328 Allowing the wait() family of functions to discard a pending SIGCHLD
330 signal that is associated with a successfully waited-for child process
331 puts them into the sigwait() and sigwaitinfo() category with respect to
332 SIGCHLD.
333 This definition allows implementations to treat a pending SIGCHLD sig‐
335 nal as accepted by the process in wait(), with the same meaning of
336 "accepted" as when that word is applied to the sigwait() family of
337 functions.
338 Allowing the wait() family of functions to behave this way permits an
340 implementation to be able to deal precisely with SIGCHLD signals.
341 In particular, an implementation that does accept (discard) the SIGCHLD
343 signal can make the following guarantees regardless of the queuing
344 depth of signals in general (the list of waitable children can hold the
345 SIGCHLD queue):
346 1. If a SIGCHLD signal handler is established via sigaction() without
348 the SA_RESETHAND flag, SIGCHLD signals can be accurately counted;
349 that is, exactly one SIGCHLD signal will be delivered to or
350 accepted by the process for every child process that terminates.
351 2. A single wait() issued from a SIGCHLD signal handler can be guaran‐
353 teed to return immediately with status information for a child
354 process.
355 3. When SA_SIGINFO is requested, the SIGCHLD signal handler can be
357 guaranteed to receive a non-NULL pointer to a siginfo_t structure
358 that describes a child process for which a wait via waitpid() or
359 waitid() will not block or fail.
360 4. The system() function will not cause a process' SIGCHLD handler to
362 be called as a result of the fork()/ exec executed within system()
363 because system() will accept the SIGCHLD signal when it performs a
364 waitpid() for its child process. This is a desirable behavior of
365 system() so that it can be used in a library without causing side
366 effects to the application linked with the library.
367 An implementation that does not permit the wait() family of functions
369 to accept (discard) a pending SIGCHLD signal associated with a success‐
370 fully waited-for child, cannot make the guarantees described above for
371 the following reasons:
372 Guarantee #1
374 Although it might be assumed that reliable queuing of all
376 SIGCHLD signals generated by the system can make this guarantee,
377 the counter-example is the case of a process that blocks SIGCHLD
378 and performs an indefinite loop of fork()/ wait() operations. If
379 the implementation supports queued signals, then eventually the
380 system will run out of memory for the queue. The guarantee can‐
381 not be made because there must be some limit to the depth of
382 queuing.
383 Guarantees #2 and #3
385 These cannot be guaranteed unless the wait() family of functions
387 accepts the SIGCHLD signal. Otherwise, a fork()/ wait() executed
388 while SIGCHLD is blocked (as in the system() function) will
389 result in an invocation of the handler when SIGCHLD is
390 unblocked, after the process has disappeared.
391 Guarantee #4
393 Although possible to make this guarantee, system() would have to
395 set the SIGCHLD handler to SIG_DFL so that the SIGCHLD signal
396 generated by its fork() would be discarded (the SIGCHLD default
397 action is to be ignored), then restore it to its previous set‐
398 ting. This would have the undesirable side effect of discarding
399 all SIGCHLD signals pending to the process.
400
403 None.
404
406 exec() , exit() , fork() , waitid() , the Base Definitions volume of
407 IEEE Std 1003.1-2001, <signal.h>, <sys/wait.h>
408
410 Portions of this text are reprinted and reproduced in electronic form
411 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
412 -- Portable Operating System Interface (POSIX), The Open Group Base
413 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
414 Electrical and Electronics Engineers, Inc and The Open Group. In the
415 event of any discrepancy between this version and the original IEEE and
416 The Open Group Standard, the original IEEE and The Open Group Standard
417 is the referee document. The original Standard can be obtained online
418 at http://www.opengroup.org/unix/online.html .
419IEEE/The Open Group 2003 WAIT(P)