summaryrefslogtreecommitdiffstats
path: root/man/man2/wait.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/wait.2')
-rw-r--r--man/man2/wait.2721
1 files changed, 721 insertions, 0 deletions
diff --git a/man/man2/wait.2 b/man/man2/wait.2
new file mode 100644
index 0000000..818b976
--- /dev/null
+++ b/man/man2/wait.2
@@ -0,0 +1,721 @@
+.\" Copyright (c) 1993 by Thomas Koenig <ig25@rz.uni-karlsruhe.de>
+.\" and Copyright (c) 2004 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith <faith@cs.unc.edu>
+.\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith <faith@cs.unc.edu>
+.\" (Thanks to Koen Holtman <koen@win.tue.nl>)
+.\" Modified Wed May 17 15:54:12 1995 by Rik Faith <faith@cs.unc.edu>
+.\" To remove *'s from status in macros (Thanks to Michael Shields).
+.\" Modified as suggested by Nick Duffek <nsd@bbc.com>, aeb, 960426
+.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR.
+.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
+.\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler
+.\" <dwheeler@dwheeler.com> - noted thread issues.
+.\" Modified 26 Jun 01 by Michael Kerrisk
+.\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions
+.\" Modified 2001-09-25, aeb
+.\" Modified 26 Jun 01 by Michael Kerrisk, <mtk.manpages@gmail.com>
+.\" Updated notes on setting disposition of SIGCHLD to SIG_IGN
+.\" 2004-11-11, mtk
+.\" Added waitid(2); added WCONTINUED and WIFCONTINUED()
+.\" Added text on SA_NOCLDSTOP
+.\" Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior
+.\" Much other text rewritten
+.\" 2005-05-10, mtk, __W* flags can't be used with waitid()
+.\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP
+.\"
+.TH wait 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+wait, waitpid, waitid \- wait for process to change state
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/wait.h>
+.P
+.BI "pid_t wait(int *_Nullable " "wstatus" );
+.BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options );
+.P
+.BI "int waitid(idtype_t " idtype ", id_t " id \
+", siginfo_t *" infop ", int " options );
+ /* This is the glibc and POSIX interface; see
+ NOTES for information on the raw system call. */
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR waitid ():
+.nf
+ Since glibc 2.26:
+ _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
+.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
+ glibc 2.25 and earlier:
+ _XOPEN_SOURCE
+ || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+ || /* glibc <= 2.19: */ _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+All of these system calls are used to wait for state changes
+in a child of the calling process, and obtain information
+about the child whose state has changed.
+A state change is considered to be: the child terminated;
+the child was stopped by a signal; or the child was resumed by a signal.
+In the case of a terminated child, performing a wait allows
+the system to release the resources associated with the child;
+if a wait is not performed, then the terminated child remains in
+a "zombie" state (see NOTES below).
+.P
+If a child has already changed state, then these calls return immediately.
+Otherwise, they block until either a child changes state or
+a signal handler interrupts the call (assuming that system calls
+are not automatically restarted using the
+.B SA_RESTART
+flag of
+.BR sigaction (2)).
+In the remainder of this page, a child whose state has changed
+and which has not yet been waited upon by one of these system
+calls is termed
+.IR waitable .
+.SS wait() and waitpid()
+The
+.BR wait ()
+system call suspends execution of the calling thread until one of its
+children terminates.
+The call
+.I wait(&wstatus)
+is equivalent to:
+.P
+.in +4n
+.EX
+waitpid(\-1, &wstatus, 0);
+.EE
+.in
+.P
+The
+.BR waitpid ()
+system call suspends execution of the calling thread until a
+child specified by
+.I pid
+argument has changed state.
+By default,
+.BR waitpid ()
+waits only for terminated children, but this behavior is modifiable
+via the
+.I options
+argument, as described below.
+.P
+The value of
+.I pid
+can be:
+.TP
+.RB "< " \-1
+meaning wait for any child process whose process group ID is
+equal to the absolute value of
+.IR pid .
+.TP
+.B \-1
+meaning wait for any child process.
+.TP
+.B 0
+meaning wait for any child process whose process group ID is
+equal to that of the calling process at the time of the call to
+.BR waitpid ().
+.TP
+.RB "> " 0
+meaning wait for the child whose process ID is equal to the
+value of
+.IR pid .
+.P
+The value of
+.I options
+is an OR of zero or more of the following constants:
+.TP
+.B WNOHANG
+return immediately if no child has exited.
+.TP
+.B WUNTRACED
+also return if a child has stopped
+(but not traced via
+.BR ptrace (2)).
+Status for
+.I traced
+children which have stopped is provided
+even if this option is not specified.
+.TP
+.BR WCONTINUED " (since Linux 2.6.10)"
+also return if a stopped child has been resumed by delivery of
+.BR SIGCONT .
+.P
+(For Linux-only options, see below.)
+.P
+If
+.I wstatus
+is not NULL,
+.BR wait ()
+and
+.BR waitpid ()
+store status information in the \fIint\fP to which it points.
+This integer can be inspected with the following macros (which
+take the integer itself as an argument, not a pointer to it,
+as is done in
+.BR wait ()
+and
+.BR waitpid ()!):
+.TP
+.BI WIFEXITED( wstatus )
+returns true if the child terminated normally, that is,
+by calling
+.BR exit (3)
+or
+.BR _exit (2),
+or by returning from main().
+.TP
+.BI WEXITSTATUS( wstatus )
+returns the exit status of the child.
+This consists of the least significant 8 bits of the
+.I status
+argument that the child specified in a call to
+.BR exit (3)
+or
+.BR _exit (2)
+or as the argument for a return statement in main().
+This macro should be employed only if
+.B WIFEXITED
+returned true.
+.TP
+.BI WIFSIGNALED( wstatus )
+returns true if the child process was terminated by a signal.
+.TP
+.BI WTERMSIG( wstatus )
+returns the number of the signal that caused the child process to
+terminate.
+This macro should be employed only if
+.B WIFSIGNALED
+returned true.
+.TP
+.BI WCOREDUMP( wstatus )
+returns true if the child produced a core dump (see
+.BR core (5)).
+This macro should be employed only if
+.B WIFSIGNALED
+returned true.
+.IP
+This macro is not specified in POSIX.1-2001 and is not available on
+some UNIX implementations (e.g., AIX, SunOS).
+Therefore, enclose its use inside
+.IR "#ifdef WCOREDUMP ... #endif" .
+.TP
+.BI WIFSTOPPED( wstatus )
+returns true if the child process was stopped by delivery of a signal;
+this is possible only if the call was done using
+.B WUNTRACED
+or when the child is being traced (see
+.BR ptrace (2)).
+.TP
+.BI WSTOPSIG( wstatus )
+returns the number of the signal which caused the child to stop.
+This macro should be employed only if
+.B WIFSTOPPED
+returned true.
+.TP
+.BI WIFCONTINUED( wstatus )
+(since Linux 2.6.10)
+returns true if the child process was resumed by delivery of
+.BR SIGCONT .
+.SS waitid()
+The
+.BR waitid ()
+system call (available since Linux 2.6.9) provides more precise
+control over which child state changes to wait for.
+.P
+The
+.I idtype
+and
+.I id
+arguments select the child(ren) to wait for, as follows:
+.TP
+.IR idtype " == " \fBP_PID\fP
+Wait for the child whose process ID matches
+.IR id .
+.TP
+.IR idtype " == " \fBP_PIDFD\fP " (since Linux 5.4)"
+.\" commit 3695eae5fee0605f316fbaad0b9e3de791d7dfaf
+Wait for the child referred to by the PID file descriptor specified in
+.IR id .
+(See
+.BR pidfd_open (2)
+for further information on PID file descriptors.)
+.TP
+.IR idtype " == " \fBP_PGID\fP
+Wait for any child whose process group ID matches
+.IR id .
+Since Linux 5.4,
+.\" commit 821cc7b0b205c0df64cce59aacc330af251fa8f7
+if
+.I id
+is zero, then wait for any child that is in the same process group
+as the caller's process group at the time of the call.
+.TP
+.IR idtype " == " \fBP_ALL\fP
+Wait for any child;
+.I id
+is ignored.
+.P
+The child state changes to wait for are specified by ORing
+one or more of the following flags in
+.IR options :
+.TP
+.B WEXITED
+Wait for children that have terminated.
+.TP
+.B WSTOPPED
+Wait for children that have been stopped by delivery of a signal.
+.TP
+.B WCONTINUED
+Wait for (previously stopped) children that have been
+resumed by delivery of
+.BR SIGCONT .
+.P
+The following flags may additionally be ORed in
+.IR options :
+.TP
+.B WNOHANG
+As for
+.BR waitpid ().
+.TP
+.B WNOWAIT
+Leave the child in a waitable state; a later wait call
+can be used to again retrieve the child status information.
+.P
+Upon successful return,
+.BR waitid ()
+fills in the following fields of the
+.I siginfo_t
+structure pointed to by
+.IR infop :
+.TP
+\fIsi_pid\fP
+The process ID of the child.
+.TP
+\fIsi_uid\fP
+The real user ID of the child.
+(This field is not set on most other implementations.)
+.TP
+\fIsi_signo\fP
+Always set to
+.BR SIGCHLD .
+.TP
+\fIsi_status\fP
+Either the exit status of the child, as given to
+.BR _exit (2)
+(or
+.BR exit (3)),
+or the signal that caused the child to terminate, stop, or continue.
+The
+.I si_code
+field can be used to determine how to interpret this field.
+.TP
+\fIsi_code\fP
+Set to one of:
+.B CLD_EXITED
+(child called
+.BR _exit (2));
+.B CLD_KILLED
+(child killed by signal);
+.B CLD_DUMPED
+(child killed by signal, and dumped core);
+.B CLD_STOPPED
+(child stopped by signal);
+.B CLD_TRAPPED
+(traced child has trapped); or
+.B CLD_CONTINUED
+(child continued by
+.BR SIGCONT ).
+.P
+If
+.B WNOHANG
+was specified in
+.I options
+and there were no children in a waitable state, then
+.BR waitid ()
+returns 0 immediately and
+the state of the
+.I siginfo_t
+structure pointed to by
+.I infop
+depends on the implementation.
+To (portably) distinguish this case from that where a child was in a
+waitable state, zero out the
+.I si_pid
+field before the call and check for a nonzero value in this field
+after the call returns.
+.P
+POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when
+.B WNOHANG
+is specified in
+.I options
+and there were no children in a waitable state, then
+.BR waitid ()
+should zero out the
+.I si_pid
+and
+.I si_signo
+fields of the structure.
+On Linux and other implementations that adhere to this requirement,
+it is not necessary to zero out the
+.I si_pid
+field before calling
+.BR waitid ().
+However,
+not all implementations follow the POSIX.1 specification on this point.
+.\" POSIX.1-2001 leaves this possibility unspecified; most
+.\" implementations (including Linux) zero out the structure
+.\" in this case, but at least one implementation (AIX 5.1)
+.\" does not -- MTK Nov 04
+.SH RETURN VALUE
+.BR wait ():
+on success, returns the process ID of the terminated child;
+on failure, \-1 is returned.
+.P
+.BR waitpid ():
+on success, returns the process ID of the child whose state has changed;
+if
+.B WNOHANG
+was specified and one or more child(ren) specified by
+.I pid
+exist, but have not yet changed state, then 0 is returned.
+On failure, \-1 is returned.
+.P
+.BR waitid ():
+returns 0 on success or
+if
+.B WNOHANG
+was specified and no child(ren) specified by
+.I id
+has yet changed state;
+on failure, \-1 is returned.
+.\" FIXME As reported by Vegard Nossum, if infop is NULL, then waitid()
+.\" returns the PID of the child. Either this is a bug, or it is intended
+.\" behavior that needs to be documented. See my Jan 2009 LKML mail
+.\" "waitid() return value strangeness when infop is NULL".
+.P
+On failure, each of these calls sets
+.I errno
+to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The PID file descriptor specified in
+.I id
+is nonblocking and the process that it refers to has not terminated.
+.TP
+.B ECHILD
+(for
+.BR wait ())
+The calling process does not have any unwaited-for children.
+.TP
+.B ECHILD
+(for
+.BR waitpid ()
+or
+.BR waitid ())
+The process specified by
+.I pid
+.RB ( waitpid ())
+or
+.I idtype
+and
+.I id
+.RB ( waitid ())
+does not exist or is not a child of the calling process.
+(This can happen for one's own child if the action for
+.B SIGCHLD
+is set to
+.BR SIG_IGN .
+See also the \fILinux Notes\fP section about threads.)
+.TP
+.B EINTR
+.B WNOHANG
+was not set and an unblocked signal or a
+.B SIGCHLD
+was caught; see
+.BR signal (7).
+.TP
+.B EINVAL
+The
+.I options
+argument was invalid.
+.TP
+.B ESRCH
+(for
+.BR wait ()
+or
+.BR waitpid ())
+.I pid
+is equal to
+.BR INT_MIN .
+.SH VERSIONS
+.SS C library/kernel differences
+.BR wait ()
+is actually a library function that (in glibc) is implemented as a call to
+.BR wait4 (2).
+.P
+On some architectures, there is no
+.BR waitpid ()
+system call;
+.\" e.g., i386 has the system call, but not x86-64
+instead, this interface is implemented via a C library
+wrapper function that calls
+.BR wait4 (2).
+.P
+The raw
+.BR waitid ()
+system call takes a fifth argument, of type
+.IR "struct rusage\ *" .
+If this argument is non-NULL,
+then it is used to return resource usage information about the child,
+in the same manner as
+.BR wait4 (2).
+See
+.BR getrusage (2)
+for details.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+SVr4, 4.3BSD, POSIX.1-2001.
+.SH NOTES
+A child that terminates, but has not been waited for becomes a "zombie".
+The kernel maintains a minimal set of information about the zombie
+process (PID, termination status, resource usage information)
+in order to allow the parent to later perform a wait to obtain
+information about the child.
+As long as a zombie is not removed from the system via a wait,
+it will consume a slot in the kernel process table, and if
+this table fills, it will not be possible to create further processes.
+If a parent process terminates, then its "zombie" children (if any)
+are adopted by
+.BR init (1),
+(or by the nearest "subreaper" process as defined through the use of the
+.BR prctl (2)
+.B PR_SET_CHILD_SUBREAPER
+operation);
+.BR init (1)
+automatically performs a wait to remove the zombies.
+.P
+POSIX.1-2001 specifies that if the disposition of
+.B SIGCHLD
+is set to
+.B SIG_IGN
+or the
+.B SA_NOCLDWAIT
+flag is set for
+.B SIGCHLD
+(see
+.BR sigaction (2)),
+then children that terminate do not become zombies and a call to
+.BR wait ()
+or
+.BR waitpid ()
+will block until all children have terminated, and then fail with
+.I errno
+set to
+.BR ECHILD .
+(The original POSIX standard left the behavior of setting
+.B SIGCHLD
+to
+.B SIG_IGN
+unspecified.
+Note that even though the default disposition of
+.B SIGCHLD
+is "ignore", explicitly setting the disposition to
+.B SIG_IGN
+results in different treatment of zombie process children.)
+.P
+Linux 2.6 conforms to the POSIX requirements.
+However, Linux 2.4 (and earlier) does not:
+if a
+.BR wait ()
+or
+.BR waitpid ()
+call is made while
+.B SIGCHLD
+is being ignored, the call behaves just as though
+.B SIGCHLD
+were not being ignored, that is, the call blocks until the next child
+terminates and then returns the process ID and status of that child.
+.SS Linux notes
+In the Linux kernel, a kernel-scheduled thread is not a distinct
+construct from a process.
+Instead, a thread is simply a process
+that is created using the Linux-unique
+.BR clone (2)
+system call; other routines such as the portable
+.BR pthread_create (3)
+call are implemented using
+.BR clone (2).
+Before Linux 2.4, a thread was just a special case of a process,
+and as a consequence one thread could not wait on the children
+of another thread, even when the latter belongs to the same thread group.
+However, POSIX prescribes such functionality, and since Linux 2.4
+a thread can, and by default will, wait on children of other threads
+in the same thread group.
+.P
+The following Linux-specific
+.I options
+are for use with children created using
+.BR clone (2);
+they can also, since Linux 4.7,
+.\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba
+be used with
+.BR waitid ():
+.TP
+.B __WCLONE
+.\" since 0.99pl10
+Wait for "clone" children only.
+If omitted, then wait for "non-clone" children only.
+(A "clone" child is one which delivers no signal, or a signal other than
+.B SIGCHLD
+to its parent upon termination.)
+This option is ignored if
+.B __WALL
+is also specified.
+.TP
+.BR __WALL " (since Linux 2.4)"
+.\" since patch-2.3.48
+Wait for all children, regardless of
+type ("clone" or "non-clone").
+.TP
+.BR __WNOTHREAD " (since Linux 2.4)"
+.\" since patch-2.4.0-test8
+Do not wait for children of other threads in
+the same thread group.
+This was the default before Linux 2.4.
+.P
+Since Linux 4.7,
+.\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c
+.\" prevents cases where an unreapable zombie is created if
+.\" /sbin/init doesn't use __WALL.
+the
+.B __WALL
+flag is automatically implied if the child is being ptraced.
+.SH BUGS
+According to POSIX.1-2008, an application calling
+.BR waitid ()
+must ensure that
+.I infop
+points to a
+.I siginfo_t
+structure (i.e., that it is a non-null pointer).
+On Linux, if
+.I infop
+is NULL,
+.BR waitid ()
+succeeds, and returns the process ID of the waited-for child.
+Applications should avoid relying on this inconsistent,
+nonstandard, and unnecessary feature.
+.SH EXAMPLES
+.\" fork.2 refers to this example program.
+The following program demonstrates the use of
+.BR fork (2)
+and
+.BR waitpid ().
+The program creates a child process.
+If no command-line argument is supplied to the program,
+then the child suspends its execution using
+.BR pause (2),
+to allow the user to send signals to the child.
+Otherwise, if a command-line argument is supplied,
+then the child exits immediately,
+using the integer supplied on the command line as the exit status.
+The parent process executes a loop that monitors the child using
+.BR waitpid (),
+and uses the W*() macros described above to analyze the wait status value.
+.P
+The following shell session demonstrates the use of the program:
+.P
+.in +4n
+.EX
+.RB "$" " ./a.out &"
+Child PID is 32360
+[1] 32359
+.RB "$" " kill \-STOP 32360"
+stopped by signal 19
+.RB "$" " kill \-CONT 32360"
+continued
+.RB "$" " kill \-TERM 32360"
+killed by signal 15
+[1]+ Done ./a.out
+$
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (wait.c)
+.EX
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+#include <unistd.h>
+\&
+int
+main(int argc, char *argv[])
+{
+ int wstatus;
+ pid_t cpid, w;
+\&
+ cpid = fork();
+ if (cpid == \-1) {
+ perror("fork");
+ exit(EXIT_FAILURE);
+ }
+\&
+ if (cpid == 0) { /* Code executed by child */
+ printf("Child PID is %jd\en", (intmax_t) getpid());
+ if (argc == 1)
+ pause(); /* Wait for signals */
+ _exit(atoi(argv[1]));
+\&
+ } else { /* Code executed by parent */
+ do {
+ w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED);
+ if (w == \-1) {
+ perror("waitpid");
+ exit(EXIT_FAILURE);
+ }
+\&
+ if (WIFEXITED(wstatus)) {
+ printf("exited, status=%d\en", WEXITSTATUS(wstatus));
+ } else if (WIFSIGNALED(wstatus)) {
+ printf("killed by signal %d\en", WTERMSIG(wstatus));
+ } else if (WIFSTOPPED(wstatus)) {
+ printf("stopped by signal %d\en", WSTOPSIG(wstatus));
+ } else if (WIFCONTINUED(wstatus)) {
+ printf("continued\en");
+ }
+ } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
+ exit(EXIT_SUCCESS);
+ }
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR _exit (2),
+.BR clone (2),
+.BR fork (2),
+.BR kill (2),
+.BR ptrace (2),
+.BR sigaction (2),
+.BR signal (2),
+.BR wait4 (2),
+.BR pthread_create (3),
+.BR core (5),
+.BR credentials (7),
+.BR signal (7)