A call to the wait() or waitpid() function only returns status on
an immediate child process of the calling process; that is, a
child that was produced by a single fork() call (perhaps followed
by an exec or other function calls) from the parent. If a child
produces grandchildren by further use of fork(), none of those
grandchildren nor any of their descendants affect the behavior of
a wait() from the original parent process. Nothing in this volume
of POSIX.1‐2017 prevents an implementation from providing
extensions that permit a process to get status from a grandchild
or any other process, but a process that does not use such
extensions must be guaranteed to see status from only its direct
children.
The waitpid() function is provided for three reasons:
1. To support job control
2. To permit a non-blocking version of the wait() function
3. To permit a library routine, such as system() or pclose(), to
wait for its children without interfering with other
terminated children for which the process has not waited
The first two of these facilities are based on the wait3()
function provided by 4.3 BSD. The function uses the options
argument, which is equivalent to an argument to wait3(). The
WUNTRACED flag is used only in conjunction with job control on
systems supporting job control. Its name comes from 4.3 BSD and
refers to the fact that there are two types of stopped processes
in that implementation: processes being traced via the ptrace()
debugging facility and (untraced) processes stopped by job
control signals. Since ptrace() is not part of this volume of
POSIX.1‐2017, only the second type is relevant. The name
WUNTRACED was retained because its usage is the same, even though
the name is not intuitively meaningful in this context.
The third reason for the waitpid() function is to permit
independent sections of a process to spawn and wait for children
without interfering with each other. For example, the following
problem occurs in developing a portable shell, or command
interpreter:
stream = popen("/bin/true");
(void) system("sleep 100");
(void) pclose(stream);
On all historical implementations, the final pclose() fails to
reap the wait() status of the popen().
The status values are retrieved by macros, rather than given as
specific bit encodings as they are in most historical
implementations (and thus expected by existing programs). This
was necessary to eliminate a limitation on the number of signals
an implementation can support that was inherent in the
traditional encodings. This volume of POSIX.1‐2017 does require
that a status value of zero corresponds to a process calling
_exit(0), as this is the most common encoding expected by
existing programs. Some of the macro names were adopted from 4.3
BSD.
These macros syntactically operate on an arbitrary integer value.
The behavior is undefined unless that value is one stored by a
successful call to wait() or waitpid() in the location pointed to
by the stat_loc argument. An early proposal attempted to make
this clearer by specifying each argument as *stat_loc rather than
stat_val. However, that did not follow the conventions of other
specifications in this volume of POSIX.1‐2017 or traditional
usage. It also could have implied that the argument to the macro
must literally be *stat_loc; in fact, that value can be stored or
passed as an argument to other functions before being interpreted
by these macros.
The extension that affects wait() and waitpid() and is common in
historical implementations is the ptrace() function. It is called
by a child process and causes that child to stop and return a
status that appears identical to the status indicated by
WIFSTOPPED. The status of ptrace() children is traditionally
returned regardless of the WUNTRACED flag (or by the wait()
function). Most applications do not need to concern themselves
with such extensions because they have control over what
extensions they or their children use. However, applications,
such as command interpreters, that invoke arbitrary processes may
see this behavior when those arbitrary processes misuse such
extensions.
Implementations that support core file creation or other
implementation-defined actions on termination of some processes
traditionally provide a bit in the status returned by wait() to
indicate that such actions have occurred.
Allowing the wait() family of functions to discard a pending
SIGCHLD signal that is associated with a successfully waited-for
child process puts them into the sigwait() and sigwaitinfo()
category with respect to SIGCHLD.
This definition allows implementations to treat a pending SIGCHLD
signal as accepted by the process in wait(), with the same
meaning of ``accepted'' as when that word is applied to the
sigwait() family of functions.
Allowing the wait() family of functions to behave this way
permits an implementation to be able to deal precisely with
SIGCHLD signals.
In particular, an implementation that does accept (discard) the
SIGCHLD signal can make the following guarantees regardless of
the queuing depth of signals in general (the list of waitable
children can hold the SIGCHLD queue):
1. If a SIGCHLD signal handler is established via sigaction()
without the SA_RESETHAND flag, SIGCHLD signals can be
accurately counted; that is, exactly one SIGCHLD signal will
be delivered to or accepted by the process for every child
process that terminates.
2. A single wait() issued from a SIGCHLD signal handler can be
guaranteed to return immediately with status information for
a child process.
3. When SA_SIGINFO is requested, the SIGCHLD signal handler can
be guaranteed to receive a non-null pointer to a siginfo_t
structure that describes a child process for which a wait via
waitpid() or waitid() will not block or fail.
4. The system() function will not cause the SIGCHLD handler of a
process to be called as a result of the fork()/exec executed
within system() because system() will accept the SIGCHLD
signal when it performs a waitpid() for its child process.
This is a desirable behavior of system() so that it can be
used in a library without causing side-effects to the
application linked with the library.
An implementation that does not permit the wait() family of
functions to accept (discard) a pending SIGCHLD signal associated
with a successfully waited-for child, cannot make the guarantees
described above for the following reasons:
Guarantee #1
Although it might be assumed that reliable queuing of all
SIGCHLD signals generated by the system can make this
guarantee, the counter-example is the case of a process
that blocks SIGCHLD and performs an indefinite loop of
fork()/wait() operations. If the implementation supports
queued signals, then eventually the system will run out of
memory for the queue. The guarantee cannot be made because
there must be some limit to the depth of queuing.
Guarantees #2 and #3
These cannot be guaranteed unless the wait() family of
functions accepts the SIGCHLD signal. Otherwise, a
fork()/wait() executed while SIGCHLD is blocked (as in the
system() function) will result in an invocation of the
handler when SIGCHLD is unblocked, after the process has
disappeared.
Guarantee #4
Although possible to make this guarantee, system() would
have to set the SIGCHLD handler to SIG_DFL so that the
SIGCHLD signal generated by its fork() would be discarded
(the SIGCHLD default action is to be ignored), then restore
it to its previous setting. This would have the undesirable
side-effect of discarding all SIGCHLD signals pending to
the process.
