waitpid()

suspend the calling process

Synopsis:

#include <sys/types.h>
#include <sys/wait.h>
pid_t waitpid( pid_t pid,
               int *stat_loc,
               int options );

Description:

The waitpid() function suspends execution of the calling process until status information from one of its terminated child processes is available, or until the delivery of a signal whose action is either to terminate the process or execute a signal handler. If status information is available prior to the call to waitpid(), the return is immediate.

The waitpid() function behaves the same as the wait() function when passed a pid argument of -1 and the options argument has a value of zero.

The pid argument modifies the behavior of waitpid() in that it allows the calling process to specify a set of child processes for which status information is requested:

1. If pid is equal to -1, status is requested for any child process.
2. If pid is greater than zero, it specifies the process ID of a single child process for which status is requested.
3. If pid is equal to zero, status is requested from any child process whose process group ID is equal to that of the calling process.
4. If pid is less than -1, status is requested for any child process whose process group ID is equal to the absolute value of pid.

If stat_loc is non-NULL, the terminating status of the child process is placed in the integer pointed to by stat_loc. The macros listed below extract information from stat_loc. The stat_val argument to these macros is the integer value pointed to by stat_loc. At least the following macros are defined in <sys/wait.h>:

WIFEXITED( stat_val )

Evaluates to a nonzero value if the status returned was from a normally terminated child process.

WEXITSTATUS( stat_val )

If the value of WIFEXITED(stat_val) is nonzero, this macro evaluates to the low-order 8 bits of the termination status of the child process.

WIFSIGNALED( stat_val )

Evaluates to nonzero value if the child process terminated from receiving a signal that wasn't caught.

WTERMSIG( stat_val )

If the value of WIFSIGNALED(stat_val) is nonzero, this macro evaluates to the number of the signal that terminated the child process.

WIFSTOPPED( stat_val )

Evaluates to a nonzero value if the status returned is for a child process that is stopped.

WSTOPSIG( stat_val )

If the value of WIFSTOPPED(stat_val) is nonzero, this macro evaluates to the number of the signal that caused the child process to stop.

The options argument is constructed from the bitwise inclusive OR of zero or more of the following flags:

WNOHANG

The waitpid() function will not suspend execution of the calling process if status isn't immediately available for one of the child processes specified by pid.

Only one of the WIFEXITED(stat_val) and WIFSIGNALED(stat_val) macros can evaluate to a nonzero value.

Returns:

If successful, waitpid() returns the process ID of the terminating child process.

If waitpid() was invoked with WNOHANG set in options and there are no children waiting, it returns 0.

On delivery of a signal, waitpid() returns -1, and errno is set to EINTR.

Errors:

ECHILD

The calling process has no existing unwaited-for child processes that meet the criteria set by pid.

EINTR

The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.

EINVAL

The value of the options argument isn't valid.

Examples:

See fork().

Classification:

POSIX 1003.1

See also:

errno, signal(), wait()