wait(2)
NAME
wait, wait3, waitpid − wait for process to terminate
SYNTAX
#include <sys/wait.h>
pid = wait(status)
int pid;
union wait *status;
pid = wait((union wait*)0)
int pid;
#include <sys/time.h>
#include <sys/resource.h>
pid = wait3(status, options, rusage)
int pid;
union wait *status;
int options;
struct rusage *rusage;
#include <sys/types.h>
pid_t
pid = waitpid(pid, status, options)
pid_t pid;
union wait *status;
int options;
DESCRIPTION
The wait system call causes its caller to delay either until a signal is received or one of its child processes terminates. If a child process has died since the last wait, return is immediate, returning the process id and exit status of one of the terminated child processes. If a child process does not exist, return is immediate with the value −1 returned.
On return from a successful wait call, if status is nonzero, the high byte of status contains the low byte of the argument to exit supplied by the child process; the low byte of status contains the termination status of the process. A more precise definition of the status word is given in <sys/wait.h>.
The wait3 system call provides an alternate interface for programs which must not block when collecting the status of child processes. The status parameter is defined as above. The options parameter is used to indicate that the call should not block if there are no processes that wish to report status (WNOHANG), and/or that only children of the current process which are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should have their status reported (WUNTRACED). If rusage is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is not available for stopped processes).
When the WNOHANG option is specified and no processes wish to report status, wait3 returns a pid of 0. The WNOHANG and WUNTRACED options may be combined by or’ing the two values.
See sigvec() for a list of termination statuses (signals). A 0 status indicates normal termination. A special status (0177) is returned for a process stopped by the process tracing mechanism, ptrace(.). If the 0200 bit of the termination status is set, a core image of the process was produced by the system.
If the parent process terminates without waiting on its children, the initialization process (process ID = 1) inherits the children.
The waitpid system call provides an interface for programs which wish to wait for a specific child process or child processes from specific process groups. The waitpid system call behaves as follows:
•If pid is equal to −1, status is requested for any child process.
•If pid is greater than zero, it specifies the process ID of a single child process for which status is requested.
•If pid is equal to zero, status is requested for any child process whose process group ID is equal to that of the calling process.
•If pid is less than −1, status is requested for any child process whose process group ID is equal to the absolute value of pid.
The status and options arguments are defined as above. The waitpid system call behaves identically to the wait system call if the pid argument has a value of −1 and the options argument has a value of 0.
wait, wait3, and waitpid system calls are automatically restarted when a process receives a signal while awaiting termination of a child process unless the SV_INTERRUPT bit has been set for that signal. See the sigvec(.).
The following macros, defined in <sys/wait.h> may be used to interpret the information contained in the status parameter returned by the wait functions; the stat_val argument is the value pointed to by the status argument.
WIFEXITED(stat_val)
Evaluates to a non-zero value if status was returned for a child process that terminated normally.
WEXITSTATUS(stat_val)
If the value of WIFEXITED(stat_val) is non-zero, this macro evaluates ro the low-order 8 bits of the status argument that the child process passes to _exit or exit, or the value the child process returned from main.
WIFSIGNALED(stat_val)
Evaluates to a non-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught.
WTERMSIG(stat_val)
If the value of WIFSIGNALED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.
WIFSTOPPED(stat_val)
Evaluates to a non-zero value if status was returned for a child process that is currently stopped.
WSTOPSIG(stat_val)
If the value of WIFSTOPPED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop.
RETURN VALUE
If wait, wait3, 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.
The wait3, and waitpid system calls return −1 if there are no children not previously waited for; 0 is returned if WNOHANG is specified and there are no stopped or exited children.
ENVIRONMENT
SYSTEM_FIVE
When your program is complied using the System V environment, when the SIGCLD signal is being ignored, wait continues until all children terminate. SIGCLD is the same as SIGCHLD.
Also, when using the System V environment, status is of type int *.
POSIX
When using the POSIX environment, status is of type int *.
In addition, the SV_INTERRUPT flag is always set in POSIX mode causing the above system calls to always fail if interrupted by a signal.
DIAGNOSTICS
The wait, wait3, or waitpid system calls fails and return is immediate if one or more of the following are true:
[ECHILD] The calling process has no existing unwaited-for child processes.
[ECHILD] The process or process group specified by pid does not exist or is not a child of the calling process.
[EINTR] The function was interrupted by a signal. The value of the location pointed to by status is undefined.
[EINVAL] The value of the options argument is not valid.
[EFAULT] The status or rusage arguments point to an illegal address.
SEE ALSO
System Calls