path: root/usr/src/man/man3ucb/wait.3ucb

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
.TH WAIT 3UCB "Oct 30, 2007"
.SH NAME
wait, wait3, wait4, waitpid, WIFSTOPPED, WIFSIGNALED, WIFEXITED \- wait for
process to terminate or stop
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ...
#include <sys/wait.h>

\fBint\fR \fBwait\fR(\fIstatusp\fR)
\fBint *\fR\fIstatusp\fR;
.fi

.LP
.nf
\fBint\fR \fBwaitpid\fR(\fIpid\fR, \fIstatusp\fR, \fIoptions\fR)
\fBint\fR \fIpid\fR;
\fBint *\fR\fIstatusp\fR;
\fBint\fR \fIoptions\fR;
.fi

.LP
.nf
#include <sys/time.h>
#include <sys/resource.h>

\fBint\fR \fBwait3\fR(\fIstatusp\fR, \fIoptions\fR, \fIrusage\fR)
\fBint *\fR\fIstatusp\fR;
\fBint\fR \fIoptions\fR;
\fBstruct rusage *\fR\fIrusage\fR;
.fi

.LP
.nf
\fBint\fR \fBwait4\fR(\fIpid\fR, \fIstatusp\fR, \fIoptions\fR, \fIrusage\fR)
\fBint\fR \fIpid\fR;
\fBint *\fR\fIstatusp\fR;
\fBint\fR \fIoptions\fR;
\fBstruct rusage *\fR\fIrusage\fR;
.fi

.LP
.nf
\fBWIFSTOPPED\fR(\fIstatus\fR)
\fBint\fR \fIstatus\fR;
.fi

.LP
.nf
\fBWIFSIGNALED\fR(\fIstatus\fR)
\fBint\fR \fIstatus\fR;
.fi

.LP
.nf
\fBWIFEXITED\fR(\fIstatus\fR)
\fBint\fR \fIstatus\fR;
.fi

.SH DESCRIPTION
.sp
.LP
The \fBwait()\fR 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 been reported using
\fBwait()\fR, return is immediate, returning the process \fBID\fR and exit
status of one of those children. If that child process has died, it is
discarded. If there are no children, return is immediate with the value \(mi1
returned. If there are only running or stopped but reported children, the
calling process is blocked.
.sp
.LP
If \fIstatus\fR is not a \fINULL\fR pointer, then on return from a successful
\fBwait()\fR call the status of the child process whose process \fBID\fR is the
return value of \fBwait()\fR is stored in the \fBwait()\fR union pointed to by
\fIstatus\fR. The \fBw_status\fR member of that union is an \fBint\fR; it
indicates the cause of termination and other information about the terminated
process in the following manner:
.RS +4
.TP
.ie t \(bu
.el o
If the low-order 8 bits of \fBw_status\fR are equal to 0177, the child process
has stopped; the 8 bits higher up from the low-order 8 bits of \fBw_status\fR
contain the number of the signal that caused the process to stop.
See\fBptrace\fR(3C) and \fBsigvec\fR(3UCB).
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the low-order 8 bits of \fBw_status\fR are non-zero and are not equal to
0177, the child process terminated due to a signal; the low-order 7 bits of
\fBw_status\fR contain the number of the signal that terminated the process. In
addition, if the low-order seventh bit of \fBw_status\fR (that is, bit 0200) is
set, a ``core image'' of the process was produced; see \fBsigvec\fR(3UCB).
.RE
.RS +4
.TP
.ie t \(bu
.el o
Otherwise, the child process terminated due to an \fBexit()\fR call; the 8 bits
higher up from the low-order 8 bits of \fBw_status\fR contain the low-order 8
bits of the argument that the child process passed to \fBexit()\fR; see
\fBexit\fR(2).
.RE
.sp
.LP
\fBwaitpid()\fR behaves identically to \fBwait()\fR if   \fIpid\fR has a value
of \(mi1 and \fIoptions\fR has a value of zero. Otherwise, the behavior of
\fBwaitpid()\fR is modified by the values of   \fIpid\fR and \fIoptions\fR as
follows:
.sp
.LP
\fIpid\fR specifies a set of child processes for which status is requested.
\fBwaitpid()\fR only returns the status of a child process from this set.
.RS +4
.TP
.ie t \(bu
.el o
If  \fIpid\fR is equal to \(mi1, status is requested for any child process. In
this respect, \fBwaitpid()\fR is then equivalent to \fBwait()\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If  \fIpid\fR is greater than zero, it specifies the process \fBID\fR of a
single child process for which status is requested.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If  \fIpid\fR is equal to zero, status is requested for any child process whose
process group \fBID\fR is equal to that of the calling process.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If  \fIpid\fR is less than \(mi1, status is requested for any child process
whose process group \fBID\fR is equal to the absolute value of \fIpid\fR.
.RE
.sp
.LP
\fIoptions\fR is constructed from the bitwise inclusive \fBOR\fR of zero or
more of the following flags, defined in the header \fB<sys/wait.h>\fR:
.sp
.ne 2
.na
\fB\fBWNOHANG\fR\fR
.ad
.RS 13n
\fBwaitpid()\fR does not suspend execution of the calling process if status is
not immediately available for one of the child processes specified by
\fIpid\fR.
.RE

.sp
.ne 2
.na
\fB\fBWUNTRACED\fR\fR
.ad
.RS 13n
The status of any child processes specified by \fIpid\fR that are stopped, and
whose status has not yet been reported since they stopped, are also reported to
the requesting process.
.RE

.sp
.LP
\fBwait3()\fR is an alternate interface that allows both non-blocking status
collection and the collection of the status of children stopped by any means.
The \fIstatus\fR parameter is defined as above. The \fIoptions\fR parameter is
used to indicate the call should not block if there are no processes that have
status to report (\fBWNOHANG\fR), and/or that children of the current process
that are stopped due to a \fBSIGTTIN\fR, \fBSIGTTOU\fR, \fBSIGTSTP\fR, or
\fBSIGSTOP\fR signal are eligible to have their status reported as well
(\fBWUNTRACED\fR). A terminated child is discarded after it reports status, and
a stopped process will not report its status more than once. If \fIrusage\fR is
not a \fINULL\fR 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
\fBrusage.ru_utime\fR and \fBrusage.ru_stime\fR, respectively.
.sp
.LP
When the \fBWNOHANG\fR option is specified and no processes have status to
report, \fBwait3()\fR returns 0. The \fBWNOHANG\fR and \fBWUNTRACED\fR options
may be combined by \fBORing\fR the two values.
.sp
.LP
\fBwait4()\fR is another alternate interface.  With a \fIpid\fR argument of 0,
it is equivalent to \fBwait3()\fR. If \fIpid\fR has a nonzero value, then
\fBwait4()\fR returns status only for the indicated process \fBID,\fR but not
for any other child processes.
.sp
.LP
\fBWIFSTOPPED\fR, \fBWIFSIGNALED\fR, \fBWIFEXITED\fR, are macros that take an
argument \fIstatus\fR, of type \fBint\fR, as returned by \fBwait()\fR, or
\fBwait3()\fR, or  \fBwait4()\fR. \fBWIFSTOPPED\fR evaluates to true (1) when
the process for which the \fBwait()\fR call was made is stopped, or to false
(0) otherwise. \fBWIFSIGNALED\fR evaluates to true when the process was
terminated with a signal. \fBWIFEXITED\fR evaluates to true when the process
exited by using an \fBexit\fR(2) call.
.SH RETURN VALUES
.sp
.LP
If \fBwait()\fRor \fBwaitpid()\fR returns due to a stopped or terminated child
process, the process ID of the child is returned to the calling process.
Otherwise, a value of \fB\(mi1\fR is returned and \fBerrno\fR is set to
indicate the error.
.sp
.LP
If \fBwait()\fR or \fBwaitpid()\fR return due to the delivery of a signal to
the calling process, a value of \fB\(mi1\fR is returned and \fBerrno\fR is set
to \fBEINTR.\fR If \fBwaitpid()\fR function was invoked with \fBWNOHANG\fR set
in \fIoptions\fR, it has at least one child process specified by \fIpid\fR for
which status is not available, and status is not available for any process
specified by \fIpid\fR, a value of zero is returned. Otherwise, a value of
\fB\(mi1\fR is returned, and \fBerrno\fR is set to indicate the error.
.sp
.LP
\fBwait3(\|)\fR and  \fBwait4(\|)\fR return 0 if \fBWNOHANG\fR is specified and
there are no stopped or exited children, and returns the process \fBID\fR of
the child process if it returns due to a stopped or terminated child process.
Otherwise, they returns a value of \fB\(mi1\fR and sets \fBerrno\fR to indicate
the error.
.SH ERRORS
.sp
.LP
The \fBwait()\fR, \fBwait3()\fR and \fBwait4()\fR functions will fail and
return immediately if:
.sp
.ne 2
.na
\fB\fBECHILD\fR\fR
.ad
.RS 10n
The calling process has no existing unwaited-for child processes.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The \fIstatus\fR or \fIrusage\fR arguments point to an illegal address.
.RE

.sp
.LP
\fBwaitpid()\fR may set \fBerrno\fR to:
.sp
.ne 2
.na
\fB\fBECHILD\fR\fR
.ad
.RS 10n
The process or process group specified by \fIpid\fR does not exist or is not a
child of the calling process.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
The function was interrupted by a signal. The value of the location pointed to
by \fIstatusp\fR is undefined.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The value of \fIoptions\fR is not valid.
.RE

.sp
.LP
The \fBwait()\fR, \fBwait3()\fR, and \fBwait4()\fR functions will terminate
prematurely, return \(mi1, and set \fBerrno\fR to \fBEINTR\fR upon the arrival
of a signal whose \fBSV_INTERRUPT\fR bit in its flags field is set (see
\fBsigvec\fR(3UCB) and \fBsiginterrupt\fR(3UCB)). \fBsignal\fR(3UCB), sets this
bit for any signal it catches.
.SH SEE ALSO
.sp
.LP
\fBexit\fR(2), \fBgetrusage\fR(3C), \fBptrace\fR(3C), \fBsiginterrupt\fR(3UCB),
\fBsignal\fR(3C), \fBsignal\fR(3UCB), \fBsigvec\fR(3UCB), \fBwait\fR(3C),
\fBwaitpid\fR(3C)
.SH NOTES
.sp
.LP
Use of these interfaces should be restricted to only applications written on
BSD platforms.  Use of these interfaces with any of the system libraries or in
multi-thread applications is unsupported.
.sp
.LP
If a parent process terminates without waiting on its children, the
initialization process (process \fBID\fR = 1) inherits the children.
.sp
.LP
The \fBwait()\fR, \fBwait3()\fR, and \fBwait4()\fR functions are automatically
restarted when a process receives a signal while awaiting termination of a
child process, unless the \fBSV_INTERRUPT\fR bit is set in the flags for that
signal.
.sp
.LP
Calls to \fBwait()\fR with an argument of  \fB0\fR should be cast to type
`\fBint *\fR', as in:
.sp
.in +2
.nf
\fBwait((int *)0)\fR
.fi
.in -2
.sp

.sp
.LP
Previous SunOS releases used \fBunion\fR \fBwait\fR\fB*statusp\fR and
\fBunion\fR \fBwait\fR \fBstatus\fR in place of \fBint *statusp\fR and
\fBint\fR status. The union contained a member \fBw_status\fR that could be
treated in the same way as \fIstatus\fR.
.sp
.LP
Other members of the \fBwait\fR union could be used to extract this information
more conveniently:
.RS +4
.TP
.ie t \(bu
.el o
If the \fBw_stopval\fR member had the value \fB\fR\fBWSTOPPED\fR\fB, \fR the
child process had stopped; the value of the \fBw_stopsig\fR member was the
signal that stopped the process.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the \fBw_termsig\fR member was non-zero, the child process terminated due to
a signal; the value of the \fBw_termsig\fR member was the number of the signal
that terminated the process.  If the \fBw_coredump\fR member was non-zero, a
core dump was produced.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Otherwise, the child process terminated due to a call to \fBexit()\fR. The
value of the \fBw_retcode\fR member was the low-order 8 bits of the argument
that the child process passed to \fBexit()\fR.
.RE
.sp
.LP
\fBunion\fR \fBwait\fR is obsolete in light of the new specifications provided
by \fIIEEE Std 1003.1-1988\fR and endorsed by \fISVID89\fR and \fIXPG3\fR.
SunOS Release 4.1 supports \fBunion\fR\fBwait\fR for backward compatibility,
but it will disappear in a future release.