wait4()

Suspend the calling process

Synopsis:

#include <sys/types.h>
#include <sys/wait.h>

pid_t wait4( pid_t pid, 
             int * stat_loc, 
             int options, 
             struct rusage * resource_usage );

Library:

libc

Description:

The wait4() 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 wait4(), the return is immediate.

The wait4() 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 wait4() 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 the stat_loc variable is non-NULL, the terminating status of the child process is placed here. For information about macros that extract information from stat_loc, see "Status macros" in the description of wait().

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

WCONTINUED

Return the status for any child that was stopped and has been continued.

WEXITED

Wait for process(es) to exit.

WNOHANG

Return immediately if there are no children to wait for.

WNOWAIT

Keep the process in a waitable state. This doesn't affect the state of the process; the process may be waited for again after this call completion.

WSTOPPED

Wait for and return the process status of any child that has stopped because it received a signal.

WUNTRACED

Report status of stopped child process.

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

The following call:

wait3( stat_loc, options, resource_usage );

is equivalent to the call:

waitpid( (pid_t)-1, stat_loc, options );

except that on successful completion, if the resource_usage argument to wait3() isn't a null pointer, the rusage structure that the third argument points to is filled in for the child process identified by the return value.

It's also equivalent to:

wait4( (pid_t)-1, stat_loc, options, resource_usage );

Returns:

If successful, wait4() returns the process id of the terminating child process. If wait4() was invoked with WNOHANG set in options, it has at least one child process specified by pid for which status is not available, and status is not available for any process specified by pid, a value of zero is returned. 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.

Classification:

Unix

See also:

exit(), fork(), pause(), wait3(), waitid(), waitpid()