1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright (c) 1993 by Thomas Koenig <ig25@rz.uni-karlsruhe.de>
4 .\" and Copyright (c) 2004 by Michael Kerrisk <mtk-manpages@gmx.net>
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith <faith@cs.unc.edu>
28 .\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith <faith@cs.unc.edu>
29 .\" (Thanks to Koen Holtman <koen@win.tue.nl>)
30 .\" Modified Wed May 17 15:54:12 1995 by Rik Faith <faith@cs.unc.edu>
31 .\" To remove *'s from status in macros (Thanks to Michael Shields).
32 .\" Modified as suggested by Nick Duffek <nsd@bbc.com>, aeb, 960426
33 .\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR.
34 .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
35 .\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler
36 .\" <dwheeler@dwheeler.com> - noted thread issues.
37 .\" Modified 26 Jun 01 by Michael Kerrisk
38 .\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions
39 .\" Modified 2001-09-25, aeb
40 .\" Modified 26 Jun 01 by Michael Kerrisk, <mtk-manpages@gmx.net>
41 .\" Updated notes on setting disposition of SIGCHLD to SIG_IGN
43 .\" Added waitid(2); added WCONTINUED and WIFCONTINUED()
44 .\" Added text on SA_NOCLDSTOP
45 .\" Updated discussion of SA_NOCLDWAIT to reflect 2.6 behaviour
46 .\" Much other text rewritten
47 .\" 2005-05-10, mtk, __W* flags can't be used with waitid()
49 .TH WAIT 2 2004-11-11 "Linux" "Linux Programmer's Manual"
51 wait, waitpid, waitid \- wait for process to change state
53 .B #include <sys/types.h>
55 .B #include <sys/wait.h>
57 .BI "pid_t wait(int *" "status" );
59 .BI "pid_t waitpid(pid_t " pid ", int *" status ", int " options );
61 .BI "int waitid(idtype_t " idtype ", id_t " id \
62 ", siginfo_t *" infop ", int " options );
64 All of these system calls are used to wait for state changes
65 in a child of the calling process, and obtain information
66 about the child whose state has changed.
67 A state change is considered to be: the child terminated;
68 the child was stopped by a signal; or the child was resumed by a signal.
69 In the case of a terminated child, performing a wait allows
70 the system to release the resources associated with the child;
71 if a wait is not performed, then terminated the child remains in
72 a "zombie" state (see NOTES below).
74 If a child has already changed state, then these calls return immediately.
75 Otherwise they block until either a child changes state or
76 a signal handler interrupts the call (assuming that system calls
77 are not automatically restarted using the
81 In the remainder of this page, a child whose state has changed
82 and which has not yet been waited upon by one of these system
85 .SS "wait() and waitpid()"
88 system call suspends execution of the current process until one of its
95 waitpid(\-1, &status, 0);
100 system call suspends execution of the current process until a
103 argument has changed state.
106 waits only for terminated children, but this behaviour is modifiable
109 argument, as described below.
115 meaning wait for any child process whose process group ID is
116 equal to the absolute value of
119 meaning wait for any child process.
121 meaning wait for any child process whose process group ID is
122 equal to that of the calling process.
124 meaning wait for the child whose process ID is equal to the
130 is an OR of zero or more of the following constants:
133 return immediately if no child has exited.
136 also return if a child has stopped
141 children which have stopped is provided
142 even if this option is not specified.
146 also return if a stopped child has been resumed by delivery of
149 (For Linux-only options, see below.)
155 options are only effective if the
157 flag has not been set for the
168 store status information in the \fIint\fR to which it points.
169 This integer can be inspected with the following macros (which
170 take the integer itself as an argument, not a pointer to it,
176 .BI WIFEXITED( status )
177 returns true if the child terminated normally, that is,
182 or by returning from main().
184 .BI WEXITSTATUS( status )
185 returns the exit status of the child.
186 This consists of the least significant 8 bits of the
188 argument that the child specified in a call to
192 or as the argument for a return statement in main().
193 This macro should only be employed if
197 .BI WIFSIGNALED( status )
198 returns true if the child process was terminated by a signal.
200 .BI WTERMSIG( status )
201 returns the number of the signal that caused the child process to
203 This macro should only be employed if
207 .BI WCOREDUMP( status )
208 returns true if the child produced a core dump.
209 This macro should only be employed if
212 This macro is not specified in POSIX.1-2001 and is not available on
213 some Unix implementations (e.g., AIX, SunOS).
214 Only use this enclosed in #ifdef WCOREDUMP ... #endif.
216 .BI WIFSTOPPED( status )
217 returns true if the child process was stopped by delivery of a signal;
218 this is only possible if the call was done using
220 or when the child is being traced (see
223 .BI WSTOPSIG( status )
224 returns the number of the signal which caused the child to stop.
225 This macro should only be employed if
229 .BI WIFCONTINUED( status )
231 returns true if the child process was resumed by delivery of
236 system call (available since Linux 2.6.9) provides more precise
237 control over which child state changes to wait for.
243 arguments select the child(ren) to wait for, as follows:
244 .IP "\fIidtype\fP == \fBP_PID\fP"
245 Wait for the child whose process ID matches
247 .IP "\fIidtype\fP == \fBP_PGID\fP"
248 Wait for any child whose process group ID matches
250 .IP "\fIidtype\fP == \fBP_ALL\fP"
255 The child state changes to wait for are specified by ORing
256 one or more of the following flags in
260 Wait for children that have terminated.
263 Wait for children that have been stopped by delivery of a signal.
266 Wait for (previously stopped) children that have been
267 resumed by delivery of
270 The following flags may additionally be ORed in
278 Leave the child in a waitable state; a later wait call
279 can be used to again retrieve the child status information.
281 Upon successful return,
283 fills in the following fields of the
285 structure pointed to by
288 The process ID of the child.
290 The real user ID of the child.
291 (This field is not set on most other implementations.)
296 Either the exit status of the child, as given to
300 or the signal that caused the child to terminate, stop, or continue.
303 field can be used to determine how to interpret this field.
310 (child killed by signal);
312 (child stopped by signal); or
321 and there were no children in a waitable state, then
323 returns 0 immediately and
326 structure pointed to by
329 .\" POSIX.1-2001 leaves this possibility unspecified; most
330 .\" implementations (including Linux) zero out the structure
331 .\" in this case, but at at least one implementation (AIX 5.1)
332 .\" does not -- MTK Nov 04
333 To distinguish this case from that where a child was in a
334 waitable state, zero out the
336 field before the call and check for a non-zero value in this field
337 after the call returns.
340 on success, returns the process ID of the terminated child;
341 on error, \-1 is returned.
344 on success, returns the process ID of the child whose state has changed;
345 on error, \-1 is returned;
348 was specified and no child(ren) specified by
350 has yet changed state, then 0 is returned.
353 returns 0 on success or
356 was specified and no child(ren) specified by
358 has yet changed state;
359 on error, \-1 is returned.
361 Each of these calls sets
363 to an appropriate value in the case of an error.
369 The calling process does not have any unwaited-for children.
376 The process specified by
384 does not exist or is not a child of the calling process.
385 (This can happen for one's own child if the action for SIGCHLD
387 See also the LINUX NOTES section about threads.)
391 was not set and an unblocked signal or a
398 argument was invalid.
400 A child that terminates, but has not been waited for becomes a "zombie".
401 The kernel maintains a minimal set of information about the zombie
402 process (PID, termination status, resource usage information)
403 in order to allow the parent to later perform a wait to obtain
404 information about the child.
405 As long as a zombie is not removed from the system via a wait,
406 it will consume a slot in the kernel process table, and if
407 this table fills, it will not be possible to create further processes.
408 If a parent process terminates, then its "zombie" children (if any)
411 which automatically performs a wait to remove the zombies.
413 POSIX.1-2001 specifies that if the disposition of
423 then children that terminate do not become zombies and a call to
427 will block until all children have terminated, and then fail with
431 (The original POSIX standard left the behaviour of setting
436 Linux 2.6 conforms to this specification.
437 However, Linux 2.4 (and earlier) does not:
444 is being ignored, the call behaves just as though
446 were not being ignored, that is, the call blocks until the next child
447 terminates and then returns the process ID and status of that child.
449 In the Linux kernel, a kernel-scheduled thread is not a distinct
450 construct from a process.
451 Instead, a thread is simply a process
452 that is created using the Linux-unique
454 system call; other routines such as the portable
455 .BR pthread_create (3)
456 call are implemented using
458 Before Linux 2.4, a thread was just a special case of a process,
459 and as a consequence one thread could not wait on the children
460 of another thread, even when the latter belongs to the same thread group.
461 However, POSIX prescribes such functionality, and since Linux 2.4
462 a thread can, and by default will, wait on children of other threads
463 in the same thread group.
465 The following Linux specific
467 are for use with children created using
469 they cannot be used with
474 Wait for "clone" children only.
475 If omitted then wait for "non-clone" children only.
476 (A "clone" child is one which delivers no signal, or a signal other than
478 to its parent upon termination.)
479 This option is ignored if
484 .\" since patch-2.3.48
485 (Since Linux 2.4) Wait for all children, regardless of
486 type ("clone" or "non-clone").
489 .\" since patch-2.4.0-test8
490 (Since Linux 2.4) Do not wait for children of other threads in
491 the same thread group.
492 This was the default before Linux 2.4.
494 .\" fork.2 refers to this example program.
495 The following program demonstrates the use of
499 The program creates a child process.
500 If no command-line argument is supplied to the program,
501 then the child suspends its execution using
503 to allow the user to send signals to the child.
504 Otherwise, if a command-line argument is supplied,
505 then the child exits immediately,
506 using the integer supplied on the command line as the exit status.
507 The parent process executes a loop that monitors the child using
509 and uses the W*() macros described above to analyse the wait status value.
511 The following shell session demonstrates the use of the program:
526 #include <sys/wait.h>
532 main(int argc, char *argv[])
538 if (cpid == -1) { perror("fork"); exit(EXIT_FAILURE); }
540 if (cpid == 0) { /* Code executed by child */
541 printf("Child PID is %ld\\n", (long) getpid());
543 pause(); /* Wait for signals */
544 _exit(atoi(argv[1]));
546 } else { /* Code executed by parent */
548 w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);
549 if (w == -1) { perror("waitpid"); exit(EXIT_FAILURE); }
551 if (WIFEXITED(status)) {
552 printf("exited, status=%d\\n", WEXITSTATUS(status));
553 } else if (WIFSIGNALED(status)) {
554 printf("killed by signal %d\\n", WTERMSIG(status));
555 } else if (WIFSTOPPED(status)) {
556 printf("stopped by signal %d\\n", WSTOPSIG(status));
557 } else if (WIFCONTINUED(status)) {
558 printf("continued\\n");
560 } while (!WIFEXITED(status) && !WIFSIGNALED(status));
566 SVr4, 4.3BSD, POSIX.1-2001.
576 .BR pthread_create (3),