lib/libcr/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: src/lib/libc/sys/wait.2,v 1.6.2.6 2001/12/14 18:34:02 ru Exp $
  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 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 parameter 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 parameter is defined below.  The
 106 .Fa options
 107 parameter contains the bitwise OR of any of the following options.
 108 The
 109 .Dv WNOHANG
 110 option
 111 is used to indicate that the call should not block if
 112 there are no processes that wish to report status.
 113 If the
 114 .Dv WUNTRACED
 115 option is set,
 116 children of the current process that are stopped
 117 due to a
 118 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 119 or
 120 .Dv SIGSTOP
 121 signal also have
 122 their status reported.
 123 .Pp
 124 If
 125 .Fa rusage
 126 is non-zero, a summary of the resources used by the terminated
 127 process and all its
 128 children is returned (this information is currently not available
 129 for stopped processes).
 130 .Pp
 131 When the
 132 .Dv WNOHANG
 133 option is specified and no processes
 134 wish to report status,
 135 .Fn wait4
 136 returns a
 137 process id
 138 of 0.
 139 .Pp
 140 The
 141 .Fn waitpid
 142 call is identical to
 143 .Fn wait4
 144 with an
 145 .Fa rusage
 146 value of zero.
 147 The older
 148 .Fn wait3
 149 call is the same as
 150 .Fn wait4
 151 with a
 152 .Fa wpid
 153 value of -1.
 154 .Pp
 155 The following macros may be used to test the manner of exit of the process.
 156 One of the first three macros will evaluate to a non-zero (true) value:
 157 .Bl -tag -width Ds
 158 .It Fn WIFEXITED status
 159 True if the process terminated normally by a call to
 160 .Xr _exit 2
 161 or
 162 .Xr exit 3 .
 163 .It Fn WIFSIGNALED status
 164 True if the process terminated due to receipt of a signal.
 165 .It Fn WIFSTOPPED status
 166 True if the process has not terminated, but has stopped and can be restarted.
 167 This macro can be true only if the wait call specified the
 168 .Dv WUNTRACED
 169 option
 170 or if the child process is being traced (see
 171 .Xr ptrace 2 ) .
 172 .El
 173 .Pp
 174 Depending on the values of those macros, the following macros
 175 produce the remaining status information about the child process:
 176 .Bl -tag -width Ds
 177 .It Fn WEXITSTATUS status
 178 If
 179 .Fn WIFEXITED status
 180 is true, evaluates to the low-order 8 bits
 181 of the argument passed to
 182 .Xr _exit 2
 183 or
 184 .Xr exit 3
 185 by the child.
 186 .It Fn WTERMSIG status
 187 If
 188 .Fn WIFSIGNALED status
 189 is true, evaluates to the number of the signal
 190 that caused the termination of the process.
 191 .It Fn WCOREDUMP status
 192 If
 193 .Fn WIFSIGNALED status
 194 is true, evaluates as true if the termination
 195 of the process was accompanied by the creation of a core file
 196 containing an image of the process when the signal was received.
 197 .It Fn WSTOPSIG status
 198 If
 199 .Fn WIFSTOPPED status
 200 is true, evaluates to the number of the signal
 201 that caused the process to stop.
 202 .El
 203 .Sh NOTES
 204 See
 205 .Xr sigaction 2
 206 for a list of termination signals.
 207 A status of 0 indicates normal termination.
 208 .Pp
 209 If a parent process terminates without
 210 waiting for all of its child processes to terminate,
 211 the remaining child processes are assigned the parent
 212 process 1 ID (the init process ID).
 213 .Pp
 214 If a signal is caught while any of the
 215 .Fn wait
 216 calls are pending,
 217 the call may be interrupted or restarted when the signal-catching routine
 218 returns,
 219 depending on the options in effect for the signal;
 220 see
 221 .Xr intro 2 ,
 222 System call restart.
 223 .Sh RETURN VALUES
 224 If
 225 .Fn wait
 226 returns due to a stopped
 227 or terminated child process, the process ID of the child
 228 is returned to the calling process.  Otherwise, a value of -1
 229 is returned and
 230 .Va errno
 231 is set to indicate the error.
 232 .Pp
 233 If
 234 .Fn wait4 ,
 235 .Fn wait3 ,
 236 or
 237 .Fn waitpid
 238 returns due to a stopped
 239 or terminated child process, the process ID of the child
 240 is returned to the calling process.
 241 If there are no children not previously awaited,
 242 -1 is returned with
 243 .Va errno
 244 set to
 245 .Er ECHILD .
 246 Otherwise, if
 247 .Dv WNOHANG
 248 is specified and there are
 249 no stopped or exited children,
 250 0 is returned.
 251 If an error is detected or a caught signal aborts the call,
 252 a value of -1
 253 is returned and
 254 .Va errno
 255 is set to indicate the error.
 256 .Sh ERRORS
 257 .Fn Wait
 258 will fail and return immediately if:
 259 .Bl -tag -width Er
 260 .It Bq Er ECHILD
 261 The calling process has no existing unwaited-for
 262 child processes.
 263 .It Bq Er EFAULT
 264 The
 265 .Fa status
 266 or
 267 .Fa rusage
 268 arguments point to an illegal address.
 269 (May not be detected before exit of a child process.)
 270 .It Bq Er EINTR
 271 The call was interrupted by a caught signal,
 272 or the signal did not have the
 273 .Dv SA_RESTART
 274 flag set.
 275 .El
 276 .Sh STANDARDS
 277 The
 278 .Fn wait
 279 and
 280 .Fn waitpid
 281 functions are defined by POSIX;
 282 .Fn wait4
 283 and
 284 .Fn wait3
 285 are not specified by POSIX.
 286 The
 287 .Fn WCOREDUMP
 288 macro
 289 and the ability to restart a pending
 290 .Fn wait
 291 call are extensions to the POSIX interface.
 292 .Sh SEE ALSO
 293 .Xr ptrace 2 ,
 294 .Xr sigaction 2 ,
 295 .Xr _exit 2 ,
 296 .Xr exit 3
 297 .Sh HISTORY
 298 A
 299 .Fn wait
 300 function call appeared in
 301 .At v6 .