NAME

wait, waitpid, wait3 − wait for child or traced process to stop or terminate

SYNOPSIS

#include <sys/wait.h>

pid_t wait(int *stat_loc);

pid_t waitpid(pid_t pid, int *stat_loc, int options);

pid_t wait3(int *stat_loc, int options, int *reserved);

DESCRIPTION

wait() suspends the calling process until one of the immediate children terminates or until a process being traced stops because that traced process has hit a break point.  A process being traced can be either a child or a process attached by the ptrace() request PT_ATTACH (see ptrace(2)). The wait() system call returns prematurely if a signal is received.  If a child or traced process stops or terminates prior to the call on wait, return is immediate. 

If stat_loc is not a null pointer, status information is stored in the location pointed to by stat_loc. The status can be used to differentiate between stopped and terminated processes. If the process terminates, the status identifies the cause of termination and passes useful information to the calling process. This is accomplished using the following macros defined in <sys/wait.h>, with the status value stored at ∗stat_loc as an argument:

WIFEXITED(stat_val) If the process terminated because of an exit() or _exit() system call, this macro evaluates to a non-zero value. 

WEXITSTATUS(stat_val) If the value of WIFEXITED(stat_val) is non-zero, this macro evaluates to the low-order 8 bits of the argument that the process passed to exit() or _exit() (see exit(2)).

WIFSIGNALED(stat_val) If the process terminated due to the default action of a signal (see signal(5)), this macro evaluates to a non-zero value.

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. 

WCOREDUMP(stat_val) If the value of WIFSIGNALED(stat_val) is non-zero, this macro evaluates to a non-zero value if a “core image” was produced (see signal(5)).

WIFSTOPPED(stat_val) If the process is stopped, this macro evaluates to a non-zero value. 

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 process to stop. 

As a single special case, the value stored in ∗stat_loc is zero if and only if status is being returned from a terminated process that called exit() or _exit() with a value of zero. 

If the information stored at the location pointed to by stat_loc was stored there by a call to one of the wait() functions, exactly one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), or WIFSTOPPED(*stat_loc) evaluates to a non-zero value. 

The waitpid() function behaves identically to wait() if pid has a value of −1 and options has a value of zero.  Otherwise its behavior is modified by the values of the pid and options arguments. 

The pid argument specifies the set of processes for which status is requested.  waitpid returns only the status of a child process from this set. 

• If pid is equal to −1, status is requested for any child process or attached process.  In this respect, waitpid() is then equivalent to wait(). 

• If pid is greater than zero, it specifies the process ID of a single child or attached process for which status is requested. 

• If pid is equal to zero, status is requested for any child or attached 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 or attached process whose process group ID is equal to the absolute value of pid.

The options argument is constructed from the bit-wise inclusive OR of zero or more of the following flags:

WNOHANG If this flag is set, waitpid() or wait3() is prevented from suspending the calling process.  A value of zero is returned indicating that no child or traced processes have stopped or died. 

WUNTRACED If and only if this flag is set, waitpid() or wait3() returns information on child or attached processes that are stopped but not traced (with ptrace(2)) because they received a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal, and whose status has not yet been reported.  Regardless of this flag, status is returned for child or attached processes that have terminated or are stopped and traced and whose status has not yet been reported. 

Calling wait3() is equivalent to calling waitpid() with the value of pid equal to zero.  The third parameter to wait3() is currently unused and must always be a null pointer. 

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. 

Notes

Earlier HP-UX versions documented the bit encodings of the status returned by wait() rather than the macros WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, and WSTOPSIG.  Applications using those bit encodings will continue to work correctly.  However, new applications should use the macros for maximum portability. 

In earlier HP-UX versions, the macros WIFSTOPPED, WIFSIGNALED, and WIFEXITED have the same definitions as the correspondingly named macros in the BSD 4.3 and earlier systems.  Existing applications that depend on these definitions will continue to work correctly.  However, if the application is recompiled, the feature test macro _BSD must be turned on for the compilation so that the old definitions of these macros are obtained.  New definitions of these macros are in effect by default.  The only difference between the old and new definitions is the type of the argument.  Type union wait is used in the BSD definitions while type int is used in the default definitions. 

ERRORS

wait() fails if one or more of the following is true:

[ECHILD] The calling process to wait() or wait3() has no existing child or traced processes, or the calling process to waitpid() has no existing unwaited-for child or traced processes that match the pid argument. 

[ECHILD] For waitpid(), the process or process group specified by pid does not exist or is not a child of the calling process. 

[EFAULT] stat_loc points to an illegal address.  The reliable detection of this error is implementation dependent. 

[EINVAL] The options argument to waitpid() or wait3() is invalid. 

[EINVAL] wait3() was passed a non-null pointer value for its third argument. 

[EINTR] The function was interrupted by a signal.  The value of the location pointed to by stat_loc is undefined. 

RETURN VALUE

If wait() returns due to the receipt of a signal, a value of −1 is returned to the calling process and errno is set to EINTR.  If wait() returns due to a stopped or terminated child or traced process, the process ID of that process is returned to the calling process.  If waitpid() or wait3() is called, the WNOHANG option is used, and there are no stopped or terminated child or traced processes (as specified by pid in the case of waitpid()), a value of zero is returned. Otherwise, a value of −1 is returned and errno is set to indicate the error. 

WARNINGS

The behavior of wait(), waitpid(), and wait3() is affected by setting the SIGCLD signal to SIG_IGN.  See WARNINGS section of signal(5). Signal handlers that cause system calls to be restarted can affect the EINTR condition described above (see sigaction(2), sigvector(2), and bsdproc(2)).

AUTHOR

wait(), waitpid(), and wait3() were developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO

Exit conditions ($?) in sh(1), exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(5). 

STANDARDS CONFORMANCE

wait(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

waitpid(): AES, XPG3, XPG4, FIPS 151-2, POSIX.1

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992