wait, waitpid, wait3, or wait364 Subroutine

Purpose

Waits for a child process to stop or terminate.

Library

Standard C Library (libc.a)

Syntax

#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;

Description

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.

Note: The effect of the wait subroutine can be modified by the setting of the SIGCHLD signal. See the sigaction subroutine for details.

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:

• If the ProcessID value is equal to a value of -1, status is requested for any child process. In this respect, the waitpid subroutine is equivalent to the wait subroutine.
• A ProcessID value that is greater than 0 specifies the process ID of a single child process for which status is requested.
• If the ProcessID parameter is equal to 0, status is requested for any child process whose process group ID is equal to that of the calling thread's process.
• If the ProcessID parameter is less than 0, status is requested for any child process whose process group ID is equal to the absolute value of the ProcessID parameter.

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.

When multiprocess debugging mode is enabled, the following new values are returned from a wait 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.

Parameters

Macros

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.

Return Values

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.

Error Codes

The wait, waitpid, wait3, and wait364 subroutines are unsuccessful if one of the following is true:

The waitpid subroutine is unsuccessful if the following is true:

The waitpid and wait3 subroutines are unsuccessful if the following is true:

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The exec subroutine, _exit, exit, or atexit subroutine, fork subroutine, getrusage subroutine, pause subroutine, ptrace subroutine, sigaction subroutine.