bsd/man/man2/wait.2

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