wait, waitpid, wait3, wait364, and wait4 Subroutine

Edit online

Purpose

Waits for a child process to stop or end.

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;
pid_t wait4 (ProcessID,(StatusLocation, Options,ResourceUsage)
pid_t ProcessID;
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 ends. The wait subroutine returns without waiting if the child process that is being waited for stops or terminates before the call. On a successful exit, the pid of the terminated process is returned by the wait subroutine.

Note: The effect of the wait subroutine can be modified by the setting of the SIGCHLD signal. When SIGCHLD is blocked and wait() returns because the status of a child process is available and there are no other child processes for which status is available, then any pending SIGCHLD signal is cleared. See the sigaction (sigaction, sigvec, or signal Subroutine) 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, wait364, wait4 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 stop or terminate. If the WUNTRACED option is set, the call also returns information when children of the current process stop because they receive 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.

The wait4() subroutine is similar to the wait3() subroutine except that we can specify the process ID of the child. The wait3() subroutine waits for any child process but the wait4() subroutine can wait for a specific child process.

64-bit quantities are also available to 64-bit applications through the wait3() and wait4() 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 returns information when the children of the current process continue from a job control stop but whose status is not reported.

Parameters

Item Description
StatusLocation Points to integer variable that contains 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 completed with resource utilization information for terminated children.

Macros

The value pointed to by StatusLocation when wait, waitpid, wait3, or wait4() subroutines are returned, can be used as the ReturnedValue parameter for the following macros that are 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 continues 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, wait364, and wait4 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, wait364, and wait4 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 and wait4 subroutines are 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, wait3, and wait4 subroutines are unsuccessful if the following is true:

Item Description
EINVAL The value of the Options parameter is not valid.