wait3

Waits for a child process to stop or terminate.

Format

#include  <wait.h>

pid_t wait3  (int *status_location, int options,
             struct rusage *resource_usage);

Arguments

status_location: A pointer to a location that contains the termination status of the child process as defined in the <wait.h> header file.
options: Flags that modify the behavior of the function. These flags are defined in the Description section.
resource_usage: The location of a structure that contains the resource utilization information for terminated child processes.

Description

This function suspends the calling process until the request is completed, and redefines it so that only the calling thread is suspended.

The options argument modifies the behavior of the function. You can combine the flags for the options argument by specifying their bitwise inclusive OR. The flags are:

WNOWAIT Specifies that the process whose status is returned in status_location is kept in a waitable state. You can wait for the process again with the same results.

WNOHANG Prevents the suspension of the calling process. If there are child processes that stopped or terminated, one is chosen and the waitpid function returns its process ID, as when you do not specify the WNOHANG flag. If there are no terminated processes (that is, if waitpid suspends the calling process without the WNOHANG flag), 0 (zero) is returned. Because you can never wait for process 0, there is no confusion arising from this return.

WUNTRACED Specifies that the call return additional information when the child processes of the current process stop because the child process received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal.

If the wait3 function returns because the status of a child process is available, the process ID of the child process is returned. Information is stored in the location pointed to by status_ location, if this pointer is not null.

The value stored in the location pointed to by status_ location is 0 (zero) only if the status is returned from a terminated child process that did one of the following:

Returned 0 from the main function.
Passed 0 as the status argument to the _exit or exit function.

Regardless of the status_location value, you can define this information using the macros defined in the <wait.h> header file, which evaluate to integral expressions. In the following macro descriptions, the status_value argument is equal to the integer value pointed to by the status_location argument:

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 argument that the child process passed to the _exit or exit function, or to the value the child process returned from the main function.

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.

WIFCONTINUED(status_value) Evaluates to a nonzero value if status was returned for a child process that has continued.

If the information stored at the location pointed to by status_ location was stored there by a call to wait3 that specified the WUNTRACED flag, one of the following macros evaluates to a nonzero value:

WIFEXITED(*status_value)
WIFSIGNALED(*status_value)
WIFSTOPPED(*status_value)
WIFCONTINUED(*status_value)

If the information stored in the location pointed to by status_ location resulted from a call to wait3 without the WUNTRACED flag specified, one of the following macros evaluates to a nonzero value:

WIFEXITED(*status_value)
WIFSIGNALED(*status_value)

The wait3 function provides compatibility with BSD systems. The resource_usage argument points to a location that contains resource usage information for the child processes as defined in the <resource.h> header file.

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

See also exit, -exit, and init in this section.

Return Values

0 Indicates success. There are no stopped or exited child processes, the WNOHANG option is specified.

x The process_id of the child process. Status of a child process is available.

-1 Indicates an error; errno is set to one of the following values:

ECHILD - There are no child processes to wait for.
EINTR - Terminated by receipt of a signal caught by the calling process.
EFAULT - The status_location or resource_ usage argument points to a location outside of the address space of the process.
EINVAL- The value of the options argument is not valid.

Previous Page | Next Page | Table of Contents | Index

WNOWAIT	Specifies that the process whose status is returned in status_location is kept in a waitable state. You can wait for the process again with the same results.
WNOHANG	Prevents the suspension of the calling process. If there are child processes that stopped or terminated, one is chosen and the waitpid function returns its process ID, as when you do not specify the WNOHANG flag. If there are no terminated processes (that is, if waitpid suspends the calling process without the WNOHANG flag), 0 (zero) is returned. Because you can never wait for process 0, there is no confusion arising from this return.
WUNTRACED	Specifies that the call return additional information when the child processes of the current process stop because the child process received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal.

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 argument that the child process passed to the _exit or exit function, or to the value the child process returned from the main function.
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.
WIFCONTINUED(status_value)	Evaluates to a nonzero value if status was returned for a child process that has continued.

0	Indicates success. There are no stopped or exited child processes, the WNOHANG option is specified.
x	The process_id of the child process. Status of a child process is available.
-1	Indicates an error; errno is set to one of the following values: ECHILD - There are no child processes to wait for. EINTR - Terminated by receipt of a signal caught by the calling process. EFAULT - The status_location or resource_ usage argument points to a location outside of the address space of the process. EINVAL- The value of the options argument is not valid.