]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/wait.2
shmop.2: wfix
[thirdparty/man-pages.git] / man2 / wait.2
CommitLineData
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.\"
d8b13fb4 49.TH WAIT 2 2013-09-04 "Linux" "Linux Programmer's Manual"
fea681da 50.SH NAME
0bfa087b 51wait, 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>
56.sp
57.BI "pid_t wait(int *" "status" );
5895e7eb 58
fea681da 59.BI "pid_t waitpid(pid_t " pid ", int *" status ", int " options );
5895e7eb 60
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. */
cc4615cc
MK
65.sp
66.in -4n
67Feature Test Macro Requirements for glibc (see
68.BR feature_test_macros (7)):
69.in
70.sp
6e3ac6ba
MK
71.ad l
72.PD 0
cc4615cc 73.BR waitid ():
6e3ac6ba 74.RS 4
6e3ac6ba
MK
75_SVID_SOURCE ||
76_XOPEN_SOURCE\ >=\ 500 ||
77_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
3ba63d80
MK
78.br
79|| /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
6e3ac6ba
MK
80.RE
81.PD
82.ad
fea681da 83.SH DESCRIPTION
f2351505
MK
84All of these system calls are used to wait for state changes
85in a child of the calling process, and obtain information
86about the child whose state has changed.
87A state change is considered to be: the child terminated;
88the child was stopped by a signal; or the child was resumed by a signal.
89In the case of a terminated child, performing a wait allows
90the system to release the resources associated with the child;
f946c580 91if a wait is not performed, then the terminated child remains in
f2351505
MK
92a "zombie" state (see NOTES below).
93
94If a child has already changed state, then these calls return immediately.
95Otherwise they block until either a child changes state or
96a signal handler interrupts the call (assuming that system calls
97are not automatically restarted using the
98.B SA_RESTART
99flag of
100.BR sigaction (2)).
101In the remainder of this page, a child whose state has changed
c13182ef 102and which has not yet been waited upon by one of these system
d3b2ef5d 103calls is termed
f2351505 104.IR waitable .
73d8cece 105.SS wait() and waitpid()
fea681da 106The
f2351505 107.BR wait ()
a1ffe9f5 108system call suspends execution of the calling process until one of its
f2351505
MK
109children terminates.
110The call
111.I wait(&status)
112is equivalent to:
113.nf
114
2bc2f479 115 waitpid(\-1, &status, 0);
f2351505 116.fi
fea681da
MK
117
118The
f2351505 119.BR waitpid ()
a1ffe9f5 120system call suspends execution of the calling process until a
f2351505 121child specified by
fea681da 122.I pid
f2351505
MK
123argument has changed state.
124By default,
125.BR waitpid ()
d9bfdb9c 126waits only for terminated children, but this behavior is modifiable
f2351505
MK
127via the
128.I options
129argument, as described below.
fea681da
MK
130
131The value of
132.I pid
f2351505 133can be:
fea681da 134.IP "< \-1"
f2351505 135meaning wait for any child process whose process group ID is
fea681da
MK
136equal to the absolute value of
137.IR pid .
138.IP \-1
f2351505 139meaning wait for any child process.
fea681da 140.IP 0
f2351505 141meaning wait for any child process whose process group ID is
fea681da
MK
142equal to that of the calling process.
143.IP "> 0"
f2351505 144meaning wait for the child whose process ID is equal to the
fea681da
MK
145value of
146.IR pid .
147.PP
148The value of
149.I options
150is an OR of zero or more of the following constants:
a325cc60 151.TP 12
fea681da 152.B WNOHANG
f2351505 153return immediately if no child has exited.
fea681da
MK
154.TP
155.B WUNTRACED
d3b2ef5d 156also return if a child has stopped
f2351505 157(but not traced via
d3b2ef5d
MK
158.BR ptrace (2)).
159Status for
160.I traced
161children which have stopped is provided
162even if this option is not specified.
f2351505 163.TP
31daf529 164.BR WCONTINUED " (since Linux 2.6.10)"
d3b2ef5d 165also return if a stopped child has been resumed by delivery of
f2351505 166.BR SIGCONT .
fea681da
MK
167.PP
168(For Linux-only options, see below.)
169.PP
170If
171.I status
8478ee02 172is not NULL,
f2351505
MK
173.BR wait ()
174and
175.BR waitpid ()
a8d55537 176store status information in the \fIint\fP to which it points.
f2351505
MK
177This integer can be inspected with the following macros (which
178take the integer itself as an argument, not a pointer to it,
179as is done in
180.BR wait ()
181and
182.BR waitpid ()!):
fea681da
MK
183.TP
184.BI WIFEXITED( status )
185returns true if the child terminated normally, that is,
f2351505
MK
186by calling
187.BR exit (3)
188or
a5e0a0e4 189.BR _exit (2),
f2351505 190or by returning from main().
fea681da
MK
191.TP
192.BI WEXITSTATUS( status )
f2351505
MK
193returns the exit status of the child.
194This consists of the least significant 8 bits of the
195.I status
196argument that the child specified in a call to
0bfa087b 197.BR exit (3)
f2351505 198or
0bfa087b 199.BR _exit (2)
f2351505 200or as the argument for a return statement in main().
33a0ccb2 201This macro should be employed only if
fea681da
MK
202.B WIFEXITED
203returned true.
204.TP
205.BI WIFSIGNALED( status )
f2351505 206returns true if the child process was terminated by a signal.
fea681da
MK
207.TP
208.BI WTERMSIG( status )
209returns the number of the signal that caused the child process to
c13182ef 210terminate.
33a0ccb2 211This macro should be employed only if
f2351505
MK
212.B WIFSIGNALED
213returned true.
214.TP
215.BI WCOREDUMP( status )
216returns true if the child produced a core dump.
33a0ccb2 217This macro should be employed only if
fea681da 218.B WIFSIGNALED
f2351505
MK
219returned true.
220This macro is not specified in POSIX.1-2001 and is not available on
008f1ecc 221some UNIX implementations (e.g., AIX, SunOS).
f2351505 222Only use this enclosed in #ifdef WCOREDUMP ... #endif.
fea681da
MK
223.TP
224.BI WIFSTOPPED( status )
f2351505 225returns true if the child process was stopped by delivery of a signal;
33a0ccb2 226this is possible only if the call was done using
0daa9e92 227.B WUNTRACED
fea681da
MK
228or when the child is being traced (see
229.BR ptrace (2)).
230.TP
231.BI WSTOPSIG( status )
c13182ef 232returns the number of the signal which caused the child to stop.
33a0ccb2 233This macro should be employed only if
fea681da 234.B WIFSTOPPED
f2351505
MK
235returned true.
236.TP
237.BI WIFCONTINUED( status )
31daf529 238(since Linux 2.6.10)
f2351505
MK
239returns true if the child process was resumed by delivery of
240.BR SIGCONT .
73d8cece 241.SS waitid()
f2351505
MK
242The
243.BR waitid ()
244system call (available since Linux 2.6.9) provides more precise
245control over which child state changes to wait for.
246
247The
248.I idtype
249and
250.I id
251arguments select the child(ren) to wait for, as follows:
252.IP "\fIidtype\fP == \fBP_PID\fP"
253Wait for the child whose process ID matches
254.IR id .
255.IP "\fIidtype\fP == \fBP_PGID\fP"
256Wait for any child whose process group ID matches
257.IR id .
258.IP "\fIidtype\fP == \fBP_ALL\fP"
259Wait for any child;
260.I id
261is ignored.
262.PP
263The child state changes to wait for are specified by ORing
264one or more of the following flags in
265.IR options :
a325cc60 266.TP 12
f2351505
MK
267.B WEXITED
268Wait for children that have terminated.
269.TP
270.B WSTOPPED
271Wait for children that have been stopped by delivery of a signal.
272.TP
273.B WCONTINUED
274Wait for (previously stopped) children that have been
275resumed by delivery of
276.BR SIGCONT .
277.PP
278The following flags may additionally be ORed in
279.IR options :
a325cc60 280.TP 12
f2351505
MK
281.B WNOHANG
282As for
283.BR waitpid ().
284.TP
285.B WNOWAIT
286Leave the child in a waitable state; a later wait call
287can be used to again retrieve the child status information.
288.PP
289Upon successful return,
290.BR waitid ()
291fills in the following fields of the
292.I siginfo_t
293structure pointed to by
294.IR infop :
a325cc60
MK
295.TP 12
296\fIsi_pid\fP
f2351505 297The process ID of the child.
a325cc60
MK
298.TP
299\fIsi_uid\fP
f2351505 300The real user ID of the child.
04d6ea6b 301(This field is not set on most other implementations.)
a325cc60
MK
302.TP
303\fIsi_signo\fP
f2351505
MK
304Always set to
305.BR SIGCHLD .
a325cc60
MK
306.TP
307\fIsi_status\fP
f2351505
MK
308Either the exit status of the child, as given to
309.BR _exit (2)
310(or
311.BR exit (3)),
312or the signal that caused the child to terminate, stop, or continue.
c13182ef 313The
f2351505
MK
314.I si_code
315field can be used to determine how to interpret this field.
a325cc60
MK
316.TP
317\fIsi_code\fP
f2351505
MK
318Set to one of:
319.B CLD_EXITED
320(child called
321.BR _exit (2));
322.B CLD_KILLED
323(child killed by signal);
73ac11ee
GK
324.B CLD_DUMPED
325(child killed by signal, and dumped core);
f2351505 326.B CLD_STOPPED
73ac11ee
GK
327(child stopped by signal);
328.B CLD_TRAPPED
329(traced child has trapped); or
f2351505
MK
330.B CLD_CONTINUED
331(child continued by
332.BR SIGCONT ).
333.PP
334If
335.B WNOHANG
336was specified in
337.I options
338and there were no children in a waitable state, then
339.BR waitid ()
340returns 0 immediately and
341the state of the
342.I siginfo_t
343structure pointed to by
344.I infop
345is unspecified.
c13182ef 346.\" POSIX.1-2001 leaves this possibility unspecified; most
f2351505 347.\" implementations (including Linux) zero out the structure
66d90115 348.\" in this case, but at least one implementation (AIX 5.1)
f2351505
MK
349.\" does not -- MTK Nov 04
350To distinguish this case from that where a child was in a
351waitable state, zero out the
352.I si_pid
c7094399 353field before the call and check for a nonzero value in this field
f2351505 354after the call returns.
47297adb 355.SH RETURN VALUE
f2351505 356.BR wait ():
d3b2ef5d 357on success, returns the process ID of the terminated child;
f2351505
MK
358on error, \-1 is returned.
359
a5e0a0e4 360.BR waitpid ():
d3b2ef5d 361on success, returns the process ID of the child whose state has changed;
f2351505 362if
fea681da 363.B WNOHANG
55ae3c86 364was specified and one or more child(ren) specified by
f2351505 365.I pid
55ae3c86
MK
366exist, but have not yet changed state, then 0 is returned.
367On error, \-1 is returned.
f2351505 368
a5e0a0e4 369.BR waitid ():
c13182ef 370returns 0 on success or
f2351505
MK
371if
372.B WNOHANG
373was specified and no child(ren) specified by
374.I id
375has yet changed state;
376on error, \-1 is returned.
47f442b2
MK
377.\" FIXME: As reported by Vegard Nossum, if infop is NULL, then waitid()
378.\" returns the PID of the child. Either this is a bug, or it is intended
74ee79b9 379.\" behavior that needs to be documented. See my Jan 2009 LKML mail
47f442b2 380.\" "waitid() return value strangeness when infop is NULL".
f2351505 381Each of these calls sets
fea681da 382.I errno
f2351505 383to an appropriate value in the case of an error.
fea681da
MK
384.SH ERRORS
385.TP
0daa9e92 386.B ECHILD
c13182ef 387(for
e1d6264d 388.BR wait ())
fea681da
MK
389The calling process does not have any unwaited-for children.
390.TP
0daa9e92 391.B ECHILD
c13182ef
MK
392(for
393.BR waitpid ()
394or
e1d6264d 395.BR waitid ())
f2351505 396The process specified by
fea681da 397.I pid
f2351505
MK
398.RB ( waitpid ())
399or
400.I idtype
401and
402.I id
403.RB ( waitid ())
fea681da 404does not exist or is not a child of the calling process.
8bd58774
MK
405(This can happen for one's own child if the action for
406.B SIGCHLD
407is set to
408.BR SIG_IGN .
4fb31341 409See also the \fILinux Notes\fP section about threads.)
fea681da
MK
410.TP
411.B EINTR
412.B WNOHANG
413was not set and an unblocked signal or a
414.B SIGCHLD
01538d0d
MK
415was caught; see
416.BR signal (7).
fea681da
MK
417.TP
418.B EINVAL
419The
420.I options
421argument was invalid.
47297adb 422.SH CONFORMING TO
2dd578fd 423SVr4, 4.3BSD, POSIX.1-2001.
fea681da 424.SH NOTES
f2351505
MK
425A child that terminates, but has not been waited for becomes a "zombie".
426The kernel maintains a minimal set of information about the zombie
427process (PID, termination status, resource usage information)
428in order to allow the parent to later perform a wait to obtain
429information about the child.
430As long as a zombie is not removed from the system via a wait,
431it will consume a slot in the kernel process table, and if
432this table fills, it will not be possible to create further processes.
433If a parent process terminates, then its "zombie" children (if any)
434are adopted by
435.BR init (8),
436which automatically performs a wait to remove the zombies.
437
438POSIX.1-2001 specifies that if the disposition of
439.B SIGCHLD
c13182ef 440is set to
f2351505 441.B SIG_IGN
c13182ef 442or the
f2351505
MK
443.B SA_NOCLDWAIT
444flag is set for
0daa9e92 445.B SIGCHLD
c13182ef 446(see
f2351505
MK
447.BR sigaction (2)),
448then children that terminate do not become zombies and a call to
fea681da
MK
449.BR wait ()
450or
451.BR waitpid ()
f2351505 452will block until all children have terminated, and then fail with
fea681da 453.I errno
f2351505
MK
454set to
455.BR ECHILD .
d9bfdb9c 456(The original POSIX standard left the behavior of setting
f2351505
MK
457.B SIGCHLD
458to
459.B SIG_IGN
0e464c2f
MK
460unspecified.
461Note that even though the default disposition of
462.B SIGCHLD
463is "ignore", explicitly setting the disposition to
464.B SIG_IGN
465results in different treatment of zombie process children.)
f2351505
MK
466Linux 2.6 conforms to this specification.
467However, Linux 2.4 (and earlier) does not:
fea681da 468if a
c13182ef
MK
469.BR wait ()
470or
e1d6264d 471.BR waitpid ()
f2351505
MK
472call is made while
473.B SIGCHLD
474is being ignored, the call behaves just as though
475.B SIGCHLD
704a18f0 476were not being ignored, that is, the call blocks until the next child
d3b2ef5d 477terminates and then returns the process ID and status of that child.
c634028a 478.SS Linux notes
fea681da 479In the Linux kernel, a kernel-scheduled thread is not a distinct
c13182ef
MK
480construct from a process.
481Instead, a thread is simply a process
fea681da
MK
482that is created using the Linux-unique
483.BR clone (2)
484system call; other routines such as the portable
485.BR pthread_create (3)
486call are implemented using
487.BR clone (2).
488Before Linux 2.4, a thread was just a special case of a process,
489and as a consequence one thread could not wait on the children
490of another thread, even when the latter belongs to the same thread group.
491However, POSIX prescribes such functionality, and since Linux 2.4
492a thread can, and by default will, wait on children of other threads
493in the same thread group.
494.LP
8382f16d 495The following Linux-specific
fea681da
MK
496.I options
497are for use with children created using
948fb4ed
MK
498.BR clone (2);
499they cannot be used with
500.BR waitid ():
fea681da
MK
501.TP
502.B __WCLONE
503.\" since 0.99pl10
c13182ef 504Wait for "clone" children only.
f14ae16e 505If omitted, then wait for "non-clone" children only.
c13182ef 506(A "clone" child is one which delivers no signal, or a signal other than
fea681da
MK
507.B SIGCHLD
508to its parent upon termination.)
509This option is ignored if
510.B __WALL
511is also specified.
512.TP
31daf529 513.BR __WALL " (since Linux 2.4)"
fea681da 514.\" since patch-2.3.48
31daf529 515Wait for all children, regardless of
fea681da
MK
516type ("clone" or "non-clone").
517.TP
31daf529 518.BR __WNOTHREAD " (since Linux 2.4)"
fea681da 519.\" since patch-2.4.0-test8
31daf529 520Do not wait for children of other threads in
c13182ef
MK
521the same thread group.
522This was the default before Linux 2.4.
d8b13fb4
MK
523.PP
524The raw
525.BR waitid ()
526system call takes a fith argument, of type
527.IR "struct rusage\ *" .
528If this argument is non-NULL,
529then it is used to return resource usage information about the child,
530in the same manner as
531.BR wait4 (2).
532See
533.BR getrusage (2)
534for details.
7484d5a7
MK
535.SH BUGS
536According to POSIX.1-2008, an application calling
537.BR waitid ()
538must ensure that
539.I infop
540points to a
541.I siginfo_t
b437fdd9 542structure (i.e., that it is a non-null pointer).
7484d5a7
MK
543On Linux, if
544.I infop
545is NULL,
546.BR waitid ()
547succeeds, and returns the process ID of the waited-for child.
548Applications should avoid relying on this inconsistent,
549nonstandard, and unnecessary feature.
1fa343d1 550.SH EXAMPLE
cde9f44b 551.\" fork.2 refers to this example program.
c13182ef 552The following program demonstrates the use of
19dbfd0a 553.BR fork (2)
c13182ef 554and
2777b1ca 555.BR waitpid ().
1fa343d1 556The program creates a child process.
c13182ef
MK
557If no command-line argument is supplied to the program,
558then the child suspends its execution using
1fa343d1
MK
559.BR pause (2),
560to allow the user to send signals to the child.
561Otherwise, if a command-line argument is supplied,
c13182ef 562then the child exits immediately,
1fa343d1
MK
563using the integer supplied on the command line as the exit status.
564The parent process executes a loop that monitors the child using
2777b1ca 565.BR waitpid (),
d9bfdb9c 566and uses the W*() macros described above to analyze the wait status value.
1fa343d1
MK
567
568The following shell session demonstrates the use of the program:
9d0cc711 569.in +4n
1fa343d1
MK
570.nf
571
b43a3b30 572.RB "$" " ./a.out &"
1fa343d1
MK
573Child PID is 32360
574[1] 32359
b43a3b30 575.RB "$" " kill \-STOP 32360"
1fa343d1 576stopped by signal 19
b43a3b30 577.RB "$" " kill \-CONT 32360"
1fa343d1 578continued
b43a3b30 579.RB "$" " kill \-TERM 32360"
1fa343d1
MK
580killed by signal 15
581[1]+ Done ./a.out
582$
9d0cc711
MK
583.fi
584.in
9c330504 585.SS Program source
d84d0300 586\&
9d0cc711 587.nf
1fa343d1
MK
588#include <sys/wait.h>
589#include <stdlib.h>
590#include <unistd.h>
591#include <stdio.h>
592
593int
594main(int argc, char *argv[])
595{
596 pid_t cpid, w;
597 int status;
598
599 cpid = fork();
29059a65 600 if (cpid == \-1) {
45949175
MK
601 perror("fork");
602 exit(EXIT_FAILURE);
603 }
1fa343d1
MK
604
605 if (cpid == 0) { /* Code executed by child */
606 printf("Child PID is %ld\\n", (long) getpid());
607 if (argc == 1)
608 pause(); /* Wait for signals */
609 _exit(atoi(argv[1]));
610
611 } else { /* Code executed by parent */
612 do {
613 w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);
29059a65 614 if (w == \-1) {
45949175
MK
615 perror("waitpid");
616 exit(EXIT_FAILURE);
617 }
1fa343d1
MK
618
619 if (WIFEXITED(status)) {
620 printf("exited, status=%d\\n", WEXITSTATUS(status));
621 } else if (WIFSIGNALED(status)) {
622 printf("killed by signal %d\\n", WTERMSIG(status));
623 } else if (WIFSTOPPED(status)) {
624 printf("stopped by signal %d\\n", WSTOPSIG(status));
625 } else if (WIFCONTINUED(status)) {
626 printf("continued\\n");
627 }
628 } while (!WIFEXITED(status) && !WIFSIGNALED(status));
629 exit(EXIT_SUCCESS);
630 }
631}
1fa343d1 632.fi
47297adb 633.SH SEE ALSO
f2351505 634.BR _exit (2),
fea681da 635.BR clone (2),
f2351505
MK
636.BR fork (2),
637.BR kill (2),
fea681da 638.BR ptrace (2),
f2351505 639.BR sigaction (2),
fea681da
MK
640.BR signal (2),
641.BR wait4 (2),
642.BR pthread_create (3),
53a1443c 643.BR credentials (7),
fea681da 644.BR signal (7)