tzfile.5, tzselect.8: sync from tzdb upstream
[man-pages.git] / man2 / wait.2
blobe2dcd59bda0916ee8a639ce7aa60a4e470bc240f
1 .\" Copyright (c) 1993 by Thomas Koenig <ig25@rz.uni-karlsruhe.de>
2 .\" and Copyright (c) 2004 by Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
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
21 .\" 2004-11-11, mtk
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
28 .\"
29 .TH wait 2 (date) "Linux man-pages (unreleased)"
30 .SH NAME
31 wait, waitpid, waitid \- wait for process to change state
32 .SH LIBRARY
33 Standard C library
34 .RI ( libc ", " \-lc )
35 .SH SYNOPSIS
36 .nf
37 .B #include <sys/wait.h>
38 .PP
39 .BI "pid_t wait(int *_Nullable " "wstatus" );
40 .BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options );
41 .PP
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. */
46 .fi
47 .PP
48 .RS -4
49 Feature Test Macro Requirements for glibc (see
50 .BR feature_test_macros (7)):
51 .RE
52 .PP
53 .BR waitid ():
54 .nf
55     Since glibc 2.26:
56         _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
57 .\"    (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
58     glibc 2.25 and earlier:
59         _XOPEN_SOURCE
60             || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
61             || /* glibc <= 2.19: */ _BSD_SOURCE
62 .fi
63 .SH DESCRIPTION
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).
73 .PP
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
78 .B SA_RESTART
79 flag of
80 .BR sigaction (2)).
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
83 calls is termed
84 .IR waitable .
85 .SS wait() and waitpid()
86 The
87 .BR wait ()
88 system call suspends execution of the calling thread until one of its
89 children terminates.
90 The call
91 .I wait(&wstatus)
92 is equivalent to:
93 .PP
94 .in +4n
95 .EX
96 waitpid(\-1, &wstatus, 0);
97 .EE
98 .in
99 .PP
101 .BR waitpid ()
102 system call suspends execution of the calling thread until a
103 child specified by
104 .I pid
105 argument has changed state.
106 By default,
107 .BR waitpid ()
108 waits only for terminated children, but this behavior is modifiable
109 via the
110 .I options
111 argument, as described below.
113 The value of
114 .I pid
115 can be:
117 .RB "< " \-1
118 meaning wait for any child process whose process group ID is
119 equal to the absolute value of
120 .IR pid .
122 .B \-1
123 meaning wait for any child process.
125 .B 0
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
128 .BR waitpid ().
130 .RB "> " 0
131 meaning wait for the child whose process ID is equal to the
132 value of
133 .IR pid .
135 The value of
136 .I options
137 is an OR of zero or more of the following constants:
139 .B WNOHANG
140 return immediately if no child has exited.
142 .B WUNTRACED
143 also return if a child has stopped
144 (but not traced via
145 .BR ptrace (2)).
146 Status for
147 .I traced
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
153 .BR SIGCONT .
155 (For Linux-only options, see below.)
158 .I wstatus
159 is not NULL,
160 .BR wait ()
162 .BR waitpid ()
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,
166 as is done in
167 .BR wait ()
169 .BR waitpid ()!):
171 .BI WIFEXITED( wstatus )
172 returns true if the child terminated normally, that is,
173 by calling
174 .BR exit (3)
176 .BR _exit (2),
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
182 .I status
183 argument that the child specified in a call to
184 .BR exit (3)
186 .BR _exit (2)
187 or as the argument for a return statement in main().
188 This macro should be employed only if
189 .B WIFEXITED
190 returned true.
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
197 terminate.
198 This macro should be employed only if
199 .B WIFSIGNALED
200 returned true.
202 .BI WCOREDUMP( wstatus )
203 returns true if the child produced a core dump (see
204 .BR core (5)).
205 This macro should be employed only if
206 .B WIFSIGNALED
207 returned true.
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
217 .B WUNTRACED
218 or when the child is being traced (see
219 .BR ptrace (2)).
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
224 .B WIFSTOPPED
225 returned true.
227 .BI WIFCONTINUED( wstatus )
228 (since Linux 2.6.10)
229 returns true if the child process was resumed by delivery of
230 .BR SIGCONT .
231 .SS waitid()
233 .BR waitid ()
234 system call (available since Linux 2.6.9) provides more precise
235 control over which child state changes to wait for.
238 .I idtype
240 .I id
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
245 .IR id .
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
250 .IR id .
251 (See
252 .BR pidfd_open (2)
253 for further information on PID file descriptors.)
255 .IR idtype " == " \fBP_PGID\fP
256 Wait for any child whose process group ID matches
257 .IR id .
258 Since Linux 5.4,
259 .\" commit 821cc7b0b205c0df64cce59aacc330af251fa8f7
261 .I id
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
266 Wait for any child;
267 .I id
268 is ignored.
270 The child state changes to wait for are specified by ORing
271 one or more of the following flags in
272 .IR options :
274 .B WEXITED
275 Wait for children that have terminated.
277 .B WSTOPPED
278 Wait for children that have been stopped by delivery of a signal.
280 .B WCONTINUED
281 Wait for (previously stopped) children that have been
282 resumed by delivery of
283 .BR SIGCONT .
285 The following flags may additionally be ORed in
286 .IR options :
288 .B WNOHANG
289 As for
290 .BR waitpid ().
292 .B WNOWAIT
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,
297 .BR waitid ()
298 fills in the following fields of the
299 .I siginfo_t
300 structure pointed to by
301 .IR infop :
303 \fIsi_pid\fP
304 The process ID of the child.
306 \fIsi_uid\fP
307 The real user ID of the child.
308 (This field is not set on most other implementations.)
310 \fIsi_signo\fP
311 Always set to
312 .BR SIGCHLD .
314 \fIsi_status\fP
315 Either the exit status of the child, as given to
316 .BR _exit (2)
318 .BR exit (3)),
319 or the signal that caused the child to terminate, stop, or continue.
321 .I si_code
322 field can be used to determine how to interpret this field.
324 \fIsi_code\fP
325 Set to one of:
326 .B CLD_EXITED
327 (child called
328 .BR _exit (2));
329 .B CLD_KILLED
330 (child killed by signal);
331 .B CLD_DUMPED
332 (child killed by signal, and dumped core);
333 .B CLD_STOPPED
334 (child stopped by signal);
335 .B CLD_TRAPPED
336 (traced child has trapped); or
337 .B CLD_CONTINUED
338 (child continued by
339 .BR SIGCONT ).
342 .B WNOHANG
343 was specified in
344 .I options
345 and there were no children in a waitable state, then
346 .BR waitid ()
347 returns 0 immediately and
348 the state of the
349 .I siginfo_t
350 structure pointed to by
351 .I infop
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
355 .I si_pid
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
360 .B WNOHANG
361 is specified in
362 .I options
363 and there were no children in a waitable state, then
364 .BR waitid ()
365 should zero out the
366 .I si_pid
368 .I si_signo
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
372 .I si_pid
373 field before calling
374 .BR waitid ().
375 However,
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
381 .SH RETURN VALUE
382 .BR wait ():
383 on success, returns the process ID of the terminated child;
384 on failure, \-1 is returned.
386 .BR waitpid ():
387 on success, returns the process ID of the child whose state has changed;
389 .B WNOHANG
390 was specified and one or more child(ren) specified by
391 .I pid
392 exist, but have not yet changed state, then 0 is returned.
393 On failure, \-1 is returned.
395 .BR waitid ():
396 returns 0 on success or
398 .B WNOHANG
399 was specified and no child(ren) specified by
400 .I id
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
409 .I errno
410 to indicate the error.
411 .SH ERRORS
413 .B EAGAIN
414 The PID file descriptor specified in
415 .I id
416 is nonblocking and the process that it refers to has not terminated.
418 .B ECHILD
419 (for
420 .BR wait ())
421 The calling process does not have any unwaited-for children.
423 .B ECHILD
424 (for
425 .BR waitpid ()
427 .BR waitid ())
428 The process specified by
429 .I pid
430 .RB ( waitpid ())
432 .I idtype
434 .I id
435 .RB ( waitid ())
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
438 .B SIGCHLD
439 is set to
440 .BR SIG_IGN .
441 See also the \fILinux Notes\fP section about threads.)
443 .B EINTR
444 .B WNOHANG
445 was not set and an unblocked signal or a
446 .B SIGCHLD
447 was caught; see
448 .BR signal (7).
450 .B EINVAL
452 .I options
453 argument was invalid.
455 .B ESRCH
456 (for
457 .BR wait ()
459 .BR waitpid ())
460 .I pid
461 is equal to
462 .BR INT_MIN .
463 .SH STANDARDS
464 SVr4, 4.3BSD, POSIX.1-2001.
465 .SH NOTES
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)
475 are adopted by
476 .BR init (1),
477 (or by the nearest "subreaper" process as defined through the use of the
478 .BR prctl (2)
479 .B PR_SET_CHILD_SUBREAPER
480 operation);
481 .BR init (1)
482 automatically performs a wait to remove the zombies.
484 POSIX.1-2001 specifies that if the disposition of
485 .B SIGCHLD
486 is set to
487 .B SIG_IGN
488 or the
489 .B SA_NOCLDWAIT
490 flag is set for
491 .B SIGCHLD
492 (see
493 .BR sigaction (2)),
494 then children that terminate do not become zombies and a call to
495 .BR wait ()
497 .BR waitpid ()
498 will block until all children have terminated, and then fail with
499 .I errno
500 set to
501 .BR ECHILD .
502 (The original POSIX standard left the behavior of setting
503 .B SIGCHLD
505 .B SIG_IGN
506 unspecified.
507 Note that even though the default disposition of
508 .B SIGCHLD
509 is "ignore", explicitly setting the disposition to
510 .B SIG_IGN
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:
515 if a
516 .BR wait ()
518 .BR waitpid ()
519 call is made while
520 .B SIGCHLD
521 is being ignored, the call behaves just as though
522 .B SIGCHLD
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.
525 .SS Linux notes
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
530 .BR clone (2)
531 system call; other routines such as the portable
532 .BR pthread_create (3)
533 call are implemented using
534 .BR clone (2).
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
543 .I options
544 are for use with children created using
545 .BR clone (2);
546 they can also, since Linux 4.7,
547 .\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba
548 be used with
549 .BR waitid ():
551 .B __WCLONE
552 .\" since 0.99pl10
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
556 .B SIGCHLD
557 to its parent upon termination.)
558 This option is ignored if
559 .B __WALL
560 is also specified.
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.
573 Since Linux 4.7,
574 .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c
575 .\" prevents cases where an unreapable zombie is created if
576 .\" /sbin/init doesn't use __WALL.
578 .B __WALL
579 flag is automatically implied if the child is being ptraced.
580 .SS C library/kernel differences
581 .BR wait ()
582 is actually a library function that (in glibc) is implemented as a call to
583 .BR wait4 (2).
585 On some architectures, there is no
586 .BR waitpid ()
587 system call;
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
591 .BR wait4 (2).
593 The raw
594 .BR waitid ()
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
600 .BR wait4 (2).
602 .BR getrusage (2)
603 for details.
604 .SH BUGS
605 According to POSIX.1-2008, an application calling
606 .BR waitid ()
607 must ensure that
608 .I infop
609 points to a
610 .I siginfo_t
611 structure (i.e., that it is a non-null pointer).
612 On Linux, if
613 .I infop
614 is NULL,
615 .BR waitid ()
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.
619 .SH EXAMPLES
620 .\" fork.2 refers to this example program.
621 The following program demonstrates the use of
622 .BR fork (2)
624 .BR waitpid ().
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
628 .BR pause (2),
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
634 .BR waitpid (),
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:
639 .in +4n
641 .RB "$" " ./a.out &"
642 Child PID is 32360
643 [1] 32359
644 .RB "$" " kill \-STOP 32360"
645 stopped by signal 19
646 .RB "$" " kill \-CONT 32360"
647 continued
648 .RB "$" " kill \-TERM 32360"
649 killed by signal 15
650 [1]+  Done                    ./a.out
654 .SS Program source
656 .\" SRC BEGIN (wait.c)
658 #include <stdint.h>
659 #include <stdio.h>
660 #include <stdlib.h>
661 #include <sys/wait.h>
662 #include <unistd.h>
665 main(int argc, char *argv[])
667     int    wstatus;
668     pid_t  cpid, w;
670     cpid = fork();
671     if (cpid == \-1) {
672         perror("fork");
673         exit(EXIT_FAILURE);
674     }
676     if (cpid == 0) {            /* Code executed by child */
677         printf("Child PID is %jd\en", (intmax_t) getpid());
678         if (argc == 1)
679             pause();                    /* Wait for signals */
680         _exit(atoi(argv[1]));
682     } else {                    /* Code executed by parent */
683         do {
684             w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED);
685             if (w == \-1) {
686                 perror("waitpid");
687                 exit(EXIT_FAILURE);
688             }
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");
698             }
699         } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
700         exit(EXIT_SUCCESS);
701     }
704 .\" SRC END
705 .SH SEE ALSO
706 .BR _exit (2),
707 .BR clone (2),
708 .BR fork (2),
709 .BR kill (2),
710 .BR ptrace (2),
711 .BR sigaction (2),
712 .BR signal (2),
713 .BR wait4 (2),
714 .BR pthread_create (3),
715 .BR core (5),
716 .BR credentials (7),
717 .BR signal (7)