WAIT(2P)WAIT(2P)NAME
wait, waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG,
WIFSTOPPED, WSTOPSIG - (POSIX version) wait for process to terminate or
stop
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
int wait(int *stat_loc);
int waitpid(pid_t pid, int *stat_loc, int options);
WIFEXITED(int stat_val)
WEXITSTATUS(int stat_val)
WIFSIGNALED(int stat_val)
WTERMSIG(int stat_val)
WIFSTOPPED(int stat_val)
WSTOPSIG(int stat_val)
DESCRIPTION
The information in this specification applies only to POSIX
applications.
This is the POSIX specification for stat. For the BSD specification,
see stat(2).
The wait function delays its caller until a signal is received or one
of its child processes terminates or stops due to tracing. If any
child has died or stopped due to tracing and this has not been reported
using wait, return is immediate, returning the process ID and exit
status of one of those children. If that child had died, it is
discarded. If there are no children, return is immediate with the
value -1 returned. If there are only running or stopped but reported
children, the calling process is blocked.
If stat_loc is not a NULL pointer, then on return from a successful
wait call the status of the child process whose process ID is the
return value of wait is stored in the int pointed to by stat_loc. The
stat_loc argument to wait) and waitpid() (stat_val is the value pointed
to by stat_loc) indicates the cause of termination and other
information about the terminated process in the following manner:
- If the low-order 8 bits of stat_val are equal to 0177, the
child process has stopped; see ptrace(2) and sigvec(2).
- If the low-order 8 bits of stat_val are non-zero and are
not equal to 0177, the child process terminated due to a
signal; the low-order 7 bits of stat_val contain the number
of the signal that terminated the process. In addition, if
the low-order seventh bit of stat_val (that is, bit 0200)
is set, a ``core image'' of the process was produced; see
sigvec(2).
- Otherwise, the child process terminated due to an exit(2)
call; the 8 bits higher up from the low-order 8 bits of
stat_val contain the low-order 8 bits of the argument that
the child process passed to exit(2).
The options argument is constructed from the bitwise inclusive OR of
zero or more of the following flags, defined in the header
<sys/wait.h>.
WNOHANG The waitpid() function will not suspend
execution of the calling process if status is
not immediately available for one of the child
processes specified by pid.
WUNTRACED The status of any child processes specified by
pid that are stopped and whose status has not
yet been reported since they stopped, will
also be reported to the requesting process.
WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, and
WSTOPSIG, are macros that take an argument stat_val as returned by wait
or waitpid().
WIFEXITED(stat_val) evaluates to a nonzero value if status was
returned for a child process that terminated
normally.
WEXITSTATUS(stat_val) If the value of WIFEXITED(stat_val) is
nonzero, this macro evaluates to the low-order
8 bits of the status argument that the child
process passed to _exit(2) or exit(2), or the
value the child process returned from main().
WIFSIGNALED(stat_val) evaluates to true when the process was
terminated with a signal.
WTERMSIG(stat_val) If the value of WIFSIGNALED(stat_val) is
nonzero, this macro evaluates to the number of
the signal that caused the termination of the
child process.
WIFSTOPPED(stat_val) evaluates to true (1) when the process for
which the wait or waitpid() call was made is
stopped, or to false (0) otherwise.
WSTOPSIG(stat_val) If the value of WIFSTOPPED(stat_val) is
nonzero, this macro evaluates to the number of
the signal that caused the child process to
stop.
NOTES
If a parent process terminates without waiting on its children, the
initialization process (process ID = 1) inherits the children.
RETURN VALUE
If wait or waitpid() returns due to a stopped or terminated child
process, the process ID of the child is returned to the calling
process. Otherwise, a value of -1 is returned and errno is set to
indicate the error.
waitpid() returns 0 if WNOHANG is specified and there are no stopped or
exited children, and return the process ID of the child process if it
returns due to a stopped or terminated child process. Otherwise, it
returns a value of -1 and set errno to indicate the error.
ERRORS
If any of the following conditions occur, the wait and waitpid()
functions will return -1 and set errno to the corresponding value:
[ECHILD] The calling process has no existing unwaited-for child
processes.
[EFAULT] The stat_loc argument points to an illegal address.
[EINTR] The function was interrupted by a signal. The value of
the location pointed to by stat_loc is undefined.
Additionally, waitpid() will fail if:
[EINVAL] The value of the options argument is not valid.
SEE ALSOexit(2), getrusage(2), sigvec(2), siginterrupt(3), signal(3), wait(2)
August 1, 1992 WAIT(2P)
