Debian Codegraph @

upstream/debian-trixie/man2/wait.2

raw
1 .\" Copyright (c) 1993 by Thomas Koenig <[email protected]>
2 .\" and Copyright (c) 2004 by Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith <[email protected]>
7 .\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith <[email protected]>
8 .\" (Thanks to Koen Holtman <[email protected]>)
9 .\" Modified Wed May 17 15:54:12 1995 by Rik Faith <[email protected]>
10 .\" To remove *'s from status in macros (Thanks to Michael Shields).
11 .\" Modified as suggested by Nick Duffek <[email protected]>, 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 .\" <[email protected]> - 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, <[email protected]>
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 2024-06-15 "Linux man-pages 6.9.1"
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 .P
39 .BI "pid_t wait(int *_Nullable " "wstatus" );
40 .BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options );
41 .P
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 .P
48 .RS -4
49 Feature Test Macro Requirements for glibc (see
50 .BR feature_test_macros (7)):
51 .RE
52 .P
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 .P
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 .P
94 .in +4n
95 .EX
96 waitpid(\-1, &wstatus, 0);
97 .EE
98 .in
99 .P
100 The
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.
112 .P
113 The value of
114 .I pid
115 can be:
116 .TP
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 .
121 .TP
122 .B \-1
123 meaning wait for any child process.
124 .TP
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 ().
129 .TP
130 .RB "> " 0
131 meaning wait for the child whose process ID is equal to the
132 value of
133 .IR pid .
134 .P
135 The value of
136 .I options
137 is an OR of zero or more of the following constants:
138 .TP
139 .B WNOHANG
140 return immediately if no child has exited.
141 .TP
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.
150 .TP
151 .BR WCONTINUED " (since Linux 2.6.10)"
152 also return if a stopped child has been resumed by delivery of
153 .BR SIGCONT .
154 .P
155 (For Linux-only options, see below.)
156 .P
157 If
158 .I wstatus
159 is not NULL,
160 .BR wait ()
161 and
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 ()
168 and
169 .BR waitpid ()!):
170 .TP
171 .BI WIFEXITED( wstatus )
172 returns true if the child terminated normally, that is,
173 by calling
174 .BR exit (3)
175 or
176 .BR _exit (2),
177 or by returning from main().
178 .TP
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)
185 or
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.
191 .TP
192 .BI WIFSIGNALED( wstatus )
193 returns true if the child process was terminated by a signal.
194 .TP
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.
201 .TP
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.
208 .IP
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" .
213 .TP
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)).
220 .TP
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.
226 .TP
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()
232 The
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.
236 .P
237 The
238 .I idtype
239 and
240 .I id
241 arguments select the child(ren) to wait for, as follows:
242 .TP
243 .IR idtype " == " \fBP_PID\fP
244 Wait for the child whose process ID matches
245 .IR id .
246 .TP
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.)
254 .TP
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
260 if
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.
264 .TP
265 .IR idtype " == " \fBP_ALL\fP
266 Wait for any child;
267 .I id
268 is ignored.
269 .P
270 The child state changes to wait for are specified by ORing
271 one or more of the following flags in
272 .IR options :
273 .TP
274 .B WEXITED
275 Wait for children that have terminated.
276 .TP
277 .B WSTOPPED
278 Wait for children that have been stopped by delivery of a signal.
279 .TP
280 .B WCONTINUED
281 Wait for (previously stopped) children that have been
282 resumed by delivery of
283 .BR SIGCONT .
284 .P
285 The following flags may additionally be ORed in
286 .IR options :
287 .TP
288 .B WNOHANG
289 As for
290 .BR waitpid ().
291 .TP
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.
295 .P
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 :
302 .TP
303 \fIsi_pid\fP
304 The process ID of the child.
305 .TP
306 \fIsi_uid\fP
307 The real user ID of the child.
308 (This field is not set on most other implementations.)
309 .TP
310 \fIsi_signo\fP
311 Always set to
312 .BR SIGCHLD .
313 .TP
314 \fIsi_status\fP
315 Either the exit status of the child, as given to
316 .BR _exit (2)
317 (or
318 .BR exit (3)),
319 or the signal that caused the child to terminate, stop, or continue.
320 The
321 .I si_code
322 field can be used to determine how to interpret this field.
323 .TP
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 ).
340 .P
341 If
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.
358 .P
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
367 and
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.
385 .P
386 .BR waitpid ():
387 on success, returns the process ID of the child whose state has changed;
388 if
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.
394 .P
395 .BR waitid ():
396 returns 0 on success or
397 if
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".
407 .P
408 On failure, each of these calls sets
409 .I errno
410 to indicate the error.
411 .SH ERRORS
412 .TP
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.
417 .TP
418 .B ECHILD
419 (for
420 .BR wait ())
421 The calling process does not have any unwaited-for children.
422 .TP
423 .B ECHILD
424 (for
425 .BR waitpid ()
426 or
427 .BR waitid ())
428 The process specified by
429 .I pid
430 .RB ( waitpid ())
431 or
432 .I idtype
433 and
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.)
442 .TP
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).
449 .TP
450 .B EINVAL
451 The
452 .I options
453 argument was invalid.
454 .TP
455 .B ESRCH
456 (for
457 .BR wait ()
458 or
459 .BR waitpid ())
460 .I pid
461 is equal to
462 .BR INT_MIN .
463 .SH VERSIONS
464 .SS C library/kernel differences
465 .BR wait ()
466 is actually a library function that (in glibc) is implemented as a call to
467 .BR wait4 (2).
468 .P
469 On some architectures, there is no
470 .BR waitpid ()
471 system call;
472 .\" e.g., i386 has the system call, but not x86-64
473 instead, this interface is implemented via a C library
474 wrapper function that calls
475 .BR wait4 (2).
476 .P
477 The raw
478 .BR waitid ()
479 system call takes a fifth argument, of type
480 .IR "struct rusage\ *" .
481 If this argument is non-NULL,
482 then it is used to return resource usage information about the child,
483 in the same manner as
484 .BR wait4 (2).
485 See
486 .BR getrusage (2)
487 for details.
488 .SH STANDARDS
489 POSIX.1-2008.
490 .SH HISTORY
491 SVr4, 4.3BSD, POSIX.1-2001.
492 .SH NOTES
493 A child that terminates, but has not been waited for becomes a "zombie".
494 The kernel maintains a minimal set of information about the zombie
495 process (PID, termination status, resource usage information)
496 in order to allow the parent to later perform a wait to obtain
497 information about the child.
498 As long as a zombie is not removed from the system via a wait,
499 it will consume a slot in the kernel process table, and if
500 this table fills, it will not be possible to create further processes.
501 If a parent process terminates, then its "zombie" children (if any)
502 are adopted by
503 .BR init (1),
504 (or by the nearest "subreaper" process as defined through the use of the
505 .BR prctl (2)
506 .B PR_SET_CHILD_SUBREAPER
507 operation);
508 .BR init (1)
509 automatically performs a wait to remove the zombies.
510 .P
511 POSIX.1-2001 specifies that if the disposition of
512 .B SIGCHLD
513 is set to
514 .B SIG_IGN
515 or the
516 .B SA_NOCLDWAIT
517 flag is set for
518 .B SIGCHLD
519 (see
520 .BR sigaction (2)),
521 then children that terminate do not become zombies and a call to
522 .BR wait ()
523 or
524 .BR waitpid ()
525 will block until all children have terminated, and then fail with
526 .I errno
527 set to
528 .BR ECHILD .
529 (The original POSIX standard left the behavior of setting
530 .B SIGCHLD
531 to
532 .B SIG_IGN
533 unspecified.
534 Note that even though the default disposition of
535 .B SIGCHLD
536 is "ignore", explicitly setting the disposition to
537 .B SIG_IGN
538 results in different treatment of zombie process children.)
539 .P
540 Linux 2.6 conforms to the POSIX requirements.
541 However, Linux 2.4 (and earlier) does not:
542 if a
543 .BR wait ()
544 or
545 .BR waitpid ()
546 call is made while
547 .B SIGCHLD
548 is being ignored, the call behaves just as though
549 .B SIGCHLD
550 were not being ignored, that is, the call blocks until the next child
551 terminates and then returns the process ID and status of that child.
552 .SS Linux notes
553 In the Linux kernel, a kernel-scheduled thread is not a distinct
554 construct from a process.
555 Instead, a thread is simply a process
556 that is created using the Linux-unique
557 .BR clone (2)
558 system call; other routines such as the portable
559 .BR pthread_create (3)
560 call are implemented using
561 .BR clone (2).
562 Before Linux 2.4, a thread was just a special case of a process,
563 and as a consequence one thread could not wait on the children
564 of another thread, even when the latter belongs to the same thread group.
565 However, POSIX prescribes such functionality, and since Linux 2.4
566 a thread can, and by default will, wait on children of other threads
567 in the same thread group.
568 .P
569 The following Linux-specific
570 .I options
571 are for use with children created using
572 .BR clone (2);
573 they can also, since Linux 4.7,
574 .\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba
575 be used with
576 .BR waitid ():
577 .TP
578 .B __WCLONE
579 .\" since 0.99pl10
580 Wait for "clone" children only.
581 If omitted, then wait for "non-clone" children only.
582 (A "clone" child is one which delivers no signal, or a signal other than
583 .B SIGCHLD
584 to its parent upon termination.)
585 This option is ignored if
586 .B __WALL
587 is also specified.
588 .TP
589 .BR __WALL " (since Linux 2.4)"
590 .\" since patch-2.3.48
591 Wait for all children, regardless of
592 type ("clone" or "non-clone").
593 .TP
594 .BR __WNOTHREAD " (since Linux 2.4)"
595 .\" since patch-2.4.0-test8
596 Do not wait for children of other threads in
597 the same thread group.
598 This was the default before Linux 2.4.
599 .P
600 Since Linux 4.7,
601 .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c
602 .\" prevents cases where an unreapable zombie is created if
603 .\" /sbin/init doesn't use __WALL.
604 the
605 .B __WALL
606 flag is automatically implied if the child is being ptraced.
607 .SH BUGS
608 According to POSIX.1-2008, an application calling
609 .BR waitid ()
610 must ensure that
611 .I infop
612 points to a
613 .I siginfo_t
614 structure (i.e., that it is a non-null pointer).
615 On Linux, if
616 .I infop
617 is NULL,
618 .BR waitid ()
619 succeeds, and returns the process ID of the waited-for child.
620 Applications should avoid relying on this inconsistent,
621 nonstandard, and unnecessary feature.
622 .SH EXAMPLES
623 .\" fork.2 refers to this example program.
624 The following program demonstrates the use of
625 .BR fork (2)
626 and
627 .BR waitpid ().
628 The program creates a child process.
629 If no command-line argument is supplied to the program,
630 then the child suspends its execution using
631 .BR pause (2),
632 to allow the user to send signals to the child.
633 Otherwise, if a command-line argument is supplied,
634 then the child exits immediately,
635 using the integer supplied on the command line as the exit status.
636 The parent process executes a loop that monitors the child using
637 .BR waitpid (),
638 and uses the W*() macros described above to analyze the wait status value.
639 .P
640 The following shell session demonstrates the use of the program:
641 .P
642 .in +4n
643 .EX
644 .RB "$" " ./a.out &"
645 Child PID is 32360
646 [1] 32359
647 .RB "$" " kill \-STOP 32360"
648 stopped by signal 19
649 .RB "$" " kill \-CONT 32360"
650 continued
651 .RB "$" " kill \-TERM 32360"
652 killed by signal 15
653 [1]+ Done ./a.out
654 $
655 .EE
656 .in
657 .SS Program source
658 \&
659 .\" SRC BEGIN (wait.c)
660 .EX
661 #include <stdint.h>
662 #include <stdio.h>
663 #include <stdlib.h>
664 #include <sys/types.h>
665 #include <sys/wait.h>
666 #include <unistd.h>
667 \&
668 int
669 main(int argc, char *argv[])
670 {
671 int wstatus;
672 pid_t cpid, w;
673 \&
674 cpid = fork();
675 if (cpid == \-1) {
676 perror("fork");
677 exit(EXIT_FAILURE);
678 }
679 \&
680 if (cpid == 0) { /* Code executed by child */
681 printf("Child PID is %jd\[rs]n", (intmax_t) getpid());
682 if (argc == 1)
683 pause(); /* Wait for signals */
684 _exit(atoi(argv[1]));
685 \&
686 } else { /* Code executed by parent */
687 do {
688 w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED);
689 if (w == \-1) {
690 perror("waitpid");
691 exit(EXIT_FAILURE);
692 }
693 \&
694 if (WIFEXITED(wstatus)) {
695 printf("exited, status=%d\[rs]n", WEXITSTATUS(wstatus));
696 } else if (WIFSIGNALED(wstatus)) {
697 printf("killed by signal %d\[rs]n", WTERMSIG(wstatus));
698 } else if (WIFSTOPPED(wstatus)) {
699 printf("stopped by signal %d\[rs]n", WSTOPSIG(wstatus));
700 } else if (WIFCONTINUED(wstatus)) {
701 printf("continued\[rs]n");
702 }
703 } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
704 exit(EXIT_SUCCESS);
705 }
706 }
707 .EE
708 .\" SRC END
709 .SH SEE ALSO
710 .BR _exit (2),
711 .BR clone (2),
712 .BR fork (2),
713 .BR kill (2),
714 .BR ptrace (2),
715 .BR sigaction (2),
716 .BR signal (2),
717 .BR wait4 (2),
718 .BR pthread_create (3),
719 .BR core (5),
720 .BR credentials (7),
721 .BR signal (7)