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 .\" 3. 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: src/lib/libc/sys/wait.2,v 1.6.2.6 2001/12/14 18:34:02 ru Exp $
  30 .\" $DragonFly: src/lib/libc/sys/wait.2,v 1.4 2007/08/30 20:58:35 pavalos Exp $
  31 .\"
  32 .Dd August 30, 2007
  33 .Dt WAIT 2
  34 .Os
  35 .Sh NAME
  36 .Nm wait ,
  37 .Nm waitpid ,
  38 .Nm wait4 ,
  39 .Nm wait3
  40 .Nd wait for process termination
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/wait.h
  46 .Ft pid_t
  47 .Fn wait "int *status"
  48 .In sys/time.h
  49 .In sys/resource.h
  50 .Ft pid_t
  51 .Fn waitpid "pid_t wpid" "int *status" "int options"
  52 .Ft pid_t
  53 .Fn wait3 "int *status" "int options" "struct rusage *rusage"
  54 .Ft pid_t
  55 .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn wait
  59 function suspends execution of its calling process until
  60 .Fa status
  61 information is available for a terminated child process,
  62 or a signal is received.
  63 On return from a successful
  64 .Fn wait
  65 call,
  66 the
  67 .Fa status
  68 area contains termination information about the process that exited
  69 as defined below.
  70 .Pp
  71 The
  72 .Fn wait4
  73 call provides a more general interface for programs
  74 that need to wait for certain child processes,
  75 that need resource utilization statistics accumulated by child processes,
  76 or that require options.
  77 The other wait functions are implemented using
  78 .Fn wait4 .
  79 .Pp
  80 The
  81 .Fa wpid
  82 parameter specifies the set of child processes for which to wait.
  83 If
  84 .Fa wpid
  85 is -1, the call waits for any child process.
  86 If
  87 .Fa wpid
  88 is 0,
  89 the call waits for any child process in the process group of the caller.
  90 If
  91 .Fa wpid
  92 is greater than zero, the call waits for the process with process id
  93 .Fa wpid .
  94 If
  95 .Fa wpid
  96 is less than -1, the call waits for any process whose process group id
  97 equals the absolute value of
  98 .Fa wpid .
  99 .Pp
 100 The
 101 .Fa status
 102 parameter is defined below.  The
 103 .Fa options
 104 parameter contains the bitwise OR of any of the following options.
 105 The
 106 .Dv WCONTINUED
 107 option indicates that children of the current process that
 108 have continued from a job control stop, by receiving a
 109 .Dv SIGCONT
 110 signal, should also have their status reported.
 111 The
 112 .Dv WNOHANG
 113 option
 114 is used to indicate that the call should not block if
 115 there are no processes that wish to report status.
 116 If the
 117 .Dv WUNTRACED
 118 option is set,
 119 children of the current process that are stopped
 120 due to a
 121 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 122 or
 123 .Dv SIGSTOP
 124 signal also have
 125 their status reported.
 126 .Pp
 127 If
 128 .Fa rusage
 129 is non-zero, a summary of the resources used by the terminated
 130 process and all its
 131 children is returned (this information is currently not available
 132 for stopped processes).
 133 .Pp
 134 When the
 135 .Dv WNOHANG
 136 option is specified and no processes
 137 wish to report status,
 138 .Fn wait4
 139 returns a
 140 process id
 141 of 0.
 142 .Pp
 143 The
 144 .Fn waitpid
 145 call is identical to
 146 .Fn wait4
 147 with an
 148 .Fa rusage
 149 value of zero.
 150 The older
 151 .Fn wait3
 152 call is the same as
 153 .Fn wait4
 154 with a
 155 .Fa wpid
 156 value of -1.
 157 .Pp
 158 The following macros may be used to test the manner of exit of the process.
 159 One of the first three macros will evaluate to a non-zero (true) value:
 160 .Bl -tag -width Ds
 161 .It Fn WIFEXITED status
 162 True if the process terminated normally by a call to
 163 .Xr _exit 2
 164 or
 165 .Xr exit 3 .
 166 .It Fn WIFSIGNALED status
 167 True if the process terminated due to receipt of a signal.
 168 .It Fn WIFSTOPPED status
 169 True if the process has not terminated, but has stopped and can be restarted.
 170 This macro can be true only if the wait call specified the
 171 .Dv WUNTRACED
 172 option
 173 or if the child process is being traced (see
 174 .Xr ptrace 2 ) .
 175 .El
 176 .Pp
 177 Depending on the values of those macros, the following macros
 178 produce the remaining status information about the child process:
 179 .Bl -tag -width Ds
 180 .It Fn WIFCONTINUED status
 181 True if the process has not terminated, and
 182 has continued after a job control stop.
 183 This macro can be true only if the wait call specified the
 184 .Dv WCONTINUED
 185 option).
 186 .It Fn WEXITSTATUS status
 187 If
 188 .Fn WIFEXITED status
 189 is true, evaluates to the low-order 8 bits
 190 of the argument passed to
 191 .Xr _exit 2
 192 or
 193 .Xr exit 3
 194 by the child.
 195 .It Fn WTERMSIG status
 196 If
 197 .Fn WIFSIGNALED status
 198 is true, evaluates to the number of the signal
 199 that caused the termination of the process.
 200 .It Fn WCOREDUMP status
 201 If
 202 .Fn WIFSIGNALED status
 203 is true, evaluates as true if the termination
 204 of the process was accompanied by the creation of a core file
 205 containing an image of the process when the signal was received.
 206 .It Fn WSTOPSIG status
 207 If
 208 .Fn WIFSTOPPED status
 209 is true, evaluates to the number of the signal
 210 that caused the process to stop.
 211 .El
 212 .Sh NOTES
 213 See
 214 .Xr sigaction 2
 215 for a list of termination signals.
 216 A status of 0 indicates normal termination.
 217 .Pp
 218 If a parent process terminates without
 219 waiting for all of its child processes to terminate,
 220 the remaining child processes are assigned the parent
 221 process 1 ID (the init process ID).
 222 .Pp
 223 If a signal is caught while any of the
 224 .Fn wait
 225 calls are pending,
 226 the call may be interrupted or restarted when the signal-catching routine
 227 returns,
 228 depending on the options in effect for the signal;
 229 see
 230 .Xr intro 2 ,
 231 System call restart.
 232 .Sh RETURN VALUES
 233 If
 234 .Fn wait
 235 returns due to a stopped
 236 or terminated child process, the process ID of the child
 237 is returned to the calling process.  Otherwise, a value of -1
 238 is returned and
 239 .Va errno
 240 is set to indicate the error.
 241 .Pp
 242 If
 243 .Fn wait4 ,
 244 .Fn wait3 ,
 245 or
 246 .Fn waitpid
 247 returns due to a stopped
 248 or terminated child process, the process ID of the child
 249 is returned to the calling process.
 250 If there are no children not previously awaited,
 251 -1 is returned with
 252 .Va errno
 253 set to
 254 .Er ECHILD .
 255 Otherwise, if
 256 .Dv WNOHANG
 257 is specified and there are
 258 no stopped or exited children,
 259 0 is returned.
 260 If an error is detected or a caught signal aborts the call,
 261 a value of -1
 262 is returned and
 263 .Va errno
 264 is set to indicate the error.
 265 .Sh ERRORS
 266 .Fn Wait
 267 will fail and return immediately if:
 268 .Bl -tag -width Er
 269 .It Bq Er ECHILD
 270 The calling process has no existing unwaited-for
 271 child processes.
 272 .It Bq Er EFAULT
 273 The
 274 .Fa status
 275 or
 276 .Fa rusage
 277 arguments point to an illegal address.
 278 (May not be detected before exit of a child process.)
 279 .It Bq Er EINTR
 280 The call was interrupted by a caught signal,
 281 or the signal did not have the
 282 .Dv SA_RESTART
 283 flag set.
 284 .El
 285 .Sh SEE ALSO
 286 .Xr ptrace 2 ,
 287 .Xr sigaction 2 ,
 288 .Xr _exit 2 ,
 289 .Xr exit 3
 290 .Sh STANDARDS
 291 The
 292 .Fn wait
 293 and
 294 .Fn waitpid
 295 functions are defined by POSIX;
 296 .Fn wait4
 297 and
 298 .Fn wait3
 299 are not specified by POSIX.
 300 The
 301 .Fn WCOREDUMP
 302 macro
 303 and the ability to restart a pending
 304 .Fn wait
 305 call are extensions to the POSIX interface.
 306 .Sh HISTORY
 307 A
 308 .Fn wait
 309 function call appeared in
 310 .At v6 .