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