./_Man_NeXT_html/html2/wait.2p.html

Manual page for WAIT(2P)

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: