wait3(2) wait3(2)
NAME [Toc] [Back]
wait3(), wait4() - wait for child process to change state
SYNOPSIS [Toc] [Back]
#include <sys/wait.h>
pid_t wait3 (int *stat_loc, int options, struct rusage *resource_usage);
pid_t wait4 (pid_t pid, int *stat_loc, int options,
struct rusage *resource_usage);
DESCRIPTION [Toc] [Back]
The wait3() and wait4() functions allow 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.
The wait4() function is similar to wait3(), except that wait4() waits
for a specific child as indicated by the pid parameter.
Note that the following call
wait3(stat_loc, options, resource_usage);
is equivalent to the call:
waitpid((pid_t)-1, stat_loc, options);
Note that the following call
wait4(pid, stat_loc, options, resource_usage);
is equivalent to the call:
waitpid(pid, stat_loc, options);
In both of the previous prototypes, on successful completion, if the
resource_usage argument to wait3() or wait4() 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 pid argument specifies a child process for which status is
requested. The following rules define which status information is
returned:
+ If pid is equal to (pid_t) -1, status is requested for any
child process.
+ If pid is greater than 0, it specifies the process ID of a
single child process for which status is requested.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
wait3(2) wait3(2)
+ If pid is 0, status is requested for any child process whose
process group ID is equal to that of the calling process.
+ If pid is less than (pid_t) -1, status is requested for any
child process whose process group ID is equal to the absolute
value of pid.
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 <sys/wait.h> header
file:
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() and wait4() functions 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 [Toc] [Back]
Threads Considerations
In a multi-threaded application, only the calling thread is suspended
by wait3() and wait4().
The wait3() and wait4() functions will not return until all threads in
the process have reached the desired state. For example, wait3() and
wait4() will not return until all threads have terminated. If the
WUNTRACED or WCONTINUED options are specified, wait3() and wait4()
will not return until all threads have stopped or continued
respectively.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
wait3(2) wait3(2)
RETURN VALUE [Toc] [Back]
If wait3(), wait4(), or waitpid() returns because the status of a
child process is available, the return value is the process ID of that
child process. If wait3(), wait4(), or waitpid() returns due to the
receipt of a signal, the return value receives a -1 and errno is set
to [EINTR].
If wait3() or wait4() 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_t) -1 will be returned and errno will be set to
indicate the error.
ERRORS [Toc] [Back]
If wait3() or wait4() fails, errno is set to one of the following
values:
[ECHILD] The calling process has no existing unwaited-for
child processes; or the states specified by the
options argument are invalid for the set of
processes specified by the pid argument.
[EFAULT] Problems were encountered in the retrieval of
status information for the specified child
process.
[EINTR] The wait3() or wait4() function has been
interrupted by a signal. The value in the
location pointed to by the stat_loc argument is
undefined.
[EINVAL] The options argument to wait3(), wait4(), or
waitpid() is invalid.
WARNINGS [Toc] [Back]
The behavior of wait3() and wait4() is affected if the SIGCLD signal
is set to SIG_IGN. See the WARNINGS section of signal(5). Signal
handlers that cause system calls to be restarted can affect the
[EINTR] condition described above (see bsdproc(3C), sigaction(2), and
sigvector(2)).
AUTHOR [Toc] [Back]
The wait3() and wait4() functions were developed by HP, AT&T, and the
University of California, Berkeley.
SEE ALSO [Toc] [Back]
exec(2), exit(2), fork(2), pause(2), wait(2), waitpid(2).
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
