Waits for a child process to stop or terminate.
Standard C Library (libc.a)
#include <sys/wait.h>
pid_t wait ( StatusLocation)
int *StatusLocation;
pid_t wait ((void *) 0)
#include <sys/wait.h>pid_t waitpid ( ProcessID,
StatusLocation, Options)
int *StatusLocation;
pid_t ProcessID;
int Options;
#include <sys/time.h>
#include <sys/resource.h>
#include <sys/wait.h>pid_t wait3 (StatusLocation, Options, ResourceUsage)
int *StatusLocation;
int Options;
struct rusage *ResourceUsage;pid_t wait364 (StatusLocation, Options, ResourceUsage)
int *StatusLocation;
int Options;
struct rusage64 *ResourceUsage;The wait subroutine suspends the calling thread until the process receives a signal that is not blocked or ignored, or until any one of the calling process' child processes stops or terminates. The wait subroutine returns without waiting if the child process that has not been waited for has already stopped or terminated prior to the call. On a successful exit, the pid of the terminated process is returned by the wait subroutine.
The waitpid subroutine includes a ProcessID parameter that allows the calling thread to gather status from a specific set of child processes, according to the following rules:
The waitpid, wait3, and wait364 subroutine variants provide an Options parameter that can modify the behavior of the subroutine. Two values are defined, WNOHANG and WUNTRACED, which can be combined by specifying their bitwise-inclusive OR. The WNOHANG option prevents the calling thread from being suspended even if there are child processes to wait for. In this case, a value of 0 is returned indicating there are no child processes that have stopped or terminated. If the WUNTRACED option is set, the call should also return information when children of the current process are stopped because they received a SIGTTIN, SIGTTOU, SIGSSTP, or SIGTSTOP signal.
The wait364 subroutine can be called to make 64-bit rusage counters explicitly available in a 32-bit environment.
In AIX® 5.1 and later, 64-bit quantities are also available to 64-bit applications through the wait3() interface in the ru_utime and ru_stime fields of struct rusage.
When a 32-bit process is being debugged with ptrace, the status location is set to W_SLWTED if the process calls load, unload, or loadbind. When a 64-bit process is being debugged with ptrace, the status location is set to W_SLWTED if the process calls load or unload.
If multiprocessing debugging mode is enabled, the status location is set to W_SEWTED if a process is stopped during an exec subroutine and to W_SFWTED if the process is stopped during a fork subroutine.
If more than one thread is suspended awaiting termination of the same child process, exactly one thread returns the process status at the time of the child process termination.
If the WCONTINUED option is set, the call should return information when the children of the current process have been continued from a job control stop but whose status has not yet been reported.
| Item | Description |
|---|---|
| StatusLocation | Points to integer variable that contains (or will contain) the child process termination status, as defined in the sys/wait.h file. |
| ProcessID | Specifies the child process. |
| Options | Modifies behavior of subroutine. |
| ResourceUsage | Specifies the location of a structure to be filled in with resource utilization information for terminated children. |
The value pointed to by StatusLocation when wait, waitpid, or wait3 subroutines are returned, can be used as the ReturnedValue parameter for the following macros defined in the <sys/wait.h> file to get more information about the process and its child process.
WIFCONTINUED(ReturnedValue)
pid_t ReturnedValue;Returns a nonzero value if status returned for a child process that has continued from a job control stop.
WIFSTOPPED(ReturnedValue)
int ReturnedValue;Returns a nonzero value if status returned for a stopped child.
int
WSTOPSIG(ReturnedValue)
int ReturnedValue;Returns the number of the signal that caused the child to stop.
WIFEXITED(ReturnedValue)
int ReturnedValue;Returns a nonzero value if status returned for normal termination.
int
WEXITSTATUS(ReturnedValue)
int ReturnedValue;Returns the low-order 8 bits of the child exit status.
WIFSIGNALED(ReturnedValue)
int ReturnedValue;Returns a nonzero value if status returned for abnormal termination.
int
WTERMSIG(ReturnedValue)
int ReturnedValue;Returns the number of the signal that caused the child to terminate.
If the wait subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error. In addition, the waitpid, wait3, and wait364 subroutines return a value of 0 if there are no stopped or exited child processes, and the WNOHANG option was specified. The wait subroutine returns a 0 if there are no stopped or exited child processes, also.
The wait, waitpid, wait3, and wait364 subroutines are unsuccessful if one of the following is true:
| Item | Description |
|---|---|
| ECHILD | The calling thread's process has no existing unwaited-for child processes. |
| EINTR | This subroutine was terminated by receipt of a signal. |
| EFAULT | The StatusLocation or ResourceUsage parameter points to a location outside of the address space of the process. |
The waitpid subroutine is unsuccessful if the following is true:
| Item | Description |
|---|---|
| ECHILD | The process or process group ID specified by the ProcessID parameter does not exist or is not a child process of the calling process. |
The waitpid and wait3 subroutines are unsuccessful if the following is true:
| Item | Description |
|---|---|
| EINVAL | The value of the Options parameter is not valid. |