.\" 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 2016-12-12 "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
-_XOPEN_SOURCE
- || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
- || /* Glibc versions <= 2.19: */ _BSD_SOURCE
+Since glibc 2.26:
+_XOPEN_SOURCE >= 500 ||
+.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
+ _POSIX_C_SOURCE\ >=\ 200809L
+.br
+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
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).
Therefore, enclose its use inside
.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
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 wait ()
is actually a library function that (in glibc) is implemented as a call to
.BR wait4 (2).
-
+.PP
On some architectures, there is no
.BR waitpid ()
system call;
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