.\" 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 2015-07-23 "Linux" "Linux Programmer's Manual"
+.TH WAIT 2 2020-04-11 "Linux" "Linux Programmer's Manual"
.SH NAME
wait, waitpid, waitid \- wait for process to change state
.SH SYNOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/wait.h>
-.sp
+.PP
.BI "pid_t wait(int *" "wstatus" );
-
+.PP
.BI "pid_t waitpid(pid_t " pid ", int *" wstatus ", int " options );
-
+.PP
.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. */
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.ad l
.PD 0
.BR waitid ():
.RS 4
-_SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500
-.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+Since glibc 2.26:
+_XOPEN_SOURCE >= 500 ||
+.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
+ _POSIX_C_SOURCE\ >=\ 200809L
.br
- || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
+Glibc 2.25 and earlier:
+ _XOPEN_SOURCE
+ || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
+ || /* Glibc versions <= 2.19: */ _BSD_SOURCE
.RE
.PD
.ad
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).
-
+.PP
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
.SS wait() and waitpid()
The
.BR wait ()
-system call suspends execution of the calling process until one of its
+system call suspends execution of the calling thread until one of its
children terminates.
The call
.I wait(&wstatus)
is equivalent to:
-.nf
-
- waitpid(\-1, &wstatus, 0);
-.fi
-
+.PP
+.in +4n
+.EX
+waitpid(\-1, &wstatus, 0);
+.EE
+.in
+.PP
The
.BR waitpid ()
-system call suspends execution of the calling process until a
+system call suspends execution of the calling thread until a
child specified by
.I pid
argument has changed state.
via the
.I options
argument, as described below.
-
+.PP
The value of
.I pid
can be:
meaning wait for any child process.
.IP 0
meaning wait for any child process whose process group ID is
-equal to that of the calling process.
+equal to that of the calling process at the time of the call to
+.BR waitpid ().
.IP "> 0"
meaning wait for the child whose process ID is equal to the
value of
The value of
.I options
is an OR of zero or more of the following constants:
-.TP 12
+.TP
.B WNOHANG
return immediately if no child has exited.
.TP
.BI WEXITSTATUS( wstatus )
returns the exit status of the child.
This consists of the least significant 8 bits of the
-.I wstatus
+.I status
argument that the child specified in a call to
.BR exit (3)
or
returned true.
.TP
.BI WCOREDUMP( wstatus )
-returns true if the child produced a core dump.
+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).
-Only use this enclosed in #ifdef WCOREDUMP ... #endif.
+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;
.BR waitid ()
system call (available since Linux 2.6.9) provides more precise
control over which child state changes to wait for.
-
+.PP
The
.I idtype
and
.IP "\fIidtype\fP == \fBP_PID\fP"
Wait for the child whose process ID matches
.IR id .
+.IP "\fIidtype\fP == \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.)
.IP "\fIidtype\fP == \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.
.IP "\fIidtype\fP == \fBP_ALL\fP"
Wait for any child;
.I id
The child state changes to wait for are specified by ORing
one or more of the following flags in
.IR options :
-.TP 12
+.TP
.B WEXITED
Wait for children that have terminated.
.TP
.PP
The following flags may additionally be ORed in
.IR options :
-.TP 12
+.TP
.B WNOHANG
As for
.BR waitpid ().
.I siginfo_t
structure pointed to by
.IR infop :
-.TP 12
+.TP
\fIsi_pid\fP
The process ID of the child.
.TP
.I siginfo_t
structure pointed to by
.I infop
-is unspecified.
-.\" 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
-To distinguish this case from that where a child was in a
+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.
+.PP
+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 error, \-1 is returned.
-
+.PP
.BR waitpid ():
on success, returns the process ID of the child whose state has changed;
if
.I pid
exist, but have not yet changed state, then 0 is returned.
On error, \-1 is returned.
-
+.PP
.BR waitid ():
returns 0 on success or
if
If a parent process terminates, then its "zombie" children (if any)
are adopted by
.BR init (1),
-which automatically performs a wait to remove the zombies.
-
+(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.
+.PP
POSIX.1-2001 specifies that if the disposition of
.B SIGCHLD
is set to
is "ignore", explicitly setting the disposition to
.B SIG_IGN
results in different treatment of zombie process children.)
-
+.PP
Linux 2.6 conforms to the POSIX requirements.
However, Linux 2.4 (and earlier) does not:
if a
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.
-.LP
+.PP
The following Linux-specific
.I options
are for use with children created using
.BR clone (2);
-they cannot be used with
+they can also, since Linux 4.7,
+.\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba
+be used with
.BR waitid ():
.TP
.B __WCLONE
Do not wait for children of other threads in
the same thread group.
This was the default before Linux 2.4.
+.PP
+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.
.SS C library/kernel differences
.BR wait ()
is actually a library function that (in glibc) is implemented as a call to
.BR wait4 (2).
-
-Within glibc,
-.\" A waitpid() system call remains, with a comment noting that
-.\" "waitpid() should be * implemented by calling sys_wait4() from libc.a"
+.PP
+On some architectures, there is no
.BR waitpid ()
-is a wrapper function that invokes
-.BR wait (2).
-
+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).
+.PP
The raw
.BR waitid ()
system call takes a fifth argument, of type
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.
-
+.PP
The following shell session demonstrates the use of the program:
+.PP
.in +4n
-.nf
-
+.EX
.RB "$" " ./a.out &"
Child PID is 32360
[1] 32359
killed by signal 15
[1]+ Done ./a.out
$
-.fi
+.EE
.in
.SS Program source
\&
-.nf
+.EX
#include <sys/wait.h>
#include <stdlib.h>
#include <unistd.h>
}
if (cpid == 0) { /* Code executed by child */
- printf("Child PID is %ld\\n", (long) getpid());
+ printf("Child PID is %ld\en", (long) getpid());
if (argc == 1)
pause(); /* Wait for signals */
_exit(atoi(argv[1]));
}
if (WIFEXITED(wstatus)) {
- printf("exited, status=%d\\n", WEXITSTATUS(wstatus));
+ printf("exited, status=%d\en", WEXITSTATUS(wstatus));
} else if (WIFSIGNALED(wstatus)) {
- printf("killed by signal %d\\n", WTERMSIG(wstatus));
+ printf("killed by signal %d\en", WTERMSIG(wstatus));
} else if (WIFSTOPPED(wstatus)) {
- printf("stopped by signal %d\\n", WSTOPSIG(wstatus));
+ printf("stopped by signal %d\en", WSTOPSIG(wstatus));
} else if (WIFCONTINUED(wstatus)) {
- printf("continued\\n");
+ printf("continued\en");
}
} while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
exit(EXIT_SUCCESS);
}
}
-.fi
+.EE
.SH SEE ALSO
.BR _exit (2),
.BR clone (2),
.BR signal (2),
.BR wait4 (2),
.BR pthread_create (3),
+.BR core (5),
.BR credentials (7),
.BR signal (7)
projects / thirdparty / man-pages.git / blobdiff