share/man/man3c/wait3.3c

   1 '\" te
   2 .\"  Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.   Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
   3 .TH WAIT3 3C "Nov 4, 2005"
   4 .SH NAME
   5 wait3, wait4 \- wait for process to terminate or stop
   6 .SH SYNOPSIS
   7 .LP
   8 .nf
   9 #include <sys/wait.h>
  10 #include <sys/time.h>
  11 #include <sys/resource.h>
  12
  13 \fBpid_t\fR \fBwait3\fR(\fBint *\fR\fIstatusp\fR, \fBint\fR \fIoptions\fR, \fBstruct rusage *\fR\fIrusage\fR);
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fBpid_t\fR \fBwait4\fR(\fBpid_t\fR \fIpid\fR, \fBint *\fR\fIstatusp\fR, \fBint\fR \fIoptions\fR, \fBstruct rusage *\fR\fIrusage\fR);
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBwait3()\fR function delays its caller until a signal is received or one
  25 of its child processes terminates or stops due to tracing. If any child process
  26 has died or stopped due to tracing and this has not already been reported,
  27 return is immediate, returning the process \fBID\fR and status of one of those
  28 children. If that child process has died, it is discarded. If there are no
  29 children, \(mi1 is returned immediately. If there are only running or stopped
  30 but reported children, the calling process is blocked.
  31 .sp
  32 .LP
  33 If \fIstatusp\fR is not a null pointer, then on return from a successful
  34 \fBwait3()\fR call, the status of the child process is stored in the integer
  35 pointed to by \fIstatusp\fR. \fI*statusp\fR indicates the cause of termination
  36 and other information about the terminated process in the following manner:
  37 .RS +4
  38 .TP
  39 .ie t \(bu
  40 .el o
  41 If the low-order 8 bits of \fI*statusp\fR are equal to 0177, the child process
  42 has stopped; the 8 bits higher up from the low-order 8 bits of \fI*statusp\fR
  43 contain the number of the signal that caused the process to stop. See
  44 \fBsignal.h\fR(3HEAD).
  45 .RE
  46 .RS +4
  47 .TP
  48 .ie t \(bu
  49 .el o
  50 If the low-order 8 bits of \fI*statusp\fR are non-zero and are not equal to
  51 0177, the child process terminated due to a signal; the low-order 7 bits of
  52 \fI*statusp\fR contain the number of the signal that terminated the process. In
  53 addition, if the low-order seventh bit of \fI*statusp\fR (that is, bit 0200) is
  54 set, a ``core image'' of the process was produced; see \fBsignal.h\fR(3HEAD).
  55 .RE
  56 .RS +4
  57 .TP
  58 .ie t \(bu
  59 .el o
  60 Otherwise, the child process terminated due to an \fBexit()\fR call; the 8 bits
  61 higher up from the low-order 8 bits of \fI*statusp\fR contain the low-order 8
  62 bits of the argument that the child process passed to \fBexit()\fR; see
  63 \fBexit\fR(2).
  64 .RE
  65 .sp
  66 .LP
  67 The \fIoptions\fR argument is constructed from the bitwise inclusive \fBOR\fR
  68 of zero or more of the following flags, defined in <\fBsys/wait.h\fR>:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBWNOHANG\fR\fR
  73 .ad
  74 .RS 13n
  75 Execution of the calling process is not suspended if status is not immediately
  76 available for any child process.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBWUNTRACED\fR\fR
  83 .ad
  84 .RS 13n
  85 The status of any child processes that are stopped, and whose status has not
  86 yet been reported since they stopped, are also reported to the requesting
  87 process.
  88 .RE
  89
  90 .sp
  91 .LP
  92 If \fIrusage\fR is not a null pointer, a summary of the resources used by the
  93 terminated process and all its children is returned. Only the user time used
  94 and the system time used are currently available. They are returned in the
  95 \fBru_utime\fR and \fBru_stime\fR, members of the rusage structure,
  96 respectively.
  97 .sp
  98 .LP
  99 When the \fBWNOHANG\fR option is specified and no processes have status to
 100 report, \fBwait3()\fR returns 0. The \fBWNOHANG\fR and \fBWUNTRACED\fR options
 101 may be combined by the bitwise \fBOR\fR operation of the two values.
 102 .sp
 103 .LP
 104 The \fBwait4()\fR function is an extended interface.  If \fIpid\fR is 0,
 105 \fBwait4()\fR is equivalent to \fBwait3()\fR. If \fIpid\fR has a nonzero value,
 106 \fBwait4()\fR returns status only for the indicated process \fBID,\fR but not
 107 for any other child processes. If \fIpid\fR has a negative value, \fBwait4()\fR
 108 return status only for child processes whose process group ID is equal to the
 109 absolute value of \fIpid\fR. The status can be evaluated using the macros
 110 defined by \fBwait.h\fR(3HEAD).
 111 .SH RETURN VALUES
 112 .sp
 113 .LP
 114 If \fBwait3()\fR or \fBwait4()\fR returns due to a stopped or terminated child
 115 process, the process \fBID\fR of the child is returned to the calling process.
 116 Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the
 117 error.
 118 .sp
 119 .LP
 120 If \fBwait3()\fR or \fBwait4()\fR return due to the delivery of a signal to the
 121 calling process, \fB\(mi1\fR is returned and \fBerrno\fR is set to \fBEINTR\fR.
 122 If \fBWNOHANG\fR was set in \fIoptions\fR, it has at least one child process
 123 specified by \fIpid\fR for which status is not available, and status is not
 124 available for any process specified by \fIpid\fR, \fB0\fR is returned.
 125 Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the
 126 error.
 127 .sp
 128 .LP
 129 The \fBwait3()\fR and \fBwait4()\fR functions return \fB0\fR if \fBWNOHANG\fR
 130 is specified and there are no stopped or exited children, and return the
 131 process \fBID\fR of the child process if they return due to a stopped or
 132 terminated child process. Otherwise, they return \fB\(mi1\fR and set
 133 \fBerrno\fR to indicate the error.
 134 .SH ERRORS
 135 .sp
 136 .LP
 137 The \fBwait3()\fR and \fBwait4()\fR functions will fail and return immediately
 138 if:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBECHILD\fR\fR
 143 .ad
 144 .RS 10n
 145 The calling process has no existing unwaited-for child processes.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBEFAULT\fR\fR
 152 .ad
 153 .RS 10n
 154 The \fIstatusp\fR or \fIrusage\fR arguments point to an illegal address.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBEINTR\fR\fR
 161 .ad
 162 .RS 10n
 163 The function was interrupted by a signal. The value of the location pointed to
 164 by \fIstatusp\fR is undefined.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBEINVAL\fR\fR
 171 .ad
 172 .RS 10n
 173 The value of \fIoptions\fR is not valid.
 174 .RE
 175
 176 .sp
 177 .LP
 178 The \fBwait4()\fR function may fail if:
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBECHILD\fR\fR
 183 .ad
 184 .RS 10n
 185 The process specified by \fIpid\fR does not exist or is not a child of the
 186 calling process.
 187 .RE
 188
 189 .sp
 190 .LP
 191 The \fBwait3()\fRand \fBwait4()\fR functions will terminate prematurely, return
 192 \fB\(mi1\fR, and set \fBerrno\fR to \fBEINTR\fR upon the arrival of a signal
 193 whose \fBSA_RESTART\fR bit in its flags field is not set (see
 194 \fBsigaction\fR(2)).
 195 .SH ATTRIBUTES
 196 .sp
 197 .LP
 198 See \fBattributes\fR(5) for descriptions of the following attributes:
 199 .sp
 200
 201 .sp
 202 .TS
 203 box;
 204 c | c
 205 l | l .
 206 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 207 _
 208 MT-Level        Async-Signal-Safe
 209 .TE
 210
 211 .SH SEE ALSO
 212 .sp
 213 .LP
 214 \fBkill\fR(1), \fBexit\fR(2), \fBwaitid\fR(2), \fBwaitpid\fR(3C),
 215 \fBgetrusage\fR(3C), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD), \fBwait\fR(3C),
 216 \fBwait.h\fR(3HEAD), \fBproc\fR(4), \fBattributes\fR(5)
 217 .SH NOTES
 218 .sp
 219 .LP
 220 If a parent process terminates without waiting on its children, the
 221 initialization process (process \fBID\fR = 1) inherits the children.
 222 .sp
 223 .LP
 224 The \fBwait3()\fR and  \fBwait4()\fR functions are automatically restarted when
 225 a process receives a signal while awaiting termination of a child process,
 226 unless the \fBSA_RESTART\fR bit is not set in the flags for that signal.