]>
Commit | Line | Data |
---|---|---|
1130df60 | 1 | .\" Copyright (c) 1993 by Thomas Koenig <ig25@rz.uni-karlsruhe.de> |
c11b1abf | 2 | .\" and Copyright (c) 2004 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith <faith@cs.unc.edu> | |
27 | .\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" (Thanks to Koen Holtman <koen@win.tue.nl>) | |
29 | .\" Modified Wed May 17 15:54:12 1995 by Rik Faith <faith@cs.unc.edu> | |
30 | .\" To remove *'s from status in macros (Thanks to Michael Shields). | |
31 | .\" Modified as suggested by Nick Duffek <nsd@bbc.com>, aeb, 960426 | |
32 | .\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. | |
33 | .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. | |
34 | .\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler | |
35 | .\" <dwheeler@dwheeler.com> - noted thread issues. | |
36 | .\" Modified 26 Jun 01 by Michael Kerrisk | |
37 | .\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions | |
38 | .\" Modified 2001-09-25, aeb | |
c11b1abf | 39 | .\" Modified 26 Jun 01 by Michael Kerrisk, <mtk.manpages@gmail.com> |
fea681da | 40 | .\" Updated notes on setting disposition of SIGCHLD to SIG_IGN |
599be3ee MK |
41 | .\" 2004-11-11, mtk |
42 | .\" Added waitid(2); added WCONTINUED and WIFCONTINUED() | |
f2351505 | 43 | .\" Added text on SA_NOCLDSTOP |
d9bfdb9c | 44 | .\" Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior |
f2351505 | 45 | .\" Much other text rewritten |
948fb4ed | 46 | .\" 2005-05-10, mtk, __W* flags can't be used with waitid() |
21399189 | 47 | .\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP |
fea681da | 48 | .\" |
e8426ca2 | 49 | .TH WAIT 2 2020-04-11 "Linux" "Linux Programmer's Manual" |
fea681da | 50 | .SH NAME |
0bfa087b | 51 | wait, waitpid, waitid \- wait for process to change state |
fea681da MK |
52 | .SH SYNOPSIS |
53 | .B #include <sys/types.h> | |
54 | .br | |
55 | .B #include <sys/wait.h> | |
68e4db0a | 56 | .PP |
36f8fb2b | 57 | .BI "pid_t wait(int *" "wstatus" ); |
dbfe9c70 | 58 | .PP |
36f8fb2b | 59 | .BI "pid_t waitpid(pid_t " pid ", int *" wstatus ", int " options ); |
dbfe9c70 | 60 | .PP |
c10859eb MK |
61 | .BI "int waitid(idtype_t " idtype ", id_t " id \ |
62 | ", siginfo_t *" infop ", int " options ); | |
d8b13fb4 MK |
63 | /* This is the glibc and POSIX interface; see |
64 | NOTES for information on the raw system call. */ | |
68e4db0a | 65 | .PP |
cc4615cc MK |
66 | .in -4n |
67 | Feature Test Macro Requirements for glibc (see | |
68 | .BR feature_test_macros (7)): | |
69 | .in | |
68e4db0a | 70 | .PP |
6e3ac6ba MK |
71 | .ad l |
72 | .PD 0 | |
cc4615cc | 73 | .BR waitid (): |
6e3ac6ba | 74 | .RS 4 |
6a43458b MK |
75 | Since glibc 2.26: |
76 | _XOPEN_SOURCE >= 500 || | |
77 | .\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) | |
78 | _POSIX_C_SOURCE\ >=\ 200809L | |
79 | .br | |
80 | Glibc 2.25 and earlier: | |
81 | _XOPEN_SOURCE | |
82 | || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L | |
83 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE | |
6e3ac6ba MK |
84 | .RE |
85 | .PD | |
86 | .ad | |
fea681da | 87 | .SH DESCRIPTION |
f2351505 MK |
88 | All of these system calls are used to wait for state changes |
89 | in a child of the calling process, and obtain information | |
90 | about the child whose state has changed. | |
91 | A state change is considered to be: the child terminated; | |
92 | the child was stopped by a signal; or the child was resumed by a signal. | |
93 | In the case of a terminated child, performing a wait allows | |
94 | the system to release the resources associated with the child; | |
f946c580 | 95 | if a wait is not performed, then the terminated child remains in |
f2351505 | 96 | a "zombie" state (see NOTES below). |
efeece04 | 97 | .PP |
f2351505 | 98 | If a child has already changed state, then these calls return immediately. |
2b9b829d | 99 | Otherwise, they block until either a child changes state or |
f2351505 MK |
100 | a signal handler interrupts the call (assuming that system calls |
101 | are not automatically restarted using the | |
102 | .B SA_RESTART | |
103 | flag of | |
104 | .BR sigaction (2)). | |
105 | In the remainder of this page, a child whose state has changed | |
c13182ef | 106 | and which has not yet been waited upon by one of these system |
d3b2ef5d | 107 | calls is termed |
f2351505 | 108 | .IR waitable . |
73d8cece | 109 | .SS wait() and waitpid() |
fea681da | 110 | The |
f2351505 | 111 | .BR wait () |
9c8ed835 | 112 | system call suspends execution of the calling thread until one of its |
f2351505 MK |
113 | children terminates. |
114 | The call | |
36f8fb2b | 115 | .I wait(&wstatus) |
f2351505 | 116 | is equivalent to: |
207050fa MK |
117 | .PP |
118 | .in +4n | |
119 | .EX | |
120 | waitpid(\-1, &wstatus, 0); | |
121 | .EE | |
122 | .in | |
efeece04 | 123 | .PP |
fea681da | 124 | The |
f2351505 | 125 | .BR waitpid () |
9c8ed835 | 126 | system call suspends execution of the calling thread until a |
f2351505 | 127 | child specified by |
fea681da | 128 | .I pid |
f2351505 MK |
129 | argument has changed state. |
130 | By default, | |
131 | .BR waitpid () | |
d9bfdb9c | 132 | waits only for terminated children, but this behavior is modifiable |
f2351505 MK |
133 | via the |
134 | .I options | |
135 | argument, as described below. | |
efeece04 | 136 | .PP |
fea681da MK |
137 | The value of |
138 | .I pid | |
f2351505 | 139 | can be: |
fea681da | 140 | .IP "< \-1" |
f2351505 | 141 | meaning wait for any child process whose process group ID is |
fea681da MK |
142 | equal to the absolute value of |
143 | .IR pid . | |
144 | .IP \-1 | |
f2351505 | 145 | meaning wait for any child process. |
fea681da | 146 | .IP 0 |
f2351505 | 147 | meaning wait for any child process whose process group ID is |
ff8ddd11 MK |
148 | equal to that of the calling process at the time of the call to |
149 | .BR waitpid (). | |
fea681da | 150 | .IP "> 0" |
f2351505 | 151 | meaning wait for the child whose process ID is equal to the |
fea681da MK |
152 | value of |
153 | .IR pid . | |
154 | .PP | |
155 | The value of | |
156 | .I options | |
157 | is an OR of zero or more of the following constants: | |
0019177e | 158 | .TP |
fea681da | 159 | .B WNOHANG |
f2351505 | 160 | return immediately if no child has exited. |
fea681da MK |
161 | .TP |
162 | .B WUNTRACED | |
d3b2ef5d | 163 | also return if a child has stopped |
f2351505 | 164 | (but not traced via |
d3b2ef5d MK |
165 | .BR ptrace (2)). |
166 | Status for | |
167 | .I traced | |
168 | children which have stopped is provided | |
169 | even if this option is not specified. | |
f2351505 | 170 | .TP |
31daf529 | 171 | .BR WCONTINUED " (since Linux 2.6.10)" |
d3b2ef5d | 172 | also return if a stopped child has been resumed by delivery of |
f2351505 | 173 | .BR SIGCONT . |
fea681da MK |
174 | .PP |
175 | (For Linux-only options, see below.) | |
176 | .PP | |
177 | If | |
36f8fb2b | 178 | .I wstatus |
8478ee02 | 179 | is not NULL, |
f2351505 MK |
180 | .BR wait () |
181 | and | |
182 | .BR waitpid () | |
a8d55537 | 183 | store status information in the \fIint\fP to which it points. |
f2351505 MK |
184 | This integer can be inspected with the following macros (which |
185 | take the integer itself as an argument, not a pointer to it, | |
186 | as is done in | |
187 | .BR wait () | |
188 | and | |
189 | .BR waitpid ()!): | |
fea681da | 190 | .TP |
36f8fb2b | 191 | .BI WIFEXITED( wstatus ) |
fea681da | 192 | returns true if the child terminated normally, that is, |
f2351505 MK |
193 | by calling |
194 | .BR exit (3) | |
195 | or | |
a5e0a0e4 | 196 | .BR _exit (2), |
f2351505 | 197 | or by returning from main(). |
fea681da | 198 | .TP |
36f8fb2b | 199 | .BI WEXITSTATUS( wstatus ) |
f2351505 MK |
200 | returns the exit status of the child. |
201 | This consists of the least significant 8 bits of the | |
c46bf9ae | 202 | .I status |
f2351505 | 203 | argument that the child specified in a call to |
0bfa087b | 204 | .BR exit (3) |
f2351505 | 205 | or |
0bfa087b | 206 | .BR _exit (2) |
f2351505 | 207 | or as the argument for a return statement in main(). |
33a0ccb2 | 208 | This macro should be employed only if |
fea681da MK |
209 | .B WIFEXITED |
210 | returned true. | |
211 | .TP | |
36f8fb2b | 212 | .BI WIFSIGNALED( wstatus ) |
f2351505 | 213 | returns true if the child process was terminated by a signal. |
fea681da | 214 | .TP |
36f8fb2b | 215 | .BI WTERMSIG( wstatus ) |
fea681da | 216 | returns the number of the signal that caused the child process to |
c13182ef | 217 | terminate. |
33a0ccb2 | 218 | This macro should be employed only if |
f2351505 MK |
219 | .B WIFSIGNALED |
220 | returned true. | |
221 | .TP | |
36f8fb2b | 222 | .BI WCOREDUMP( wstatus ) |
b8433813 MK |
223 | returns true if the child produced a core dump (see |
224 | .BR core (5)). | |
33a0ccb2 | 225 | This macro should be employed only if |
fea681da | 226 | .B WIFSIGNALED |
f2351505 | 227 | returned true. |
efeece04 | 228 | .IP |
f2351505 | 229 | This macro is not specified in POSIX.1-2001 and is not available on |
008f1ecc | 230 | some UNIX implementations (e.g., AIX, SunOS). |
b50a708b MK |
231 | Therefore, enclose its use inside |
232 | .IR "#ifdef WCOREDUMP ... #endif" . | |
fea681da | 233 | .TP |
36f8fb2b | 234 | .BI WIFSTOPPED( wstatus ) |
f2351505 | 235 | returns true if the child process was stopped by delivery of a signal; |
33a0ccb2 | 236 | this is possible only if the call was done using |
0daa9e92 | 237 | .B WUNTRACED |
fea681da MK |
238 | or when the child is being traced (see |
239 | .BR ptrace (2)). | |
240 | .TP | |
36f8fb2b | 241 | .BI WSTOPSIG( wstatus ) |
c13182ef | 242 | returns the number of the signal which caused the child to stop. |
33a0ccb2 | 243 | This macro should be employed only if |
fea681da | 244 | .B WIFSTOPPED |
f2351505 MK |
245 | returned true. |
246 | .TP | |
36f8fb2b | 247 | .BI WIFCONTINUED( wstatus ) |
31daf529 | 248 | (since Linux 2.6.10) |
f2351505 MK |
249 | returns true if the child process was resumed by delivery of |
250 | .BR SIGCONT . | |
73d8cece | 251 | .SS waitid() |
f2351505 MK |
252 | The |
253 | .BR waitid () | |
254 | system call (available since Linux 2.6.9) provides more precise | |
255 | control over which child state changes to wait for. | |
efeece04 | 256 | .PP |
f2351505 MK |
257 | The |
258 | .I idtype | |
259 | and | |
260 | .I id | |
261 | arguments select the child(ren) to wait for, as follows: | |
262 | .IP "\fIidtype\fP == \fBP_PID\fP" | |
263 | Wait for the child whose process ID matches | |
264 | .IR id . | |
f3ea12fb MK |
265 | .IP "\fIidtype\fP == \fBP_PIDFD\fP (since Linux 5.4)" |
266 | .\" commit 3695eae5fee0605f316fbaad0b9e3de791d7dfaf | |
267 | Wait for the child referred to by the PID file descriptor specified in | |
268 | .IR id . | |
269 | (See | |
270 | .BR pidfd_open (2) | |
271 | for further information on PID file descriptors.) | |
f2351505 MK |
272 | .IP "\fIidtype\fP == \fBP_PGID\fP" |
273 | Wait for any child whose process group ID matches | |
274 | .IR id . | |
bc4a6786 MK |
275 | Since Linux 5.4, |
276 | .\" commit 821cc7b0b205c0df64cce59aacc330af251fa8f7 | |
277 | if | |
278 | .I id | |
279 | is zero, then wait for any child that is in the same process group | |
280 | as the caller's process group at the time of the call. | |
f2351505 MK |
281 | .IP "\fIidtype\fP == \fBP_ALL\fP" |
282 | Wait for any child; | |
283 | .I id | |
284 | is ignored. | |
285 | .PP | |
286 | The child state changes to wait for are specified by ORing | |
287 | one or more of the following flags in | |
288 | .IR options : | |
0019177e | 289 | .TP |
f2351505 MK |
290 | .B WEXITED |
291 | Wait for children that have terminated. | |
292 | .TP | |
293 | .B WSTOPPED | |
294 | Wait for children that have been stopped by delivery of a signal. | |
295 | .TP | |
296 | .B WCONTINUED | |
297 | Wait for (previously stopped) children that have been | |
298 | resumed by delivery of | |
299 | .BR SIGCONT . | |
300 | .PP | |
301 | The following flags may additionally be ORed in | |
302 | .IR options : | |
0019177e | 303 | .TP |
f2351505 MK |
304 | .B WNOHANG |
305 | As for | |
306 | .BR waitpid (). | |
307 | .TP | |
308 | .B WNOWAIT | |
309 | Leave the child in a waitable state; a later wait call | |
310 | can be used to again retrieve the child status information. | |
311 | .PP | |
312 | Upon successful return, | |
313 | .BR waitid () | |
314 | fills in the following fields of the | |
315 | .I siginfo_t | |
316 | structure pointed to by | |
317 | .IR infop : | |
0019177e | 318 | .TP |
a325cc60 | 319 | \fIsi_pid\fP |
f2351505 | 320 | The process ID of the child. |
a325cc60 MK |
321 | .TP |
322 | \fIsi_uid\fP | |
f2351505 | 323 | The real user ID of the child. |
04d6ea6b | 324 | (This field is not set on most other implementations.) |
a325cc60 MK |
325 | .TP |
326 | \fIsi_signo\fP | |
f2351505 MK |
327 | Always set to |
328 | .BR SIGCHLD . | |
a325cc60 MK |
329 | .TP |
330 | \fIsi_status\fP | |
f2351505 MK |
331 | Either the exit status of the child, as given to |
332 | .BR _exit (2) | |
333 | (or | |
334 | .BR exit (3)), | |
335 | or the signal that caused the child to terminate, stop, or continue. | |
c13182ef | 336 | The |
f2351505 MK |
337 | .I si_code |
338 | field can be used to determine how to interpret this field. | |
a325cc60 MK |
339 | .TP |
340 | \fIsi_code\fP | |
f2351505 MK |
341 | Set to one of: |
342 | .B CLD_EXITED | |
343 | (child called | |
344 | .BR _exit (2)); | |
345 | .B CLD_KILLED | |
346 | (child killed by signal); | |
73ac11ee GK |
347 | .B CLD_DUMPED |
348 | (child killed by signal, and dumped core); | |
f2351505 | 349 | .B CLD_STOPPED |
73ac11ee GK |
350 | (child stopped by signal); |
351 | .B CLD_TRAPPED | |
352 | (traced child has trapped); or | |
f2351505 MK |
353 | .B CLD_CONTINUED |
354 | (child continued by | |
355 | .BR SIGCONT ). | |
356 | .PP | |
357 | If | |
358 | .B WNOHANG | |
359 | was specified in | |
360 | .I options | |
361 | and there were no children in a waitable state, then | |
362 | .BR waitid () | |
363 | returns 0 immediately and | |
364 | the state of the | |
365 | .I siginfo_t | |
366 | structure pointed to by | |
367 | .I infop | |
59e30f70 MK |
368 | depends on the implementation. |
369 | To (portably) distinguish this case from that where a child was in a | |
f2351505 MK |
370 | waitable state, zero out the |
371 | .I si_pid | |
c7094399 | 372 | field before the call and check for a nonzero value in this field |
f2351505 | 373 | after the call returns. |
59e30f70 MK |
374 | .PP |
375 | POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when | |
376 | .B WNOHANG | |
377 | is specified in | |
378 | .I options | |
379 | and there were no children in a waitable state, then | |
380 | .BR waitid () | |
381 | should zero out the | |
382 | .I si_pid | |
383 | and | |
384 | .I si_signo | |
385 | fields of the structure. | |
386 | On Linux and other implementations that adhere to this requirement, | |
387 | it is not necessary to zero out the | |
388 | .I si_pid | |
389 | field before calling | |
390 | .BR waitid (). | |
391 | However, | |
392 | not all implementations follow the POSIX.1 specification on this point. | |
393 | .\" POSIX.1-2001 leaves this possibility unspecified; most | |
394 | .\" implementations (including Linux) zero out the structure | |
395 | .\" in this case, but at least one implementation (AIX 5.1) | |
396 | .\" does not -- MTK Nov 04 | |
47297adb | 397 | .SH RETURN VALUE |
f2351505 | 398 | .BR wait (): |
d3b2ef5d | 399 | on success, returns the process ID of the terminated child; |
f2351505 | 400 | on error, \-1 is returned. |
efeece04 | 401 | .PP |
a5e0a0e4 | 402 | .BR waitpid (): |
d3b2ef5d | 403 | on success, returns the process ID of the child whose state has changed; |
f2351505 | 404 | if |
fea681da | 405 | .B WNOHANG |
55ae3c86 | 406 | was specified and one or more child(ren) specified by |
f2351505 | 407 | .I pid |
55ae3c86 MK |
408 | exist, but have not yet changed state, then 0 is returned. |
409 | On error, \-1 is returned. | |
efeece04 | 410 | .PP |
a5e0a0e4 | 411 | .BR waitid (): |
c13182ef | 412 | returns 0 on success or |
f2351505 MK |
413 | if |
414 | .B WNOHANG | |
415 | was specified and no child(ren) specified by | |
416 | .I id | |
417 | has yet changed state; | |
418 | on error, \-1 is returned. | |
bea08fec | 419 | .\" FIXME As reported by Vegard Nossum, if infop is NULL, then waitid() |
47f442b2 | 420 | .\" returns the PID of the child. Either this is a bug, or it is intended |
74ee79b9 | 421 | .\" behavior that needs to be documented. See my Jan 2009 LKML mail |
47f442b2 | 422 | .\" "waitid() return value strangeness when infop is NULL". |
3252fa3f | 423 | .PP |
f2351505 | 424 | Each of these calls sets |
fea681da | 425 | .I errno |
f2351505 | 426 | to an appropriate value in the case of an error. |
fea681da MK |
427 | .SH ERRORS |
428 | .TP | |
0daa9e92 | 429 | .B ECHILD |
c13182ef | 430 | (for |
e1d6264d | 431 | .BR wait ()) |
fea681da MK |
432 | The calling process does not have any unwaited-for children. |
433 | .TP | |
0daa9e92 | 434 | .B ECHILD |
c13182ef MK |
435 | (for |
436 | .BR waitpid () | |
437 | or | |
e1d6264d | 438 | .BR waitid ()) |
f2351505 | 439 | The process specified by |
fea681da | 440 | .I pid |
f2351505 MK |
441 | .RB ( waitpid ()) |
442 | or | |
443 | .I idtype | |
444 | and | |
445 | .I id | |
446 | .RB ( waitid ()) | |
fea681da | 447 | does not exist or is not a child of the calling process. |
8bd58774 MK |
448 | (This can happen for one's own child if the action for |
449 | .B SIGCHLD | |
450 | is set to | |
451 | .BR SIG_IGN . | |
4fb31341 | 452 | See also the \fILinux Notes\fP section about threads.) |
fea681da MK |
453 | .TP |
454 | .B EINTR | |
455 | .B WNOHANG | |
456 | was not set and an unblocked signal or a | |
457 | .B SIGCHLD | |
01538d0d MK |
458 | was caught; see |
459 | .BR signal (7). | |
fea681da MK |
460 | .TP |
461 | .B EINVAL | |
462 | The | |
463 | .I options | |
464 | argument was invalid. | |
47297adb | 465 | .SH CONFORMING TO |
2dd578fd | 466 | SVr4, 4.3BSD, POSIX.1-2001. |
fea681da | 467 | .SH NOTES |
f2351505 MK |
468 | A child that terminates, but has not been waited for becomes a "zombie". |
469 | The kernel maintains a minimal set of information about the zombie | |
470 | process (PID, termination status, resource usage information) | |
471 | in order to allow the parent to later perform a wait to obtain | |
472 | information about the child. | |
473 | As long as a zombie is not removed from the system via a wait, | |
474 | it will consume a slot in the kernel process table, and if | |
475 | this table fills, it will not be possible to create further processes. | |
476 | If a parent process terminates, then its "zombie" children (if any) | |
477 | are adopted by | |
e8906093 | 478 | .BR init (1), |
cfbe21a4 MK |
479 | (or by the nearest "subreaper" process as defined through the use of the |
480 | .BR prctl (2) | |
481 | .B PR_SET_CHILD_SUBREAPER | |
482 | operation); | |
483 | .BR init (1) | |
484 | automatically performs a wait to remove the zombies. | |
efeece04 | 485 | .PP |
f2351505 MK |
486 | POSIX.1-2001 specifies that if the disposition of |
487 | .B SIGCHLD | |
c13182ef | 488 | is set to |
f2351505 | 489 | .B SIG_IGN |
c13182ef | 490 | or the |
f2351505 MK |
491 | .B SA_NOCLDWAIT |
492 | flag is set for | |
0daa9e92 | 493 | .B SIGCHLD |
c13182ef | 494 | (see |
f2351505 MK |
495 | .BR sigaction (2)), |
496 | then children that terminate do not become zombies and a call to | |
fea681da MK |
497 | .BR wait () |
498 | or | |
499 | .BR waitpid () | |
f2351505 | 500 | will block until all children have terminated, and then fail with |
fea681da | 501 | .I errno |
f2351505 MK |
502 | set to |
503 | .BR ECHILD . | |
d9bfdb9c | 504 | (The original POSIX standard left the behavior of setting |
f2351505 MK |
505 | .B SIGCHLD |
506 | to | |
507 | .B SIG_IGN | |
0e464c2f MK |
508 | unspecified. |
509 | Note that even though the default disposition of | |
510 | .B SIGCHLD | |
511 | is "ignore", explicitly setting the disposition to | |
512 | .B SIG_IGN | |
513 | results in different treatment of zombie process children.) | |
efeece04 | 514 | .PP |
3818a4f1 | 515 | Linux 2.6 conforms to the POSIX requirements. |
f2351505 | 516 | However, Linux 2.4 (and earlier) does not: |
fea681da | 517 | if a |
c13182ef MK |
518 | .BR wait () |
519 | or | |
e1d6264d | 520 | .BR waitpid () |
f2351505 MK |
521 | call is made while |
522 | .B SIGCHLD | |
523 | is being ignored, the call behaves just as though | |
524 | .B SIGCHLD | |
704a18f0 | 525 | were not being ignored, that is, the call blocks until the next child |
d3b2ef5d | 526 | terminates and then returns the process ID and status of that child. |
c634028a | 527 | .SS Linux notes |
fea681da | 528 | In the Linux kernel, a kernel-scheduled thread is not a distinct |
c13182ef MK |
529 | construct from a process. |
530 | Instead, a thread is simply a process | |
fea681da MK |
531 | that is created using the Linux-unique |
532 | .BR clone (2) | |
533 | system call; other routines such as the portable | |
534 | .BR pthread_create (3) | |
535 | call are implemented using | |
536 | .BR clone (2). | |
537 | Before Linux 2.4, a thread was just a special case of a process, | |
538 | and as a consequence one thread could not wait on the children | |
539 | of another thread, even when the latter belongs to the same thread group. | |
540 | However, POSIX prescribes such functionality, and since Linux 2.4 | |
541 | a thread can, and by default will, wait on children of other threads | |
542 | in the same thread group. | |
dd3568a1 | 543 | .PP |
8382f16d | 544 | The following Linux-specific |
fea681da MK |
545 | .I options |
546 | are for use with children created using | |
948fb4ed | 547 | .BR clone (2); |
ff82608e MK |
548 | they can also, since Linux 4.7, |
549 | .\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba | |
550 | be used with | |
948fb4ed | 551 | .BR waitid (): |
fea681da MK |
552 | .TP |
553 | .B __WCLONE | |
554 | .\" since 0.99pl10 | |
c13182ef | 555 | Wait for "clone" children only. |
f14ae16e | 556 | If omitted, then wait for "non-clone" children only. |
c13182ef | 557 | (A "clone" child is one which delivers no signal, or a signal other than |
fea681da MK |
558 | .B SIGCHLD |
559 | to its parent upon termination.) | |
560 | This option is ignored if | |
561 | .B __WALL | |
562 | is also specified. | |
563 | .TP | |
31daf529 | 564 | .BR __WALL " (since Linux 2.4)" |
fea681da | 565 | .\" since patch-2.3.48 |
31daf529 | 566 | Wait for all children, regardless of |
fea681da MK |
567 | type ("clone" or "non-clone"). |
568 | .TP | |
31daf529 | 569 | .BR __WNOTHREAD " (since Linux 2.4)" |
fea681da | 570 | .\" since patch-2.4.0-test8 |
31daf529 | 571 | Do not wait for children of other threads in |
c13182ef MK |
572 | the same thread group. |
573 | This was the default before Linux 2.4. | |
cd32ec84 MK |
574 | .PP |
575 | Since Linux 4.7, | |
576 | .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c | |
577 | .\" prevents cases where an unreapable zombie is created if | |
578 | .\" /sbin/init doesn't use __WALL. | |
579 | the | |
580 | .B __WALL | |
581 | flag is automatically implied if the child is being ptraced. | |
0722a578 | 582 | .SS C library/kernel differences |
7704b6a9 MK |
583 | .BR wait () |
584 | is actually a library function that (in glibc) is implemented as a call to | |
585 | .BR wait4 (2). | |
efeece04 | 586 | .PP |
aab65e59 MK |
587 | On some architectures, there is no |
588 | .BR waitpid () | |
589 | system call; | |
590 | .\" e.g., i386 has the system call, but not x86-64 | |
591 | instead, this interface is implemented via a C library | |
592 | wrapper function that calls | |
593 | .BR wait4 (2). | |
efeece04 | 594 | .PP |
d8b13fb4 MK |
595 | The raw |
596 | .BR waitid () | |
72896e87 | 597 | system call takes a fifth argument, of type |
d8b13fb4 MK |
598 | .IR "struct rusage\ *" . |
599 | If this argument is non-NULL, | |
600 | then it is used to return resource usage information about the child, | |
601 | in the same manner as | |
602 | .BR wait4 (2). | |
603 | See | |
604 | .BR getrusage (2) | |
605 | for details. | |
7484d5a7 MK |
606 | .SH BUGS |
607 | According to POSIX.1-2008, an application calling | |
608 | .BR waitid () | |
609 | must ensure that | |
610 | .I infop | |
611 | points to a | |
612 | .I siginfo_t | |
b437fdd9 | 613 | structure (i.e., that it is a non-null pointer). |
7484d5a7 MK |
614 | On Linux, if |
615 | .I infop | |
616 | is NULL, | |
617 | .BR waitid () | |
618 | succeeds, and returns the process ID of the waited-for child. | |
619 | Applications should avoid relying on this inconsistent, | |
620 | nonstandard, and unnecessary feature. | |
1fa343d1 | 621 | .SH EXAMPLE |
cde9f44b | 622 | .\" fork.2 refers to this example program. |
c13182ef | 623 | The following program demonstrates the use of |
19dbfd0a | 624 | .BR fork (2) |
c13182ef | 625 | and |
2777b1ca | 626 | .BR waitpid (). |
1fa343d1 | 627 | The program creates a child process. |
c13182ef MK |
628 | If no command-line argument is supplied to the program, |
629 | then the child suspends its execution using | |
1fa343d1 MK |
630 | .BR pause (2), |
631 | to allow the user to send signals to the child. | |
632 | Otherwise, if a command-line argument is supplied, | |
c13182ef | 633 | then the child exits immediately, |
1fa343d1 MK |
634 | using the integer supplied on the command line as the exit status. |
635 | The parent process executes a loop that monitors the child using | |
2777b1ca | 636 | .BR waitpid (), |
d9bfdb9c | 637 | and uses the W*() macros described above to analyze the wait status value. |
efeece04 | 638 | .PP |
1fa343d1 | 639 | The following shell session demonstrates the use of the program: |
e646a1ba | 640 | .PP |
9d0cc711 | 641 | .in +4n |
e646a1ba | 642 | .EX |
b43a3b30 | 643 | .RB "$" " ./a.out &" |
1fa343d1 MK |
644 | Child PID is 32360 |
645 | [1] 32359 | |
b43a3b30 | 646 | .RB "$" " kill \-STOP 32360" |
1fa343d1 | 647 | stopped by signal 19 |
b43a3b30 | 648 | .RB "$" " kill \-CONT 32360" |
1fa343d1 | 649 | continued |
b43a3b30 | 650 | .RB "$" " kill \-TERM 32360" |
1fa343d1 MK |
651 | killed by signal 15 |
652 | [1]+ Done ./a.out | |
653 | $ | |
b8302363 | 654 | .EE |
9d0cc711 | 655 | .in |
9c330504 | 656 | .SS Program source |
d84d0300 | 657 | \& |
e7d0bb47 | 658 | .EX |
1fa343d1 MK |
659 | #include <sys/wait.h> |
660 | #include <stdlib.h> | |
661 | #include <unistd.h> | |
662 | #include <stdio.h> | |
663 | ||
664 | int | |
665 | main(int argc, char *argv[]) | |
666 | { | |
667 | pid_t cpid, w; | |
36f8fb2b | 668 | int wstatus; |
1fa343d1 MK |
669 | |
670 | cpid = fork(); | |
29059a65 | 671 | if (cpid == \-1) { |
45949175 MK |
672 | perror("fork"); |
673 | exit(EXIT_FAILURE); | |
674 | } | |
1fa343d1 MK |
675 | |
676 | if (cpid == 0) { /* Code executed by child */ | |
d1a71985 | 677 | printf("Child PID is %ld\en", (long) getpid()); |
1fa343d1 MK |
678 | if (argc == 1) |
679 | pause(); /* Wait for signals */ | |
680 | _exit(atoi(argv[1])); | |
681 | ||
682 | } else { /* Code executed by parent */ | |
683 | do { | |
36f8fb2b | 684 | w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED); |
29059a65 | 685 | if (w == \-1) { |
45949175 MK |
686 | perror("waitpid"); |
687 | exit(EXIT_FAILURE); | |
688 | } | |
1fa343d1 | 689 | |
36f8fb2b | 690 | if (WIFEXITED(wstatus)) { |
d1a71985 | 691 | printf("exited, status=%d\en", WEXITSTATUS(wstatus)); |
36f8fb2b | 692 | } else if (WIFSIGNALED(wstatus)) { |
d1a71985 | 693 | printf("killed by signal %d\en", WTERMSIG(wstatus)); |
36f8fb2b | 694 | } else if (WIFSTOPPED(wstatus)) { |
d1a71985 | 695 | printf("stopped by signal %d\en", WSTOPSIG(wstatus)); |
36f8fb2b | 696 | } else if (WIFCONTINUED(wstatus)) { |
d1a71985 | 697 | printf("continued\en"); |
1fa343d1 | 698 | } |
36f8fb2b | 699 | } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus)); |
1fa343d1 MK |
700 | exit(EXIT_SUCCESS); |
701 | } | |
702 | } | |
e7d0bb47 | 703 | .EE |
47297adb | 704 | .SH SEE ALSO |
f2351505 | 705 | .BR _exit (2), |
fea681da | 706 | .BR clone (2), |
f2351505 MK |
707 | .BR fork (2), |
708 | .BR kill (2), | |
fea681da | 709 | .BR ptrace (2), |
f2351505 | 710 | .BR sigaction (2), |
fea681da MK |
711 | .BR signal (2), |
712 | .BR wait4 (2), | |
713 | .BR pthread_create (3), | |
b8433813 | 714 | .BR core (5), |
53a1443c | 715 | .BR credentials (7), |
fea681da | 716 | .BR signal (7) |