lib/libcr/sys/wait.2

   1 .\" Copyright (c) 1980, 1991, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)wait.2      8.2 (Berkeley) 4/19/94
  33 .\" $FreeBSD: src/lib/libc/sys/wait.2,v 1.6.2.6 2001/12/14 18:34:02 ru Exp $
  34 .\" $DragonFly: src/lib/libcr/sys/Attic/wait.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd April 19, 1994
  37 .Dt WAIT 2
  38 .Os
  39 .Sh NAME
  40 .Nm wait ,
  41 .Nm waitpid ,
  42 .Nm wait4 ,
  43 .Nm wait3
  44 .Nd wait for process termination
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In sys/wait.h
  50 .Ft pid_t
  51 .Fn wait "int *status"
  52 .In sys/time.h
  53 .In sys/resource.h
  54 .Ft pid_t
  55 .Fn waitpid "pid_t wpid" "int *status" "int options"
  56 .Ft pid_t
  57 .Fn wait3 "int *status" "int options" "struct rusage *rusage"
  58 .Ft pid_t
  59 .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn wait
  63 function suspends execution of its calling process until
  64 .Fa status
  65 information is available for a terminated child process,
  66 or a signal is received.
  67 On return from a successful
  68 .Fn wait
  69 call,
  70 the
  71 .Fa status
  72 area contains termination information about the process that exited
  73 as defined below.
  74 .Pp
  75 The
  76 .Fn wait4
  77 call provides a more general interface for programs
  78 that need to wait for certain child processes,
  79 that need resource utilization statistics accumulated by child processes,
  80 or that require options.
  81 The other wait functions are implemented using
  82 .Fn wait4 .
  83 .Pp
  84 The
  85 .Fa wpid
  86 parameter specifies the set of child processes for which to wait.
  87 If
  88 .Fa wpid
  89 is -1, the call waits for any child process.
  90 If
  91 .Fa wpid
  92 is 0,
  93 the call waits for any child process in the process group of the caller.
  94 If
  95 .Fa wpid
  96 is greater than zero, the call waits for the process with process id
  97 .Fa wpid .
  98 If
  99 .Fa wpid
 100 is less than -1, the call waits for any process whose process group id
 101 equals the absolute value of
 102 .Fa wpid .
 103 .Pp
 104 The
 105 .Fa status
 106 parameter is defined below.  The
 107 .Fa options
 108 parameter contains the bitwise OR of any of the following options.
 109 The
 110 .Dv WNOHANG
 111 option
 112 is used to indicate that the call should not block if
 113 there are no processes that wish to report status.
 114 If the
 115 .Dv WUNTRACED
 116 option is set,
 117 children of the current process that are stopped
 118 due to a
 119 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 120 or
 121 .Dv SIGSTOP
 122 signal also have
 123 their status reported.
 124 .Pp
 125 If
 126 .Fa rusage
 127 is non-zero, a summary of the resources used by the terminated
 128 process and all its
 129 children is returned (this information is currently not available
 130 for stopped processes).
 131 .Pp
 132 When the
 133 .Dv WNOHANG
 134 option is specified and no processes
 135 wish to report status,
 136 .Fn wait4
 137 returns a
 138 process id
 139 of 0.
 140 .Pp
 141 The
 142 .Fn waitpid
 143 call is identical to
 144 .Fn wait4
 145 with an
 146 .Fa rusage
 147 value of zero.
 148 The older
 149 .Fn wait3
 150 call is the same as
 151 .Fn wait4
 152 with a
 153 .Fa wpid
 154 value of -1.
 155 .Pp
 156 The following macros may be used to test the manner of exit of the process.
 157 One of the first three macros will evaluate to a non-zero (true) value:
 158 .Bl -tag -width Ds
 159 .It Fn WIFEXITED status
 160 True if the process terminated normally by a call to
 161 .Xr _exit 2
 162 or
 163 .Xr exit 3 .
 164 .It Fn WIFSIGNALED status
 165 True if the process terminated due to receipt of a signal.
 166 .It Fn WIFSTOPPED status
 167 True if the process has not terminated, but has stopped and can be restarted.
 168 This macro can be true only if the wait call specified the
 169 .Dv WUNTRACED
 170 option
 171 or if the child process is being traced (see
 172 .Xr ptrace 2 ) .
 173 .El
 174 .Pp
 175 Depending on the values of those macros, the following macros
 176 produce the remaining status information about the child process:
 177 .Bl -tag -width Ds
 178 .It Fn WEXITSTATUS status
 179 If
 180 .Fn WIFEXITED status
 181 is true, evaluates to the low-order 8 bits
 182 of the argument passed to
 183 .Xr _exit 2
 184 or
 185 .Xr exit 3
 186 by the child.
 187 .It Fn WTERMSIG status
 188 If
 189 .Fn WIFSIGNALED status
 190 is true, evaluates to the number of the signal
 191 that caused the termination of the process.
 192 .It Fn WCOREDUMP status
 193 If
 194 .Fn WIFSIGNALED status
 195 is true, evaluates as true if the termination
 196 of the process was accompanied by the creation of a core file
 197 containing an image of the process when the signal was received.
 198 .It Fn WSTOPSIG status
 199 If
 200 .Fn WIFSTOPPED status
 201 is true, evaluates to the number of the signal
 202 that caused the process to stop.
 203 .El
 204 .Sh NOTES
 205 See
 206 .Xr sigaction 2
 207 for a list of termination signals.
 208 A status of 0 indicates normal termination.
 209 .Pp
 210 If a parent process terminates without
 211 waiting for all of its child processes to terminate,
 212 the remaining child processes are assigned the parent
 213 process 1 ID (the init process ID).
 214 .Pp
 215 If a signal is caught while any of the
 216 .Fn wait
 217 calls are pending,
 218 the call may be interrupted or restarted when the signal-catching routine
 219 returns,
 220 depending on the options in effect for the signal;
 221 see
 222 .Xr intro 2 ,
 223 System call restart.
 224 .Sh RETURN VALUES
 225 If
 226 .Fn wait
 227 returns due to a stopped
 228 or terminated child process, the process ID of the child
 229 is returned to the calling process.  Otherwise, a value of -1
 230 is returned and
 231 .Va errno
 232 is set to indicate the error.
 233 .Pp
 234 If
 235 .Fn wait4 ,
 236 .Fn wait3 ,
 237 or
 238 .Fn waitpid
 239 returns due to a stopped
 240 or terminated child process, the process ID of the child
 241 is returned to the calling process.
 242 If there are no children not previously awaited,
 243 -1 is returned with
 244 .Va errno
 245 set to
 246 .Er ECHILD .
 247 Otherwise, if
 248 .Dv WNOHANG
 249 is specified and there are
 250 no stopped or exited children,
 251 0 is returned.
 252 If an error is detected or a caught signal aborts the call,
 253 a value of -1
 254 is returned and
 255 .Va errno
 256 is set to indicate the error.
 257 .Sh ERRORS
 258 .Fn Wait
 259 will fail and return immediately if:
 260 .Bl -tag -width Er
 261 .It Bq Er ECHILD
 262 The calling process has no existing unwaited-for
 263 child processes.
 264 .It Bq Er EFAULT
 265 The
 266 .Fa status
 267 or
 268 .Fa rusage
 269 arguments point to an illegal address.
 270 (May not be detected before exit of a child process.)
 271 .It Bq Er EINTR
 272 The call was interrupted by a caught signal,
 273 or the signal did not have the
 274 .Dv SA_RESTART
 275 flag set.
 276 .El
 277 .Sh STANDARDS
 278 The
 279 .Fn wait
 280 and
 281 .Fn waitpid
 282 functions are defined by POSIX;
 283 .Fn wait4
 284 and
 285 .Fn wait3
 286 are not specified by POSIX.
 287 The
 288 .Fn WCOREDUMP
 289 macro
 290 and the ability to restart a pending
 291 .Fn wait
 292 call are extensions to the POSIX interface.
 293 .Sh SEE ALSO
 294 .Xr ptrace 2 ,
 295 .Xr sigaction 2 ,
 296 .Xr _exit 2 ,
 297 .Xr exit 3
 298 .Sh HISTORY
 299 A
 300 .Fn wait
 301 function call appeared in
 302 .At v6 .