HP-UX Reference (11i v2 03/08) - 2 System Calls (vol 5)

w
wait3(2) wait3(2)
NAME
wait3 - wait for child process to change state
SYNOPSIS
#include <sys/wait.h>
pid_t wait3 (int *stat_loc, int options,struct rusage *resource_usage);
DESCRIPTION
The wait3() function allows the calling process to obtain various status information for a caller’s child
process based on the options specified. If status information is available for two or more child processes,
the order of which process to report status on is not defined.
Note that 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()
is not a null pointer,
the
rusage structure that the resource_usage argument points to is filled in for the child process
identified by the return value.
The stat_loc argument is the address where status about the specified child process is placed.
The options argument is constructed from the bitwise-inclusive OR of zero or more of the following flags
defined in the header
<sys/wait.h>:
WCONTINUED The status of any continued child process specified by pid that has not
been reported since it continued is reported to the requesting process.
WNOHANG The wait3() function will not suspend execution of the calling process
if status is not immediately available for one of the child processes
specified by pid .
WNOWAIT This causes the wait not to be registered. This means that the registered
process that is being waited on, can be waited on again with identical
results, provided that the status of the child does not change in the
meantime.
WUNTRACED The status of any child processes specified by pid that are stopped and
whose status has not yet been reported since they stopped, will also be
reported to the requesting process.
The resource_usage argument points to the resource utilization structure.
APPLICATION USAGE
Threads Considerations
In a multi-threaded application, only the calling thread is suspended by wait3().
wait3() will not return until all threads in the process have reached the desired state. For example,
wait3() will not return until all threads have terminated. If the WUNTRACED or WCONTINUED options
are specified, wait3() will not return until all threads have stopped or continued respectively.
RETURN VALUE
If
wait3() or waitpid() returns because the status of a child process is available, then the return
value is the process ID of that child process. If wait3() or waitpid() returns due to the receipt of a
signal, then the return value receives a -1 and errno is set to [EINTR].
If
wait3() was called with the WNOHANG options argument where status is not available for any process
specified by the pid argument, 0 will be returned.
Otherwise, pid
-1 will be returned and errno will be set to indicate the error.
ERRORS
If
wait3() fails, errno is set to one of the following values:
[ECHILD] The calling process has no existing unwaited-for child processes, or if the
set of processes specified by the pid argument can never be in the states
Section 2−−484 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: August 2003