1 files changed, 383 insertions, 0 deletions
diff --git a/usr/src/man/man3ucb/wait.3ucb b/usr/src/man/man3ucb/wait.3ucb
new file mode 100644
index 0000000000..a685d47b69
--- /dev/null
+++ b/usr/src/man/man3ucb/wait.3ucb
@@ -0,0 +1,383 @@
+'\" 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 "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions"
+.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
+.mk
+.na
+\fB\fBWNOHANG\fR\fR
+.ad
+.RS 13n
+.rt  
+\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
+.mk
+.na
+\fB\fBWUNTRACED\fR\fR
+.ad
+.RS 13n
+.rt  
+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
+.mk
+.na
+\fB\fBECHILD\fR\fR
+.ad
+.RS 10n
+.rt  
+The calling process has no existing unwaited-for child processes.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+.rt  
+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
+.mk
+.na
+\fB\fBECHILD\fR\fR
+.ad
+.RS 10n
+.rt  
+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
+.mk
+.na
+\fB\fBEINTR\fR\fR
+.ad
+.RS 10n
+.rt  
+The function was interrupted by a signal. The value of the location pointed to
+by \fIstatusp\fR is undefined.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+.rt  
+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.