Standard C Library Functions wait3(3C)
NAME
wait3, wait4 - wait for process to terminate or stop
SYNOPSIS
#include
#include
#include
pidt wait3(int *statusp, int options, struct rusage *rusage);
pidt wait4(pidt pid, int *statusp, int options, struct rusage *rusage);
DESCRIPTION
The wait3() function delays its caller until a signal is
received or one of its child processes terminates or stops
due to tracing. If any child process has died or stopped due
to tracing and this has not already been reported, return is
immediate, returning the process ID and status of one of
those children. If that child process has died, it is dis-
carded. If there are no children, -1 is returned immedi-
ately. If there are only running or stopped but reported
children, the calling process is blocked.
If statusp is not a null pointer, then on return from a suc-
cessful wait3() call, the status of the child process is
stored in the integer pointed to by statusp. *statusp indi-
cates the cause of termination and other information about
the terminated process in the following manner:
o If the low-order 8 bits of *statusp are equal to
0177, the child process has stopped; the 8 bits
higher up from the low-order 8 bits of *statusp
contain the number of the signal that caused the
process to stop. See signal.h(3HEAD).
o If the low-order 8 bits of *statusp are non-zero
and are not equal to 0177, the child process ter-
minated due to a signal; the low-order 7 bits of
*statusp contain the number of the signal that ter-
minated the process. In addition, if the low-order
seventh bit of *statusp (that is, bit 0200) is set,
a ``core image'' of the process was produced; see
signal.h(3HEAD).
o Otherwise, the child process terminated due to an
exit() call; the 8 bits higher up from the low-
order 8 bits of *statusp contain the low-order 8
bits of the argument that the child process passed
to exit(); see exit(2).
SunOS 5.11 Last change: 4 Nov 2005 1
Standard C Library Functions wait3(3C)
The options argument is constructed from the bitwise
inclusive OR of zero or more of the following flags, defined
in :
WNOHANG Execution of the calling process is not
suspended if status is not immediately avail-
able for any child process.
WUNTRACED The status of any child processes that are
stopped, and whose status has not yet been
reported since they stopped, are also reported
to the requesting process.
If rusage is not a null pointer, a summary of the resources
used by the terminated process and all its children is
returned. Only the user time used and the system time used
are currently available. They are returned in the ruutime
and rustime, members of the rusage structure, respectively.
When the WNOHANG option is specified and no processes have
status to report, wait3() returns 0. The WNOHANG and WUN-
TRACED options may be combined by the bitwise OR operation
of the two values.
The wait4() function is an extended interface. If pid is 0,
wait4() is equivalent to wait3(). If pid has a nonzero
value, wait4() returns status only for the indicated process
ID, but not for any other child processes. If pid has a
negative value, wait4() return status only for child
processes whose process group ID is equal to the absolute
value of pid. The status can be evaluated using the macros
defined by wait.h(3HEAD).
RETURN VALUES
If wait3() or wait4() returns due to a stopped or terminated
child process, the process ID of the child is returned to
the calling process. Otherwise, -1 is returned and errno is
set to indicate the error.
If wait3() or wait4() return due to the delivery of a signal
to the calling process, -1 is returned and errno is set to
EINTR. If WNOHANG was 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, 0 is returned. Otherwise, -1 is returned
and errno is set to indicate the error.
SunOS 5.11 Last change: 4 Nov 2005 2
Standard C Library Functions wait3(3C)
The wait3() and wait4() functions return 0 if WNOHANG is
specified and there are no stopped or exited children, and
return the process ID of the child process if they return
due to a stopped or terminated child process. Otherwise,
they return -1 and set errno to indicate the error.
ERORS
The wait3() and wait4() functions will fail and return
immediately if:
ECHILD The calling process has no existing unwaited-for
child processes.
EFAULT The statusp or rusage arguments point to an ille-
gal address.
EINTR The function was interrupted by a signal. The
value of the location pointed to by statusp is
undefined.
EINVAL The value of options is not valid.
The wait4() function may fail if:
ECHILD The process specified by pid does not exist or is
not a child of the calling process.
The wait3()and wait4() functions will terminate prematurely,
return -1, and set errno to EINTR upon the arrival of a sig-
nal whose SARESTART bit in its flags field is not set (see
sigaction(2)).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 4 Nov 2005 3
Standard C Library Functions wait3(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Async-Signal-Safe
SEE ALSO
kill(1), exit(2), waitid(2), waitpid(3C), getrusage(3C),
signal(3C), signal.h(3HEAD), wait(3C), wait.h(3HEAD),
proc(4), attributes(5)
NOTES
If a parent process terminates without waiting on its chil-
dren, the initialization process (process ID = 1) inherits
the children.
The wait3() and wait4() functions are automatically res-
tarted when a process receives a signal while awaiting ter-
mination of a child process, unless the SARESTART bit is
not set in the flags for that signal.
SunOS 5.11 Last change: 4 Nov 2005 4
|
