wait3(2)
_________________________________________________________________
wait3 System Call
Wait for child process to stop or terminate.
_________________________________________________________________
SYNTAX
#include <sys/wait.h>
#include <sys/time.h>
#include <sys/resource.h>
int wait3 (wait_status, options, rusage)
union wait * wait_status;
int options;
struct rusage * rusage;
PARAMETERS
wait_status NULL or address of a status word.
options Modifications to the action of wait3.
rusage NULL or address of a resource usage structure.
DESCRIPTION
Wait3 suspends the calling process until a child process stops or
terminates, then reports the identity, status, and resource usage
of the child process to the calling process. If more than one
child process has stopped or terminated, the manner in which one
is chosen is undefined.
* A process ("stops") when it is being traced (see ptrace) and
either hits a break point or receives a signal that is set
to be caught.
* A process ("terminates") when it calls exit either directly
or due to the receipt of a signal that causes the process to
terminate.
* A process that has terminated, but whose status has not been
reported on by wait may consume system resources. The wait
operation ("cleans-up") the terminated process and recovers
remaining system resources.
The identity of the child process is obtained by the return value
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
wait3(2)
of wait3.
The status of the child process is optionally obtained by the
<wait_status> parameter. If <wait_status> is NULL, status
information is not returned. Otherwise, 16 bits of status
information are stored in the low-order 16 bits of the location
pointed to by <wait_status>. <wait_status> can be used to
determine the termination cause. See wait().
A summary of the resources used by a child process that has
terminated is obtained by the <rusage> parameter. If <rusage> is
NULL, a summary is not returned. Otherwise, summary information
is stored in the location pointed to by <rusage>.
Wait(status) is identical to wait3(status, 0, NULL). However,
the action taken by wait3 may be modified by setting bits in the
<options> parameter as follows.
* The WNOHANG bit specifies that the calling process should
not be suspended by wait3.
* A process that is not being traced may be stopped by the
SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signals. The WUNTRACED
bit specifies that the status of all stopped child processes
should be reported, not just those being traced.
If a parent process terminates without waiting for its child
processes to terminate, a special system process inherits the
child processes.
If an error occurs, wait3 will not clean-up any process and the
values of <status> and <rusage> are undefined.
Wait3() is automatically restarted when a process receives a
signal while awaiting the termination of a child process.
ACCESS CONTROL
None.
RETURN VALUE
<child-process-id>
Completed successfully.
0 The WNOHANG bit in <options> was set and the
calling process would otherwise have been
suspended by wait3.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
wait3(2)
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
ECHILD The calling process has no child processes. This
condition implies that the calling process was not
suspended by wait3.
EFAULT The <status> or <rusage> arguments point to an
illegal address. This condition implies that the
calling process was not suspended by wait3.
SEE ALSO
The related system calls: exec, exit, fork, ptrace, sigpause,
sigvec, wait3.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)