pid_t waitpid(pid_t pid, int *stat_loc, int options);
Description
waitpid suspends the calling process until one of its
children changes state (stops or terminates); if a child process
changed state prior to the call to waitpid, return is
immediate. pid specifies a set of child processes for
which status is requested.
If pid is equal to (pid_t)-1, status is
requested for any child process.
If pid is greater than 0, it specifies the process
ID of the child process for which status is requested.
If pid is equal to 0, status is requested for any child
process whose process group ID is equal to that of the
calling process.
If pid is less than (pid_t)-1, status is
requested for any child process whose process group ID is
equal to the absolute value of pid.
If the calling process had specified a non-zero value of
stat_loc, the status of the child process will be stored
in the location pointed to by stat_loc.
The options argument is constructed from the bitwise
inclusive OR of zero or more of the following flags,
defined in the header file <sys/wait.h>:
WCONTINUED
the status of any continued child process specified by
pid, whose status has not been reported since it continued
(from a job control stop), shall also be reported to the calling
process.
WNOHANG
waitpid will not suspend execution of the calling process
if status is not immediately available for one of the child
processes specified by pid.
WNOWAIT
keep the process whose status is returned in stat_loc in a
waitable state. The process may be waited for again with identical
results.
WUNTRACED
the status of any child processes specified by pid that
are stopped, and whose status has not yet been reported since they
stopped, shall also be reported to the calling process.
waitpid with options equal to 0 and
pid equal to (pid_t)-1 is identical to a call
to
wait(S).
The status of a child process may be interpreted using the following
macros, which are defined in <sys/wait.h>;
status is the integer value pointed to by
stat_loc:
WIFEXITED(status)
Evaluates to a non-zero value if status was returned for a
child process that terminated normally.
WEXITSTATUS(status)
If the value of WIFEXITED(status) is non-zero,
this macro evaluates to the exit code that the child process passed
to the
_exit(S)
or
exit(S)
function, or the value that the child process returned from
main( ).
WIFSIGNALED(status)
Evaluates to a non-zero value if status was returned for a
child process that terminated due to the receipt of a signal.
WTERMSIG(status)
If the value of WIFSIGNALED(status) is non-zero,
this macro evaluates to the number of the signal that caused the
termination of the child process.
WIFSTOPPED(status)
Evaluates to a non-zero value if status was returned for a child
process that is currently stopped.
WSTOPSIG(status)
If the value of WIFSTOPPED(status) is non-zero,
this macro evaluates to the number of the signal that caused the
child process to stop.
WIFCONTINUED(status)
Evaluates to a non-zero value if status was returned for a child
process that has continued from a job control stop.
WCOREDUMP(status)
If the value of WIFSIGNALED(status) is non-zero,
this macro evaluates to a non-zero value if a core image of the
terminated child process was created.
The way in which these macros evaluate depends on the flags
specified by the call to waitpid:
WUNTRACED specified?
WCONTINUED specified?
Result
yes
yes
Exactly one of the following evaluates to non-zero:
WIFEXITED(*stat_loc)
WIFSIGNALED(*stat_loc)
WIFSTOPPED(*stat_loc)
WIFCONTINUED(*stat_loc)
yes
no
Exactly one of the following evaluates to non-zero:
WIFEXITED(*stat_loc)
WIFSIGNALED(*stat_loc)
WIFSTOPPED(*stat_loc)
no
yes
Exactly one of the following evaluates to non-zero:
WIFEXITED(*stat_loc)
WIFSIGNALED(*stat_loc)
WIFCONTINUED(*stat_loc)
no
no
Exactly one of the following evaluates to non-zero:
WIFEXITED(*stat_loc)
WIFSIGNALED(*stat_loc)
This call is equivalent to a call to the wait function.
Return values
If waitpid returns because the status of a child process
is available, it returns the process ID of the child
process for which status is reported. If waitpid was
invoked with WNOHANG set in options, it has at
least one child process specified by pid for which status
is not available, and status is not available for any process
specified by pid, waitpid returns 0. Otherwise,
waitpid returns (pid_t)-1 and sets
errno to identify the error. If waitpid returns
due to the delivery of a signal to the calling process, -1 is
returned and errno is set to EINTR.
Diagnostics
In the following conditions, waitpid fails and sets
errno to indicate the error:
[EINTR]
waitpid was interrupted due to the receipt of a signal
sent by the calling process.
[EINVAL]
An invalid value was specified for options.
[ECHILD]
The process or process group specified by pid does not
exist or is not a child of the calling process or can never be in
the states specified by options.