wait(S) 6 January 1993 wait(S) Name wait, waitpid - wait for child process to stop or terminate Syntax cc . . . -lc #include <sys/types.h> #include <sys/wait.h> pid_t wait (stat_loc) int *stat_loc; pid_t waitpid (pid, stat_loc, options) pid_t pid; int *stat_loc, options; Description The wait and waitpid system calls suspend the calling process until one of the immediate children terminates, or until a process that is being traced stops. The wait system call returns prematurely if a signal is received. If a child process stops or terminates prior to the call on wait; return is immediate. If status information is available for two or more child processes, the order in which their status is reported is unspecified. The waitpid function behaves identically to the wait function, if the pid argument has a value of -1 and the options argument has a value of zero. Otherwise, its behavior is modified by the values of the pid and options arguments. The pid argument specifies a set of child processes for which status is requested. waitpid only returns the status of a child process from this set. 1. If pid is equal to -1, status is requested for any child process. In this respect, waitpid is then equivalent to wait. 2. If pid is greater than zero, it specifies the process ID of a single child process for which status is requested. 3. 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. 4. 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 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 does not suspend execution of the calling process if status is not immediately available for one of the child processes specified by pid. WUNTRACED If the implementation supports job control, the status of any child processes specified by pid that are stopped, and whose status has not yet been reported since they stopped, are also reported to the requesting process. If wait or waitpid return because the status of a child process is avail- able, these functions return a value equal to the process ID of the child process. In this case, if the value of the argument statloc is not NULL, informa- tion is stored in the location pointed to by statloc. If and only if the status returned is from a terminated child process that returned a value of zero from main or passed a value of zero as the status argument to exit or exit, the value stored at the location pointed to by statloc is zero. Regardless of its value, this information may be interpreted using the following macros, which are defined in <sys/wait.h> and evalu- ate to integral expressions; the statval argument is the integer value pointed to by statloc. WIFEXITED(statval) Evaluates to a non-zero value if status was returned for a child process that terminated nor- mally. WEXITSTATUS(statval) If the value of WIFEXITED(statval) is non-zero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to exit or exit, or the value the child process returned from main. WIFSIGNALED(statval) 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 (see signal(S)). WTERMSIG(statval) If the value of WIFSIGNALED(statval) is non- zero, this macro evaluates to the number of the signal that caused the termination of the child process. WIFSTOPPED(statval) Evaluates to a non-zero value if status was returned for a child process that is currently stopped. WSTOPSIG(statval) If the value of WIFSTOPPED(statval) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop. If the information stored at the location pointed to by statloc was stored there by a call to the waitpid function that specified the WUN- TRACED flag, exactly one of the macros WIFEXITED(statloc), WIFSIGNALED(statloc), and WIFSTOPPED(statloc) evaluates to a non-zero value. If the information stored at the location pointed to by statloc was stored there by a call to the waitpid function that did not specify the WUNTRACED flag or by a call to the wait function, exactly one of the macros WIFEXITED(*statloc) and WIFSIGNALED(*statloc) evaluates to a non-zero number. If statloc is non-zero, 16 bits of information called status are stored in the low order 16 bits of the location pointed to by statloc. status can be used to differentiate between stopped and terminated child pro- cesses and if the child process terminated, status identifies the cause of termination and passes useful information to the parent. This is accomplished in the following manner: If the child process stopped, the high order 8 bits of status contain the number of the signal that caused the process to stop, and the low order 8 bits are set equal to 0177. If the child process terminated due to an exit call, the low order 8 bits of status are zero, and the high order 8 bits contain the low order 8 bits of the argument that the child process passed to exit (see exit(S)). If the child process terminated due to a signal, the high order 8 bits of status are zero, and the low order 8 bits contain the number of the signal that caused the termination. In addition, if the low order seventh bit (that is, bit 200) is set, a ``core image'' has been pro- duced (see signal(S)). If a parent process terminates without waiting for its child processes to terminate, the parent process ID of each child process is set to 1. This means the initialization process inherits the child processes. Return value If the wait or waitpid functions return because the status of a child process is available, these functions return a value equal to the process ID of the child process for which status is reported. If the wait or waitpid functions return due to the delivery of a signal to the calling process, a value of -1 is returned and errno is set to [EINTR]. If the waitpid function 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, a value of zero is returned. Otherwise, a value of -1 is returned, and errno is set to indicate the error. The wait function fails and returns -1 if one or more of the following is true: [ECHILD] The calling process has no existing unwaited-for child pro- cesses. [EINTR] The function was interrrupted by a signal. The value of the location pointed to by statloc is undefined. If any of the following conditions occur, the waitpid function returns -1 and sets errno to the corresponding value: [ECHILD] The process or process group defined by pid does not exist or is not a child of the calling process. [EINTR] The function was interrrupted by a signal. The value of the location pointed to by statloc is undefined. [EINVAL] The value of the options argument is not valid. Warning The wait system call fails and its actions are undefined if statloc points to an invalid address. See also exec(S), exit(S), fork(S), pause(S), ptrace(S), signal(S), times(S) Standards conformance wait is conformant with: AT&T SVID Issue 2; X/Open Portability Guide, Issue 3, 1989; IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); and NIST FIPS 151-1. waitpid is conformant with: IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); X/Open Portability Guide, Issue 3, 1989; and NIST FIPS 151-1.