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