1 .\" Copyright (c) 1993 by Thomas Koenig <ig25@rz.uni-karlsruhe.de>
2 .\" and Copyright (c) 2004 by Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith <faith@cs.unc.edu>
7 .\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith <faith@cs.unc.edu>
8 .\" (Thanks to Koen Holtman <koen@win.tue.nl>)
9 .\" Modified Wed May 17 15:54:12 1995 by Rik Faith <faith@cs.unc.edu>
10 .\" To remove *'s from status in macros (Thanks to Michael Shields).
11 .\" Modified as suggested by Nick Duffek <nsd@bbc.com>, aeb, 960426
12 .\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR.
13 .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
14 .\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler
15 .\" <dwheeler@dwheeler.com> - noted thread issues.
16 .\" Modified 26 Jun 01 by Michael Kerrisk
17 .\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions
18 .\" Modified 2001-09-25, aeb
19 .\" Modified 26 Jun 01 by Michael Kerrisk, <mtk.manpages@gmail.com>
20 .\" Updated notes on setting disposition of SIGCHLD to SIG_IGN
22 .\" Added waitid(2); added WCONTINUED and WIFCONTINUED()
23 .\" Added text on SA_NOCLDSTOP
24 .\" Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior
25 .\" Much other text rewritten
26 .\" 2005-05-10, mtk, __W* flags can't be used with waitid()
27 .\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP
29 .TH wait 2 (date) "Linux man-pages (unreleased)"
31 wait, waitpid, waitid \- wait for process to change state
34 .RI ( libc ", " \-lc )
37 .B #include <sys/wait.h>
39 .BI "pid_t wait(int *_Nullable " "wstatus" );
40 .BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options );
42 .BI "int waitid(idtype_t " idtype ", id_t " id \
43 ", siginfo_t *" infop ", int " options );
44 /* This is the glibc and POSIX interface; see
45 NOTES for information on the raw system call. */
49 Feature Test Macro Requirements for glibc (see
50 .BR feature_test_macros (7)):
56 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
57 .\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
58 glibc 2.25 and earlier:
60 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
61 || /* glibc <= 2.19: */ _BSD_SOURCE
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 the terminated 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 calling thread until one of its
96 waitpid(\-1, &wstatus, 0);
102 system call suspends execution of the calling thread until a
105 argument has changed state.
108 waits only for terminated children, but this behavior is modifiable
111 argument, as described below.
118 meaning wait for any child process whose process group ID is
119 equal to the absolute value of
123 meaning wait for any child process.
126 meaning wait for any child process whose process group ID is
127 equal to that of the calling process at the time of the call to
131 meaning wait for the child whose process ID is equal to the
137 is an OR of zero or more of the following constants:
140 return immediately if no child has exited.
143 also return if a child has stopped
148 children which have stopped is provided
149 even if this option is not specified.
151 .BR WCONTINUED " (since Linux 2.6.10)"
152 also return if a stopped child has been resumed by delivery of
155 (For Linux-only options, see below.)
163 store status information in the \fIint\fP to which it points.
164 This integer can be inspected with the following macros (which
165 take the integer itself as an argument, not a pointer to it,
171 .BI WIFEXITED( wstatus )
172 returns true if the child terminated normally, that is,
177 or by returning from main().
179 .BI WEXITSTATUS( wstatus )
180 returns the exit status of the child.
181 This consists of the least significant 8 bits of the
183 argument that the child specified in a call to
187 or as the argument for a return statement in main().
188 This macro should be employed only if
192 .BI WIFSIGNALED( wstatus )
193 returns true if the child process was terminated by a signal.
195 .BI WTERMSIG( wstatus )
196 returns the number of the signal that caused the child process to
198 This macro should be employed only if
202 .BI WCOREDUMP( wstatus )
203 returns true if the child produced a core dump (see
205 This macro should be employed only if
209 This macro is not specified in POSIX.1-2001 and is not available on
210 some UNIX implementations (e.g., AIX, SunOS).
211 Therefore, enclose its use inside
212 .IR "#ifdef WCOREDUMP ... #endif" .
214 .BI WIFSTOPPED( wstatus )
215 returns true if the child process was stopped by delivery of a signal;
216 this is possible only if the call was done using
218 or when the child is being traced (see
221 .BI WSTOPSIG( wstatus )
222 returns the number of the signal which caused the child to stop.
223 This macro should be employed only if
227 .BI WIFCONTINUED( wstatus )
229 returns true if the child process was resumed by delivery of
234 system call (available since Linux 2.6.9) provides more precise
235 control over which child state changes to wait for.
241 arguments select the child(ren) to wait for, as follows:
243 .IR idtype " == " \fBP_PID\fP
244 Wait for the child whose process ID matches
247 .IR idtype " == " \fBP_PIDFD\fP " (since Linux 5.4)"
248 .\" commit 3695eae5fee0605f316fbaad0b9e3de791d7dfaf
249 Wait for the child referred to by the PID file descriptor specified in
253 for further information on PID file descriptors.)
255 .IR idtype " == " \fBP_PGID\fP
256 Wait for any child whose process group ID matches
259 .\" commit 821cc7b0b205c0df64cce59aacc330af251fa8f7
262 is zero, then wait for any child that is in the same process group
263 as the caller's process group at the time of the call.
265 .IR idtype " == " \fBP_ALL\fP
270 The child state changes to wait for are specified by ORing
271 one or more of the following flags in
275 Wait for children that have terminated.
278 Wait for children that have been stopped by delivery of a signal.
281 Wait for (previously stopped) children that have been
282 resumed by delivery of
285 The following flags may additionally be ORed in
293 Leave the child in a waitable state; a later wait call
294 can be used to again retrieve the child status information.
296 Upon successful return,
298 fills in the following fields of the
300 structure pointed to by
304 The process ID of the child.
307 The real user ID of the child.
308 (This field is not set on most other implementations.)
315 Either the exit status of the child, as given to
319 or the signal that caused the child to terminate, stop, or continue.
322 field can be used to determine how to interpret this field.
330 (child killed by signal);
332 (child killed by signal, and dumped core);
334 (child stopped by signal);
336 (traced child has trapped); or
345 and there were no children in a waitable state, then
347 returns 0 immediately and
350 structure pointed to by
352 depends on the implementation.
353 To (portably) distinguish this case from that where a child was in a
354 waitable state, zero out the
356 field before the call and check for a nonzero value in this field
357 after the call returns.
359 POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when
363 and there were no children in a waitable state, then
369 fields of the structure.
370 On Linux and other implementations that adhere to this requirement,
371 it is not necessary to zero out the
376 not all implementations follow the POSIX.1 specification on this point.
377 .\" POSIX.1-2001 leaves this possibility unspecified; most
378 .\" implementations (including Linux) zero out the structure
379 .\" in this case, but at least one implementation (AIX 5.1)
380 .\" does not -- MTK Nov 04
383 on success, returns the process ID of the terminated child;
384 on failure, \-1 is returned.
387 on success, returns the process ID of the child whose state has changed;
390 was specified and one or more child(ren) specified by
392 exist, but have not yet changed state, then 0 is returned.
393 On failure, \-1 is returned.
396 returns 0 on success or
399 was specified and no child(ren) specified by
401 has yet changed state;
402 on failure, \-1 is returned.
403 .\" FIXME As reported by Vegard Nossum, if infop is NULL, then waitid()
404 .\" returns the PID of the child. Either this is a bug, or it is intended
405 .\" behavior that needs to be documented. See my Jan 2009 LKML mail
406 .\" "waitid() return value strangeness when infop is NULL".
408 On failure, each of these calls sets
410 to indicate the error.
414 The PID file descriptor specified in
416 is nonblocking and the process that it refers to has not terminated.
421 The calling process does not have any unwaited-for children.
428 The process specified by
436 does not exist or is not a child of the calling process.
437 (This can happen for one's own child if the action for
441 See also the \fILinux Notes\fP section about threads.)
445 was not set and an unblocked signal or a
453 argument was invalid.
464 SVr4, 4.3BSD, POSIX.1-2001.
466 A child that terminates, but has not been waited for becomes a "zombie".
467 The kernel maintains a minimal set of information about the zombie
468 process (PID, termination status, resource usage information)
469 in order to allow the parent to later perform a wait to obtain
470 information about the child.
471 As long as a zombie is not removed from the system via a wait,
472 it will consume a slot in the kernel process table, and if
473 this table fills, it will not be possible to create further processes.
474 If a parent process terminates, then its "zombie" children (if any)
477 (or by the nearest "subreaper" process as defined through the use of the
479 .B PR_SET_CHILD_SUBREAPER
482 automatically performs a wait to remove the zombies.
484 POSIX.1-2001 specifies that if the disposition of
494 then children that terminate do not become zombies and a call to
498 will block until all children have terminated, and then fail with
502 (The original POSIX standard left the behavior of setting
507 Note that even though the default disposition of
509 is "ignore", explicitly setting the disposition to
511 results in different treatment of zombie process children.)
513 Linux 2.6 conforms to the POSIX requirements.
514 However, Linux 2.4 (and earlier) does not:
521 is being ignored, the call behaves just as though
523 were not being ignored, that is, the call blocks until the next child
524 terminates and then returns the process ID and status of that child.
526 In the Linux kernel, a kernel-scheduled thread is not a distinct
527 construct from a process.
528 Instead, a thread is simply a process
529 that is created using the Linux-unique
531 system call; other routines such as the portable
532 .BR pthread_create (3)
533 call are implemented using
535 Before Linux 2.4, a thread was just a special case of a process,
536 and as a consequence one thread could not wait on the children
537 of another thread, even when the latter belongs to the same thread group.
538 However, POSIX prescribes such functionality, and since Linux 2.4
539 a thread can, and by default will, wait on children of other threads
540 in the same thread group.
542 The following Linux-specific
544 are for use with children created using
546 they can also, since Linux 4.7,
547 .\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba
553 Wait for "clone" children only.
554 If omitted, then wait for "non-clone" children only.
555 (A "clone" child is one which delivers no signal, or a signal other than
557 to its parent upon termination.)
558 This option is ignored if
562 .BR __WALL " (since Linux 2.4)"
563 .\" since patch-2.3.48
564 Wait for all children, regardless of
565 type ("clone" or "non-clone").
567 .BR __WNOTHREAD " (since Linux 2.4)"
568 .\" since patch-2.4.0-test8
569 Do not wait for children of other threads in
570 the same thread group.
571 This was the default before Linux 2.4.
574 .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c
575 .\" prevents cases where an unreapable zombie is created if
576 .\" /sbin/init doesn't use __WALL.
579 flag is automatically implied if the child is being ptraced.
580 .SS C library/kernel differences
582 is actually a library function that (in glibc) is implemented as a call to
585 On some architectures, there is no
588 .\" e.g., i386 has the system call, but not x86-64
589 instead, this interface is implemented via a C library
590 wrapper function that calls
595 system call takes a fifth argument, of type
596 .IR "struct rusage\ *" .
597 If this argument is non-NULL,
598 then it is used to return resource usage information about the child,
599 in the same manner as
605 According to POSIX.1-2008, an application calling
611 structure (i.e., that it is a non-null pointer).
616 succeeds, and returns the process ID of the waited-for child.
617 Applications should avoid relying on this inconsistent,
618 nonstandard, and unnecessary feature.
620 .\" fork.2 refers to this example program.
621 The following program demonstrates the use of
625 The program creates a child process.
626 If no command-line argument is supplied to the program,
627 then the child suspends its execution using
629 to allow the user to send signals to the child.
630 Otherwise, if a command-line argument is supplied,
631 then the child exits immediately,
632 using the integer supplied on the command line as the exit status.
633 The parent process executes a loop that monitors the child using
635 and uses the W*() macros described above to analyze the wait status value.
637 The following shell session demonstrates the use of the program:
644 .RB "$" " kill \-STOP 32360"
646 .RB "$" " kill \-CONT 32360"
648 .RB "$" " kill \-TERM 32360"
656 .\" SRC BEGIN (wait.c)
661 #include <sys/wait.h>
665 main(int argc, char *argv[])
676 if (cpid == 0) { /* Code executed by child */
677 printf("Child PID is %jd\en", (intmax_t) getpid());
679 pause(); /* Wait for signals */
680 _exit(atoi(argv[1]));
682 } else { /* Code executed by parent */
684 w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED);
690 if (WIFEXITED(wstatus)) {
691 printf("exited, status=%d\en", WEXITSTATUS(wstatus));
692 } else if (WIFSIGNALED(wstatus)) {
693 printf("killed by signal %d\en", WTERMSIG(wstatus));
694 } else if (WIFSTOPPED(wstatus)) {
695 printf("stopped by signal %d\en", WSTOPSIG(wstatus));
696 } else if (WIFCONTINUED(wstatus)) {
697 printf("continued\en");
699 } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
714 .BR pthread_create (3),