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