usr/src/man/man3c/waitpid.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH WAITPID 3C "Dec 7, 2007"
  48 .SH NAME
  49 waitpid \- wait for child process to change state
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <sys/types.h>
  54 #include <sys/wait.h>
  55
  56 \fBpid_t\fR \fBwaitpid\fR(\fBpid_t\fR \fIpid\fR, \fBint *\fR\fIstat_loc\fR, \fBint\fR \fIoptions\fR);
  57 .fi
  58
  59 .SH DESCRIPTION
  60 .sp
  61 .LP
  62 The \fBwaitpid()\fR function will suspend execution of the calling thread until
  63 status information for one of its terminated child processes is available, or
  64 until delivery of a signal whose action is either to execute a signal-catching
  65 function or to terminate the process. If more than one thread is suspended in
  66 \fBwaitpid()\fR, \fBwait\fR(3C), or \fBwaitid\fR(2) awaiting termination of the
  67 same process, exactly one thread will return the process status at the time of
  68 the target process termination. If status information is available prior to the
  69 call to \fBwaitpid()\fR, return will be immediate.
  70 .sp
  71 .LP
  72 The \fIpid\fR argument specifies a set of child processes for which status is
  73 requested, as follows:
  74 .RS +4
  75 .TP
  76 .ie t \(bu
  77 .el o
  78 If \fIpid\fR is less than \fB(pid_t)\(mi1\fR, status is requested for any child
  79 process whose process group  \fBID\fR is equal to the absolute value of
  80 \fIpid\fR.
  81 .RE
  82 .RS +4
  83 .TP
  84 .ie t \(bu
  85 .el o
  86 If \fIpid\fR is equal to \fB(pid_t)\(mi1\fR, status is requested for any child
  87 process.
  88 .RE
  89 .RS +4
  90 .TP
  91 .ie t \(bu
  92 .el o
  93 If  \fIpid\fR is equal to \fB(pid_t)0\fR status is requested for any child
  94 process whose process group  \fBID\fR is equal to that of the calling process.
  95 .RE
  96 .RS +4
  97 .TP
  98 .ie t \(bu
  99 .el o
 100 If  \fIpid\fR is greater than \fB(pid_t)0\fR, it specifies the process \fBID\fR
 101 of the child process for which status is requested.
 102 .RE
 103 .sp
 104 .LP
 105 One instance of a \fBSIGCHLD\fR signal is queued for each child process whose
 106 status has changed. If \fBwaitpid()\fR returns because the status of a child
 107 process is available, and \fBWNOWAIT\fR was not specified in \fIoptions\fR, any
 108 pending \fBSIGCHLD\fR signal associated with the process ID of that child
 109 process is discarded. Any other pending \fBSIGCHLD\fR signals remain pending.
 110 .sp
 111 .LP
 112 If the calling process has \fBSA_NOCLDWAIT\fR set or has \fBSIGCHLD\fR set to
 113 \fBSIG_IGN\fR and the process has no unwaited children that were transformed
 114 into zombie processes, it will block until all of its children terminate, and
 115 \fBwaitpid()\fR will fail and set \fBerrno\fR to \fBECHILD\fR.
 116 .sp
 117 .LP
 118 If \fBwaitpid()\fR returns because the status of a child process is available,
 119 then that  status may be evaluated with the macros defined by
 120 \fBwait.h\fR(3HEAD) If the calling process had specified a non-zero value of
 121 \fIstat_loc\fR, the status of the child process will be stored in the location
 122 pointed to by \fIstat_loc\fR.
 123 .sp
 124 .LP
 125 The \fIoptions\fR argument is constructed from the bitwise-inclusive OR of zero
 126 or more of the following flags, defined in the header  <\fBsys/wait.h\fR>:
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBWCONTINUED\fR\fR
 131 .ad
 132 .RS 14n
 133 The status of any continued child process specified by \fIpid\fR, whose status
 134 has not been reported since it continued, is also reported to the calling
 135 process.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBWNOHANG\fR\fR
 142 .ad
 143 .RS 14n
 144 The \fBwaitpid()\fR function will not suspend execution of the calling process
 145 if status is not immediately available for one of the child processes specified
 146 by \fIpid\fR.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBWNOWAIT\fR\fR
 153 .ad
 154 .RS 14n
 155 Keep the process whose status is returned in \fIstat_loc\fR in a waitable
 156 state. The process may be waited for again with identical results.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBWUNTRACED\fR\fR
 163 .ad
 164 .RS 14n
 165 The status of any child processes specified by \fIpid\fR that are stopped, and
 166 whose status has not yet been reported since they stopped, is also reported to
 167 the calling process. \fBWSTOPPED\fR is a synonym for \fBWUNTRACED\fR.
 168 .RE
 169
 170 .SH RETURN VALUES
 171 .sp
 172 .LP
 173 If \fBwaitpid()\fR returns because the status of a child process is available,
 174 it returns a value equal to the process \fBID\fR of the child process for which
 175 status is reported.  If \fBwaitpid()\fR returns due to the delivery of a signal
 176 to the calling process, \fB\(mi1\fR is returned and \fBerrno\fR is set to
 177 \fBEINTR\fR.  If \fBwaitpid()\fR was invoked with \fBWNOHANG\fR set in
 178 \fIoptions\fR, it has at  least one child process specified by \fIpid\fR for
 179 which status is not available, and status is not available for any process
 180 specified by \fIpid\fR, then \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
 181 returned and \fBerrno\fR is set to indicate the error.
 182 .SH ERRORS
 183 .sp
 184 .LP
 185 The \fBwaitpid()\fR function will fail if:
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBECHILD\fR\fR
 190 .ad
 191 .RS 10n
 192 The process or process group specified by \fIpid\fR does not exist or is not a
 193 child of the calling process or can never be in the states specified by
 194 \fIoptions\fR.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBEINTR\fR\fR
 201 .ad
 202 .RS 10n
 203 The \fBwaitpid()\fR function was interrupted due to the receipt of a signal
 204 sent by the calling process.
 205 .RE
 206
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBEINVAL\fR\fR
 211 .ad
 212 .RS 10n
 213 An invalid value was specified for \fIoptions.\fR
 214 .RE
 215
 216 .SH USAGE
 217 .sp
 218 .LP
 219 With \fIoptions\fR equal to \fB0\fR and  \fIpid\fR equal to \fB(pid_t)\(mi1\fR,
 220 \fBwaitpid()\fR is identical to \fBwait\fR(3C). The \fBwaitpid()\fR function is
 221 implemented as a call to the more general \fBwaitid\fR(2) function.
 222 .SH ATTRIBUTES
 223 .sp
 224 .LP
 225 See \fBattributes\fR(5) for descriptions of the following attributes:
 226 .sp
 227
 228 .sp
 229 .TS
 230 box;
 231 c | c
 232 l | l .
 233 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 234 _
 235 Interface Stability     Committed
 236 _
 237 MT-Level        Async-Signal-Safe
 238 _
 239 Standard        See \fBstandards\fR(5).
 240 .TE
 241
 242 .SH SEE ALSO
 243 .sp
 244 .LP
 245 \fBIntro\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBpause\fR(2),
 246 \fBsigaction\fR(2), \fBptrace\fR(3C), \fBsignal\fR(3C), \fBsiginfo.h\fR(3HEAD),
 247 \fBwait\fR(3C), \fBwait.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5)