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 .In sys/time.h
  48 .In sys/resource.h
  49 .Ft pid_t
  50 .Fn waitpid "pid_t wpid" "int *status" "int options"
  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 .Pp
  70 The
  71 .Fn wait4
  72 system call provides a more general interface for programs
  73 that need to wait for certain child processes,
  74 that need resource utilization statistics accumulated by child processes,
  75 or that require options.
  76 The other wait functions are implemented using
  77 .Fn wait4 .
  78 .Pp
  79 The
  80 .Fa wpid
  81 argument specifies the set of child processes for which to wait.
  82 If
  83 .Fa wpid
  84 is -1, the call waits for any child process.
  85 If
  86 .Fa wpid
  87 is 0,
  88 the call waits for any child process in the process group of the caller.
  89 If
  90 .Fa wpid
  91 is greater than zero, the call waits for the process with process id
  92 .Fa wpid .
  93 If
  94 .Fa wpid
  95 is less than -1, the call waits for any process whose process group id
  96 equals the absolute value of
  97 .Fa wpid .
  98 .Pp
  99 The
 100 .Fa status
 101 argument is defined below.
 102 .Pp
 103 The
 104 .Fa options
 105 argument contains the bitwise OR of any of the following options.
 106 The
 107 .Dv WCONTINUED
 108 option indicates that children of the current process that
 109 have continued from a job control stop, by receiving a
 110 .Dv SIGCONT
 111 signal, should also have their status reported.
 112 The
 113 .Dv WNOHANG
 114 option
 115 is used to indicate that the call should not block if
 116 there are no processes that wish to report status.
 117 If the
 118 .Dv WUNTRACED
 119 option is set,
 120 children of the current process that are stopped
 121 due to a
 122 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 123 or
 124 .Dv SIGSTOP
 125 signal also have their status reported.
 126 The
 127 .Dv WSTOPPED
 128 option is an alias for
 129 .Dv WUNTRACED .
 130 The
 131 .Dv WNOWAIT
 132 option keeps the process whose status is returned in a waitable state.
 133 The process may be waited for again after this call completes.
 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 or continued 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 function 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 wpid
 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 WIFCONTINUED status
 170 True if the process has not terminated, and
 171 has continued after a job control stop.
 172 This macro can be true only if the wait call specified the
 173 .Dv WCONTINUED
 174 option).
 175 .It Fn WIFEXITED status
 176 True if the process terminated normally by a call to
 177 .Xr _exit 2
 178 or
 179 .Xr exit 3 .
 180 .It Fn WIFSIGNALED status
 181 True if the process terminated due to receipt of a signal.
 182 .It Fn WIFSTOPPED status
 183 True if the process has not terminated, but has stopped and can be restarted.
 184 This macro can be true only if the wait call specified the
 185 .Dv WUNTRACED
 186 option
 187 or if the child process is being traced (see
 188 .Xr ptrace 2 ) .
 189 .El
 190 .Pp
 191 Depending on the values of those macros, the following macros
 192 produce the remaining status information about the child process:
 193 .Bl -tag -width Ds
 194 .It Fn WEXITSTATUS status
 195 If
 196 .Fn WIFEXITED status
 197 is true, evaluates to the low-order 8 bits
 198 of the argument passed to
 199 .Xr _exit 2
 200 or
 201 .Xr exit 3
 202 by the child.
 203 .It Fn WTERMSIG status
 204 If
 205 .Fn WIFSIGNALED status
 206 is true, evaluates to the number of the signal
 207 that caused the termination of the process.
 208 .It Fn WCOREDUMP status
 209 If
 210 .Fn WIFSIGNALED status
 211 is true, evaluates as true if the termination
 212 of the process was accompanied by the creation of a core file
 213 containing an image of the process when the signal was received.
 214 .It Fn WSTOPSIG status
 215 If
 216 .Fn WIFSTOPPED status
 217 is true, evaluates to the number of the signal
 218 that caused the process to stop.
 219 .El
 220 .Sh NOTES
 221 See
 222 .Xr sigaction 2
 223 for a list of termination signals.
 224 A status of 0 indicates normal termination.
 225 .Pp
 226 If a parent process terminates without
 227 waiting for all of its child processes to terminate,
 228 the remaining child processes are assigned the parent
 229 process 1 ID (the init process ID).
 230 .Pp
 231 If a signal is caught while any of the
 232 .Fn wait
 233 calls are pending,
 234 the call may be interrupted or restarted when the signal-catching routine
 235 returns,
 236 depending on the options in effect for the signal;
 237 see discussion of
 238 .Dv SA_RESTART
 239 in
 240 .Xr sigaction 2 .
 241 .Pp
 242 The implementation queues one
 243 .Dv SIGCHLD
 244 signal for each child process whose
 245 status has changed, if
 246 .Fn wait
 247 returns because the status of a child process is available, the pending
 248 SIGCHLD signal associated with the process ID of the child process will
 249 be discarded.
 250 Any other pending
 251 .Dv SIGCHLD
 252 signals remain pending.
 253 .Pp
 254 If
 255 .Dv SIGCHLD
 256 is blocked,
 257 .Fn wait
 258 returns because the status of a child process is available, the pending
 259 .Dv SIGCHLD
 260 signal will be cleared unless another status of the child process
 261 is available.
 262 .Sh RETURN VALUES
 263 If
 264 .Fn wait
 265 returns due to a stopped, continued,
 266 or terminated child process, the process ID of the child
 267 is returned to the calling process.
 268 Otherwise, a value of \-1
 269 is returned and
 270 .Va errno
 271 is set to indicate the error.
 272 .Pp
 273 If
 274 .Fn wait4 ,
 275 .Fn wait3 ,
 276 or
 277 .Fn waitpid
 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 If there are no children not previously awaited,
 282 -1 is returned with
 283 .Va errno
 284 set to
 285 .Er ECHILD .
 286 Otherwise, if
 287 .Dv WNOHANG
 288 is specified and there are
 289 no stopped, continued or exited children,
 290 0 is returned.
 291 If an error is detected or a caught signal aborts the call,
 292 a value of -1
 293 is returned and
 294 .Va errno
 295 is set to indicate the error.
 296 .Sh ERRORS
 297 The
 298 .Fn wait
 299 function
 300 will fail and return immediately if:
 301 .Bl -tag -width Er
 302 .It Bq Er ECHILD
 303 The calling process has no existing unwaited-for
 304 child processes.
 305 .It Bq Er ECHILD
 306 No status from the terminated child process is available
 307 because the calling process has asked the system to discard
 308 such status by ignoring the signal
 309 .Dv SIGCHLD
 310 or setting the flag
 311 .Dv SA_NOCLDWAIT
 312 for that signal.
 313 .It Bq Er EFAULT
 314 The
 315 .Fa status
 316 or
 317 .Fa rusage
 318 argument points to an illegal address.
 319 (May not be detected before exit of a child process.)
 320 .It Bq Er EINTR
 321 The call was interrupted by a caught signal,
 322 or the signal did not have the
 323 .Dv SA_RESTART
 324 flag set.
 325 .El
 326 .Sh SEE ALSO
 327 .Xr _exit 2 ,
 328 .Xr ptrace 2 ,
 329 .Xr sigaction 2 ,
 330 .Xr exit 3 ,
 331 .Xr siginfo 3
 332 .Sh STANDARDS
 333 The
 334 .Fn wait
 335 and
 336 .Fn waitpid
 337 functions are defined by POSIX;
 338 .Fn wait4
 339 and
 340 .Fn wait3
 341 are not specified by POSIX.
 342 The
 343 .Fn WCOREDUMP
 344 macro
 345 and the ability to restart a pending
 346 .Fn wait
 347 call are extensions to the POSIX interface.
 348 .Sh HISTORY
 349 The
 350 .Fn wait
 351 function appeared in
 352 .At v6 .