.\" 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 2017-05-03 "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
.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.
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
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 "\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;
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
\&
}
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);
.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