waitpid

Suspends the calling process to wait for exit status of the specified child processes.

Syntax

   #include <sys/types.h>

   #include <sys/wait.h>

   pid_t waitpid (pid_t pid, int *stat_loc, int options);

Parameters

pid

An parameter of type pid_t that specifies the process whose status is being reported. Following are valid values and their meanings:

>0: A single child process with process ID equal to pid.
0: All child processes with process group ID equal to the caller's.
-1: All child processes.
<-1: All child processes with process group ID equal to the absolute value of pid.

stat_loc

A pointer to the exit status of the child process. No information is stored if stat_loc is NULL.

options

Modifies the behavior of the waitpid() function. The contents of options is a bitwise inclusive OR of the following flags (defined in <sys/wait.h>):

WNOHANG: Do not suspend the calling process when no child status is available.
WHANG: Suspend and wait for a child status if none is yet available.
WUNTRACED: Suspend and wait for the status of a stopped child process.

Return Values

>0: Success. The process ID of a terminated child process whose process ID matches pid is returned.
0: The WNOHANG option is specified in options and no child specified by pid has terminated.
-1: An error occurred. There is no result, and errno is set to indicate the error condition.

Description

The waitpid() function suspends the calling process until status information for the specified child process(es) is available. If status information is already available, wait() returns immediately.

If the calling process receives a signal whose action is to terminate, the calling process terminates. If the calling process receives a signal whose action is to execute a signal handling function, waitpid() returns to the calling process.

If status is available for more than one specified process, the order in which their status is reported may not correspond to the order of their termination.

The waitpid() function is identical to the wait() function when the pid parameter has a value of -1 and options is equal to zero.

The waitpid() function returns to the argument pointed to by stat_loc an exit status of 0 if, and only if, the child process that returned status took one of the following two actions:

returned a value of zero from its main() function (outer block)
passed a status value of zero to _exit() or exit()

The following macros that evaluate the stat_loc parameter, regardless of its value, are defined in the header <sys/wait.h>:

WIFEXITED(exit_status): Evaluates to a nonzero value if status was returned for a child process that terminated normally.
WEXITSTATUS(exit_status): If WIFEXITED is nonzero, this macro evaluates to the low-order 8 bits of the stat_loc parameter that the child process passed to _exit() or exit(), or the value that the child process returned from main().
WIFSIGNALED(exit_status): Evaluates to a nonzero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught.
WTERMSIG(exit_status): If WIFSIGNALED is nonzero, this macro evaluates to the number of the signal that caused the termination of the child process.
WIFSTOPPED(exit_status): Evaluates to a nonzero value if status was returned for a child process that is currently stopped.
WSTOPSIG(exit_status): If WIFSTOPPED is nonzero, this macro evaluates to the number of the signal that caused the child process to stop.

Implementation Considerations

Refer to the EFAULT error description below.

If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are terminated.

Errors

If an error occurs, errno is set to one of the following values:

`ECHILD`	CAUSE	The process or process group specified by `pid` does not exist or is not a child of the calling process.
	ACTION	No action is necessary.
`EFAULT`	CAUSE	The system detected a bad address in attempting to use the `stat_loc` parameter.
	ACTION	Make sure that the pointer is correctly initialized.
`EINTR`	CAUSE	The function was interrupted by a signal. The `stat_loc` parameter's value is undefined.
	ACTION	Call the `waitpid()` function again to continue waiting.
`EINVAL`	CAUSE	The `options` parameter is invalid.
	ACTION	Specify a valid option as defined in the file `<wait.h>`.

waitpid

Technical documentation

» Table of Contents

» Index