NAME

wait3 − optionally wait for stopped/terminated child or traced process, or FBS-scheduled children

SYNOPSIS

#include <sys/time.h>
#include <sys/resource.h>
#include <sys/wait.h>

pid = wait3 (status, options, rusage)
pid_t pid;
union wait ∗status;
int options;
struct rusage ∗rusage;

DESCRIPTION

wait3 optionally suspends the calling process until one of its immediate children stops, terminates, or is successfully scheduled on a frequency based scheduler.  wait3 also optionally suspends the calling process until one of the processes it is tracing stops or terminates; see ptrace(2).  On return from a successful wait3 call, status contains the status of the stopped or terminated process, or frequency based scheduled child process.  A more precise definition of the status word is given in <sys/wait.h>. 

The options parameter can be one or more of the following values or’ed together:

WNOHANG Do not block if there are no children or traced processes that wish to report status. 

WNOWAIT Keep the process whose status is returned in a waitable state.  The process may be waited for again with identical results. 

WUNTRACED
Report status on stopped children.

WCONTINUED
Report status on stopped children that have been continued.

WFBSWAIT Report status on frequency based scheduled children. 

If rusage is non-zero, a summary of the resources used by the waited-on process and all of its children is returned (this information is currently not available for stopped processes or traced processes which are not immediate children of the calling process). 

NOTES

See signal(2) for a list of termination statuses (signals); 0 status indicates normal termination. 

If the WCOREFLG bit of the termination status is set, a core image of the process was produced by the system. 

A special status (WSTOPFLG) is returned for a stopped process which has not terminated and can be restarted; see ptrace(2). 

A special status (WFBSSCHED) is returned for frequency based scheduled children. 

If a parent process terminates without waiting on its children, the initialization process (process ID = 1) inherits the children. 

wait3 is automatically restarted when a process receives a signal while it is blocked waiting for status on one of its children or traced processes.  (NOTE: this is not true if wait3 is used in an AT&T environment.  In this case the function will return with EINTR). 

RETURN VALUE

wait3 returns the process ID of the terminated, stopped, or frequency based scheduled process; or -1 if the caller has no unwaited-for children or traced processes; or 0 if the WNOHANG option is specified and the caller has no unwaited-for children or traced processes. 

ERRORS

wait3 will fail and return immediately if one or more of the following are true:

ECHILD The calling process has no existing unwaited-for child or traced processes. 

EFAULT The status or rusage arguments point to an illegal address. 

EINTR The function was interrupted by a signal (AT&T environment). 

SEE ALSO

exit(2), ptrace(2)
signal(5), wstat(5)

CX/UX Programmer’s Reference Manual