OSF

NAME

wait, waitpid, wait3, wait4 − Waits for a child process to stop or terminate

SYNOPSIS

#include <sys/types.h> #include <sys/wait.h> pid_t wait (
int ∗status_location ); pid_t waitpid (
pid_t process_id,
int ∗status_location,
int options ); #include <sys/resource.h> pid_t wait3 (
union wait ∗status_location,
int options,
struct rusage ∗resource_usage ); pid_t wait4 (
pid_t process_id
union wait ∗status_location,
int options,
struct rusage ∗resource_usage );

PARAMETERS

status_location
Points to a location that is filled in with the child process termination status, as defined in the sys/wait.h header file. 

process_idSpecifies the child process. 

optionsModifies the behavior of the function. 

resource_usage
Specifies the location of a structure to be filled in with resource utilization information for terminated child processes.

DESCRIPTION

The wait() function suspends the calling process until it receives a signal that is to be caught, or until any one of the calling process’ child processes stops or terminates.  The wait() function returns without waiting if a child process that has not been waited for has already stopped or terminated prior to the call. 

The effect of the wait() function can be modified by the setting of the SIGCHLD signal.  (See the sigaction() function for details.) 

The waitpid() function behaves identically to the wait() function if the process_id parameter has a value of -1 and the options parameter has a value of 0 (zero).  Otherwise, its behavior is modified by the values of the process_id and options parameters. 

The wait(), waitpid(), wait3(), and wait4(), functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended. 

The process_id parameter allows the calling process to gather status from a specific set of child processes, according to the following rules:

       •If the process_id parameter is equal to -1, status is requested for any child process.  In this respect, the waitpid() function is equivalent to the wait() function. 

       •If the process_id parameter is greater than 0 (zero), it specifies the process ID of a single child process for which status is requested. 

       •If the process_id parameter is equal to 0 (zero), status is requested for any child process whose process group ID is equal to that of the calling process. 

       •If the process_id parameter is less than -1, status is requested for any child process whose process group ID is equal to the absolute value of the process_id parameter. 

The waitpid() and wait4() functions will only return the status of a child process from this set. 

The options parameter to both the waitpid() wait3() and wait4() functions modifies the behavior of the function.  Two values are defined, WNOHANG and WUNTRACED, which can be combined by specifying their bitwise-inclusive OR.  The WNOHANG option prevents the calling process from being suspended even if there are child processes to wait for.  In this case, 0 (zero) is returned indicating that there are no child processes that have stopped or terminated.  If the WUNTRACED option is set, the call also returns information when child processes of the current process are stopped because they received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal. 

If the wait(), waitpid(), wait3() or wait4() function returns because the status of a child process is available, they return the process ID of the child process.  In this case, if the status_location parameter is not null, information will be stored in the location pointed to by status_location.  The value stored at the location pointed to by status_location is 0 (zero) if and only if the status returned is from a terminated child process that returned 0 (zero) from the main() routine, or passed 0 (zero) as the status parameter to the _exit() or exit() function.  Regardless of its value, this information can be interpreted using the following macros, which are defined in the sys/wait.h header file and evaluate to integral expressions; the status_value parameter is the integer value pointed to by status_location. 

WIFEXITED(status_value)
Evaluates to a nonzero value if status was returned for a child process that terminated normally.

WEXITSTATUS(status_value)
If the value of WIFEXITED(status_value) is nonzero, this macro evaluates to the low-order 8 bits of the status parameter that the child process passed to the _exit() or exit() functions, or the value the child process returned from the main() routine. 

WIFSIGNALED(status_value)
Evaluates to nonzero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught.

WTERMSIG(status_value)
If the value of WIFSIGNALED(status_value) is nonzero, this macro evaluates to the number of the signal that caused the termination of the child process. 

WIFSTOPPED(status_value)
Evaluates to a nonzero value if status was returned for a child process that is currently stopped.

WSTOPSIG(status_value)
If the value of WIFSTOPPED(status_value) is nonzero, 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 the status_location parameter was stored there by a call to the waitpid(), wait3(), or wait4() function that specified the WUNTRACED flag, exactly one of the WIFEXITED(∗status_location), WIFSIGNALED(∗status_location), and WIFSTOPPED(∗status_location) macros will evaluate to a nonzero value.  If the information stored at the location pointed to by the status_location function was stored there by a call to waitpid(), wait3(),or wait4() that did not specify the WUNTRACED flag or by a call to the wait() function, exactly one of the WIFEXITED(∗status_location) and WIFSIGNALED(∗status_location) macros will evaluate to a nonzero value. 

The wait3() function is provided for compatibility with BSD systems.  A program that calls wait3() must be compiled with the _BSD switch defined.  In this case, the parameter to the macros described above should be the w_status member of the union pointed to by status_location.  The wait3() and wait4() functions also provide a resource_usage parameter that points to a location in which resource usage information for the child process is stored, as defined in the sys/resource.h function. 

The wait4() function is similar to wait3(), but instead of waiting on all children, it waits only for a specific child as specified by process_id. 

If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes will be assigned a parent process ID equal to the process ID of init. 

NOTES

If a program that calls the wait() function is compiled with the _BSD switch defined and linked with the libbsd compatibility library, the status_location parameter is of type union wait ∗ rather than int ∗, as described above for the wait3() function. 

AES Support Level:
Full use (wait(), waitpid())

ERRORS

If the wait(), waitpid(), wait3(), or wait4() function fails, errno may be set to one of the following values:

[ECHILD]The calling process has no existing unwaited-for child processes. 

[EINTR]The function was terminated by receipt of a signal. 

[EFAULT]The status_location or resource_usage parameter points to a location outside of the address space of the process. 

The waitpid() function fails if one or both of the following are true:

[ECHILD]The process or process group ID specified by the process_id parameter does not exist or is not a child process of the calling process. 

The waitpid(), wait3(), or wait4() functions fail if the following is true:

[EINVAL]The value of the options parameter is not valid. 

RETURN VALUES

If the wait(), waitpid(), wait3(), or wait4() function returns because the status of a child process is available, the process ID of the child is returned to the calling process.  If they return because a signal was caught by the calling process, -1 is returned and errno is set to [EINTR]. 

If the WNOHANG option was specified, and there are no stopped or exited child processes, the waitpid(), wait3(), and wait4() functions return a value of 0 (zero).  Otherwise, -1 is returned and errno is set to indicate the error. 

RELATED INFORMATION

Functions: exec(2), exit(2), fork(2), pause(3), ptrace(2), getrusage(2), sigaction(2)