Debian Codegraph @

upstream/debian-unstable/man2/wait.2

raw
1 .\" Copyright 1993, Thomas Koenig <[email protected]>
2 .\" Copyright 2004, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH wait 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wait, waitpid, waitid \- wait for process to change state
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/wait.h>
16 .P
17 .BI "pid_t wait(int *_Nullable " "wstatus" );
18 .BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options );
19 .P
20 .BI "int waitid(idtype_t " idtype ", id_t " id \
21 ", siginfo_t *" infop ", int " options );
22 /* This is the glibc and POSIX interface; see
23 VERSIONS for information on the raw system call. */
24 .fi
25 .P
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .P
31 .BR waitid ():
32 .nf
33 Since glibc 2.26:
34 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
35 .\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
36 glibc 2.25 and earlier:
37 _XOPEN_SOURCE
38 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
39 || /* glibc <= 2.19: */ _BSD_SOURCE
40 .fi
41 .SH DESCRIPTION
42 All of these system calls are used
43 to wait for state changes
44 in a child of the calling process,
45 and obtain information
46 about the child whose state has changed.
47 A state change is considered to be:
48 the child terminated;
49 the child was stopped by a signal;
50 or the child was resumed by a signal.
51 In the case of a terminated child,
52 performing a wait allows the system to
53 release the resources associated with the child;
54 if a wait is not performed,
55 then the terminated child remains
56 in a "zombie" state
57 (see NOTES below).
58 .P
59 If a child has already changed state, then these calls return immediately.
60 Otherwise, they block until either a child changes state or
61 a signal handler interrupts the call (assuming that system calls
62 are not automatically restarted using the
63 .B SA_RESTART
64 flag of
65 .BR sigaction (2)).
66 In the remainder of this page, a child whose state has changed
67 and which has not yet been waited upon by one of these system
68 calls is termed
69 .IR waitable .
70 .SS wait() and waitpid()
71 The
72 .BR wait ()
73 system call suspends execution of the calling thread until one of its
74 children terminates.
75 The call
76 .I wait(&wstatus)
77 is equivalent to:
78 .P
79 .in +4n
80 .EX
81 waitpid(\-1, &wstatus, 0);
82 .EE
83 .in
84 .P
85 The
86 .BR waitpid ()
87 system call suspends execution of the calling thread until a
88 child specified by
89 .I pid
90 argument has changed state.
91 By default,
92 .BR waitpid ()
93 waits only for terminated children, but this behavior is modifiable
94 via the
95 .I options
96 argument, as described below.
97 .P
98 The value of
99 .I pid
100 can be:
101 .TP
102 .RB "< " \-1
103 meaning wait for any child process whose process group ID is
104 equal to the absolute value of
105 .IR pid .
106 .TP
107 .B \-1
108 meaning wait for any child process.
109 .TP
110 .B 0
111 meaning wait for any child process whose process group ID is
112 equal to that of the calling process at the time of the call to
113 .BR waitpid ().
114 .TP
115 .RB "> " 0
116 meaning wait for the child whose process ID is equal to the
117 value of
118 .IR pid .
119 .P
120 The value of
121 .I options
122 is an OR of zero or more of the following constants:
123 .TP
124 .B WNOHANG
125 return immediately if no child has exited.
126 .TP
127 .B WUNTRACED
128 also return if a child has stopped
129 (but not traced via
130 .BR ptrace (2)).
131 Status for
132 .I traced
133 children which have stopped is provided
134 even if this option is not specified.
135 .TP
136 .BR WCONTINUED " (since Linux 2.6.10)"
137 also return if a stopped child has been resumed by delivery of
138 .BR SIGCONT .
139 .P
140 (For Linux-only options, see below.)
141 .P
142 If
143 .I wstatus
144 is not NULL,
145 .BR wait ()
146 and
147 .BR waitpid ()
148 store status information in the
149 .I int
150 to which it points.
151 This integer can be inspected with the following macros (which
152 take the integer itself as an argument, not a pointer to it,
153 as is done in
154 .BR wait ()
155 and
156 .BR waitpid ()!):
157 .TP
158 .BI WIFEXITED( wstatus )
159 returns true if the child terminated normally, that is,
160 by calling
161 .BR exit (3)
162 or
163 .BR _exit (2),
164 or by returning from main().
165 .TP
166 .BI WEXITSTATUS( wstatus )
167 returns the exit status of the child.
168 This consists of the least significant 8 bits of the
169 .I status
170 argument that the child specified in a call to
171 .BR exit (3)
172 or
173 .BR _exit (2)
174 or as the argument for a return statement in main().
175 This macro should be employed only if
176 .B WIFEXITED
177 returned true.
178 .TP
179 .BI WIFSIGNALED( wstatus )
180 returns true if the child process was terminated by a signal.
181 .TP
182 .BI WTERMSIG( wstatus )
183 returns the number of the signal that caused the child process to
184 terminate.
185 This macro should be employed only if
186 .B WIFSIGNALED
187 returned true.
188 .TP
189 .BI WCOREDUMP( wstatus ) " \f[R]// POSIX.1-2024\f[]"
190 returns true if the child produced a core dump (see
191 .BR core (5)).
192 This macro should be employed only if
193 .B WIFSIGNALED
194 returned true.
195 .TP
196 .BI WIFSTOPPED( wstatus ) " \f[R]// POSIX.1-2024\f[]"
197 returns true if the child process was stopped by delivery of a signal;
198 this is possible only if the call was done using
199 .B WUNTRACED
200 or when the child is being traced (see
201 .BR ptrace (2)).
202 .TP
203 .BI WSTOPSIG( wstatus )
204 returns the number of the signal which caused the child to stop.
205 This macro should be employed only if
206 .B WIFSTOPPED
207 returned true.
208 .TP
209 .BI WIFCONTINUED( wstatus )
210 (since Linux 2.6.10)
211 returns true if the child process was resumed by delivery of
212 .BR SIGCONT .
213 .SS waitid()
214 The
215 .BR waitid ()
216 system call (available since Linux 2.6.9) provides more precise
217 control over which child state changes to wait for.
218 .P
219 The
220 .I idtype
221 and
222 .I id
223 arguments select the child(ren) to wait for, as follows:
224 .TP
225 .IR idtype " == " \f[B]P_PID\f[]
226 Wait for the child whose process ID matches
227 .IR id .
228 .TP
229 .IR idtype " == " \f[B]P_PIDFD\f[] " (since Linux 5.4)"
230 .\" commit 3695eae5fee0605f316fbaad0b9e3de791d7dfaf
231 Wait for the child referred to by the PID file descriptor specified in
232 .IR id .
233 (See
234 .BR pidfd_open (2)
235 for further information on PID file descriptors.)
236 .TP
237 .IR idtype " == " \f[B]P_PGID\f[]
238 Wait for any child whose process group ID matches
239 .IR id .
240 Since Linux 5.4,
241 .\" commit 821cc7b0b205c0df64cce59aacc330af251fa8f7
242 if
243 .I id
244 is zero, then wait for any child that is in the same process group
245 as the caller's process group at the time of the call.
246 .TP
247 .IR idtype " == " \f[B]P_ALL\f[]
248 Wait for any child;
249 .I id
250 is ignored.
251 .P
252 The child state changes to wait for are specified by ORing
253 one or more of the following flags in
254 .IR options :
255 .TP
256 .B WEXITED
257 Wait for children that have terminated.
258 .TP
259 .B WSTOPPED
260 Wait for children that have been stopped by delivery of a signal.
261 .TP
262 .B WCONTINUED
263 Wait for (previously stopped) children that have been
264 resumed by delivery of
265 .BR SIGCONT .
266 .P
267 The following flags may additionally be ORed in
268 .IR options :
269 .TP
270 .B WNOHANG
271 As for
272 .BR waitpid ().
273 .TP
274 .B WNOWAIT
275 Leave the child in a waitable state;
276 a later wait call
277 can be used to again retrieve the child status information.
278 .P
279 Upon successful return,
280 .BR waitid ()
281 fills in the following fields of the
282 .I siginfo_t
283 structure pointed to by
284 .IR infop :
285 .TP
286 .I si_pid
287 The process ID of the child.
288 .TP
289 .I si_uid
290 The real user ID of the child.
291 (This field is not set on most other implementations.)
292 .TP
293 .I si_signo
294 Always set to
295 .BR SIGCHLD .
296 .TP
297 .I si_status
298 Either the exit status of the child, as given to
299 .BR _exit (2)
300 (or
301 .BR exit (3)),
302 or the signal that caused the child to terminate, stop, or continue.
303 The
304 .I si_code
305 field can be used to determine how to interpret this field.
306 .TP
307 .I si_code
308 Set to one of:
309 .B CLD_EXITED
310 (child called
311 .BR _exit (2));
312 .B CLD_KILLED
313 (child killed by signal);
314 .B CLD_DUMPED
315 (child killed by signal, and dumped core);
316 .B CLD_STOPPED
317 (child stopped by signal);
318 .B CLD_TRAPPED
319 (traced child has trapped);
320 or
321 .B CLD_CONTINUED
322 (child continued by
323 .BR SIGCONT ).
324 .P
325 If
326 .B WNOHANG
327 was specified in
328 .I options
329 and there were no children in a waitable state, then
330 .BR waitid ()
331 returns 0 immediately and
332 the state of the
333 .I siginfo_t
334 structure pointed to by
335 .I infop
336 depends on the implementation.
337 To (portably) distinguish this case from that where a child was in a
338 waitable state, zero out the
339 .I si_pid
340 field before the call and check for a nonzero value in this field
341 after the call returns.
342 .P
343 POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when
344 .B WNOHANG
345 is specified in
346 .I options
347 and there were no children in a waitable state, then
348 .BR waitid ()
349 should zero out the
350 .I si_pid
351 and
352 .I si_signo
353 fields of the structure.
354 On Linux and other implementations that adhere to this requirement,
355 it is not necessary to zero out the
356 .I si_pid
357 field before calling
358 .BR waitid ().
359 However,
360 not all implementations follow the POSIX.1 specification on this point.
361 .\" POSIX.1-2001 leaves this possibility unspecified; most
362 .\" implementations (including Linux) zero out the structure
363 .\" in this case, but at least one implementation (AIX 5.1)
364 .\" does not -- MTK Nov 04
365 .SH RETURN VALUE
366 .BR wait ():
367 on success, returns the process ID of the terminated child;
368 on failure, \-1 is returned.
369 .P
370 .BR waitpid ():
371 on success, returns the process ID of the child whose state has changed;
372 if
373 .B WNOHANG
374 was specified and one or more child(ren) specified by
375 .I pid
376 exist, but have not yet changed state, then 0 is returned.
377 On failure, \-1 is returned.
378 .P
379 .BR waitid ():
380 returns 0 on success or
381 if
382 .B WNOHANG
383 was specified and no child(ren) specified by
384 .I id
385 has yet changed state;
386 on failure, \-1 is returned.
387 .\" FIXME As reported by Vegard Nossum, if infop is NULL, then waitid()
388 .\" returns the PID of the child. Either this is a bug, or it is intended
389 .\" behavior that needs to be documented. See my Jan 2009 LKML mail
390 .\" "waitid() return value strangeness when infop is NULL".
391 .P
392 On failure, each of these calls sets
393 .I errno
394 to indicate the error.
395 .SH ERRORS
396 .TP
397 .B EAGAIN
398 The PID file descriptor specified in
399 .I id
400 is nonblocking and the process that it refers to has not terminated.
401 .TP
402 .B ECHILD
403 (for
404 .BR wait ())
405 The calling process does not have any unwaited-for children.
406 .TP
407 .B ECHILD
408 (for
409 .BR waitpid ()
410 or
411 .BR waitid ())
412 The process specified by
413 .I pid
414 .RB ( waitpid ())
415 or
416 .I idtype
417 and
418 .I id
419 .RB ( waitid ())
420 does not exist or is not a child of the calling process.
421 (This can happen for one's own child if the action for
422 .B SIGCHLD
423 is set to
424 .BR SIG_IGN .
425 See also the
426 .I Linux\~Notes
427 section about threads.)
428 .TP
429 .B EINTR
430 .B WNOHANG
431 was not set and an unblocked signal or a
432 .B SIGCHLD
433 was caught;
434 see
435 .BR signal (7).
436 .TP
437 .B EINVAL
438 The
439 .I options
440 argument was invalid.
441 .TP
442 .B ESRCH
443 (for
444 .BR wait ()
445 or
446 .BR waitpid ())
447 .I pid
448 is equal to
449 .BR INT_MIN .
450 .SH VERSIONS
451 .SS C library/kernel differences
452 .BR wait ()
453 is actually a library function that (in glibc) is implemented as a call to
454 .BR wait4 (2).
455 .P
456 On some architectures, there is no
457 .BR waitpid ()
458 system call;
459 .\" e.g., i386 has the system call, but not x86-64
460 instead, this interface is implemented via a C library
461 wrapper function that calls
462 .BR wait4 (2).
463 .P
464 The raw
465 .BR waitid ()
466 system call takes a fifth argument, of type
467 .IR "struct rusage\ *" .
468 If this argument is non-NULL,
469 then it is used to return resource usage information about the child,
470 in the same manner as
471 .BR wait4 (2).
472 See
473 .BR getrusage (2)
474 for details.
475 .SH STANDARDS
476 POSIX.1-2024.
477 .SH HISTORY
478 SVr4, 4.3BSD, POSIX.1-2001.
479 .SH NOTES
480 A child that terminates, but has not been waited for becomes a "zombie".
481 The kernel maintains a minimal set of information about the zombie
482 process (PID, termination status, resource usage information)
483 in order to allow the parent to later perform a wait to obtain
484 information about the child.
485 As long as a zombie is not removed from the system via a wait,
486 it will consume a slot in the kernel process table, and if
487 this table fills, it will not be possible to create further processes.
488 If a parent process terminates, then its "zombie" children (if any)
489 are adopted by
490 .BR init (1),
491 (or by the nearest "subreaper" process as defined through the use of the
492 .BR prctl (2)
493 .B PR_SET_CHILD_SUBREAPER
494 operation);
495 .BR init (1)
496 automatically performs a wait to remove the zombies.
497 .P
498 POSIX.1-2001 specifies that if the disposition of
499 .B SIGCHLD
500 is set to
501 .B SIG_IGN
502 or the
503 .B SA_NOCLDWAIT
504 flag is set for
505 .B SIGCHLD
506 (see
507 .BR sigaction (2)),
508 then children that terminate do not become zombies and a call to
509 .BR wait ()
510 or
511 .BR waitpid ()
512 will block until all children have terminated, and then fail with
513 .I errno
514 set to
515 .BR ECHILD .
516 (The original POSIX standard left the behavior of setting
517 .B SIGCHLD
518 to
519 .B SIG_IGN
520 unspecified.
521 Note that even though the default disposition of
522 .B SIGCHLD
523 is "ignore", explicitly setting the disposition to
524 .B SIG_IGN
525 results in different treatment of zombie process children.)
526 .P
527 Linux 2.6 conforms to the POSIX requirements.
528 However, Linux 2.4 (and earlier) does not:
529 if a
530 .BR wait ()
531 or
532 .BR waitpid ()
533 call is made while
534 .B SIGCHLD
535 is being ignored, the call behaves just as though
536 .B SIGCHLD
537 were not being ignored, that is, the call blocks until the next child
538 terminates and then returns the process ID and status of that child.
539 .SS Linux notes
540 In the Linux kernel, a kernel-scheduled thread is not a distinct
541 construct from a process.
542 Instead,
543 a thread is simply a process
544 that is created using the Linux-unique
545 .BR clone (2)
546 system call;
547 other routines such as the portable
548 .BR pthread_create (3)
549 call are implemented using
550 .BR clone (2).
551 Before Linux 2.4,
552 a thread was just a special case of a process,
553 and as a consequence one thread could not wait on the children
554 of another thread, even when the latter belongs to the same thread group.
555 However, POSIX prescribes such functionality, and since Linux 2.4
556 a thread can, and by default will, wait on children of other threads
557 in the same thread group.
558 .P
559 The following Linux-specific
560 .I options
561 are for use with children created using
562 .BR clone (2);
563 they can also, since Linux 4.7,
564 .\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba
565 be used with
566 .BR waitid ():
567 .TP
568 .B __WCLONE
569 .\" since 0.99pl10
570 Wait for "clone" children only.
571 If omitted, then wait for "non-clone" children only.
572 (A "clone" child is one which delivers no signal, or a signal other than
573 .B SIGCHLD
574 to its parent upon termination.)
575 This option is ignored if
576 .B __WALL
577 is also specified.
578 .TP
579 .BR __WALL " (since Linux 2.4)"
580 .\" since patch-2.3.48
581 Wait for all children, regardless of
582 type ("clone" or "non-clone").
583 .TP
584 .BR __WNOTHREAD " (since Linux 2.4)"
585 .\" since patch-2.4.0-test8
586 Do not wait for children of other threads in
587 the same thread group.
588 This was the default before Linux 2.4.
589 .P
590 Since Linux 4.7,
591 .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c
592 .\" prevents cases where an unreapable zombie is created if
593 .\" /sbin/init doesn't use __WALL.
594 the
595 .B __WALL
596 flag is automatically implied if the child is being ptraced.
597 .SH BUGS
598 According to POSIX.1-2008, an application calling
599 .BR waitid ()
600 must ensure that
601 .I infop
602 points to a
603 .I siginfo_t
604 structure (i.e., that it is a non-null pointer).
605 On Linux, if
606 .I infop
607 is NULL,
608 .BR waitid ()
609 succeeds, and returns the process ID of the waited-for child.
610 Applications should avoid relying on this inconsistent,
611 nonstandard, and unnecessary feature.
612 .SH EXAMPLES
613 .\" fork.2 refers to this example program.
614 The following program demonstrates the use of
615 .BR fork (2)
616 and
617 .BR waitpid ().
618 The program creates a child process.
619 If no command-line argument is supplied to the program,
620 then the child suspends its execution using
621 .BR pause (2),
622 to allow the user to send signals to the child.
623 Otherwise, if a command-line argument is supplied,
624 then the child exits immediately,
625 using the integer supplied on the command line as the exit status.
626 The parent process executes a loop that monitors the child using
627 .BR waitpid (),
628 and uses the W*() macros described above to analyze the wait status value.
629 .P
630 The following shell session demonstrates the use of the program:
631 .P
632 .in +4n
633 .EX
634 .RB "$" " ./a.out &"
635 Child PID is 32360
636 [1] 32359
637 .RB "$" " kill \-STOP 32360"
638 stopped by signal 19
639 .RB "$" " kill \-CONT 32360"
640 continued
641 .RB "$" " kill \-TERM 32360"
642 killed by signal 15
643 [1]+ Done ./a.out
644 $
645 .EE
646 .in
647 .SS Program source
648 \&
649 .\" SRC BEGIN (wait.c)
650 .EX
651 #include <stdint.h>
652 #include <stdio.h>
653 #include <stdlib.h>
654 #include <sys/types.h>
655 #include <sys/wait.h>
656 #include <unistd.h>
657 \&
658 int
659 main(int argc, char *argv[])
660 {
661 int wstatus;
662 pid_t cpid, w;
663 \&
664 cpid = fork();
665 if (cpid == \-1) {
666 perror("fork");
667 exit(EXIT_FAILURE);
668 }
669 \&
670 if (cpid == 0) { /* Code executed by child */
671 printf("Child PID is %jd\[rs]n", (intmax_t) getpid());
672 if (argc == 1)
673 pause(); /* Wait for signals */
674 _exit(atoi(argv[1]));
675 \&
676 } else { /* Code executed by parent */
677 do {
678 w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED);
679 if (w == \-1) {
680 perror("waitpid");
681 exit(EXIT_FAILURE);
682 }
683 \&
684 if (WIFEXITED(wstatus)) {
685 printf("exited, status=%d\[rs]n", WEXITSTATUS(wstatus));
686 } else if (WIFSIGNALED(wstatus)) {
687 printf("killed by signal %d\[rs]n", WTERMSIG(wstatus));
688 } else if (WIFSTOPPED(wstatus)) {
689 printf("stopped by signal %d\[rs]n", WSTOPSIG(wstatus));
690 } else if (WIFCONTINUED(wstatus)) {
691 printf("continued\[rs]n");
692 }
693 } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
694 exit(EXIT_SUCCESS);
695 }
696 }
697 .EE
698 .\" SRC END
699 .SH SEE ALSO
700 .BR _exit (2),
701 .BR clone (2),
702 .BR fork (2),
703 .BR kill (2),
704 .BR ptrace (2),
705 .BR sigaction (2),
706 .BR signal (2),
707 .BR wait4 (2),
708 .BR pthread_create (3),
709 .BR core (5),
710 .BR credentials (7),
711 .BR signal (7)