src/lib/libc/sys/wait.2

   1 .\"     $OpenBSD: wait.2,v 1.21 2007/05/31 19:19:34 jmc Exp $
   2 .\"     $NetBSD: wait.2,v 1.6 1995/02/27 12:39:37 cgd Exp $
   3 .\"
   4 .\" Copyright (c) 1980, 1991, 1993, 1994
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)wait.2      8.2 (Berkeley) 4/19/94
  32 .\"
  33 .Dd $Mdocdate: May 31 2007 $
  34 .Dt WAIT 2
  35 .Os
  36 .Sh NAME
  37 .Nm wait ,
  38 .Nm waitpid ,
  39 .Nm wait4 ,
  40 .Nm wait3
  41 .Nd wait for process termination
  42 .Sh SYNOPSIS
  43 .Fd #include <sys/types.h>
  44 .Fd #include <sys/wait.h>
  45 .Ft pid_t
  46 .Fn wait "int *status"
  47 .Ft pid_t
  48 .Fn waitpid "pid_t wpid" "int *status" "int options"
  49 .Fd #include <sys/time.h>
  50 .Fd #include <sys/resource.h>
  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, the
  65 .Fa status
  66 area, if non-zero, is filled in with termination information about the
  67 process that exited (see below).
  68 .Pp
  69 The
  70 .Fn wait4
  71 call provides a more general interface for programs
  72 that need to wait for certain child processes,
  73 that need resource utilization statistics accumulated by child processes,
  74 or that require options.
  75 The other wait functions are implemented using
  76 .Fn wait4 .
  77 .Pp
  78 The
  79 .Fa wpid
  80 parameter specifies the set of child processes for which to wait.
  81 The following symbolic constants are currently defined in
  82 .Aq Pa sys/wait.h :
  83 .Bd -unfilled -offset indent
  84 #define WAIT_ANY        (-1)    /* any process */
  85 #define WAIT_MYPGRP     0       /* any process in my process group */
  86 .Ed
  87 .Pp
  88 If
  89 .Fa wpid
  90 is set to
  91 .Dv WAIT_ANY ,
  92 the call waits for any child process.
  93 If
  94 .Fa wpid
  95 is set to
  96 .Dv WAIT_MYPGRP ,
  97 the call waits for any child process in the process group of the caller.
  98 If
  99 .Fa wpid
 100 is greater than zero, the call waits for the process with process ID
 101 .Fa wpid .
 102 If
 103 .Fa wpid
 104 is less than \-1, the call waits for any process whose process group ID
 105 equals the absolute value of
 106 .Fa wpid .
 107 .Pp
 108 The
 109 .Fa status
 110 parameter is defined below.
 111 The
 112 .Fa options
 113 parameter contains the bitwise
 114 .Tn OR
 115 of any of the following options:
 116 .Bl -tag -width "WCONTINUED"
 117 .It Dv WCONTINUED
 118 Causes status to be reported for stopped child processes that have been
 119 continued by receipt of a
 120 .Dv SIGCONT
 121 signal.
 122 .It Dv WNOHANG
 123 Indicates that the call should not block if there are no processes that wish
 124 to report status.
 125 .It Dv WUNTRACED
 126 If set, children of the current process that are stopped due to a
 127 .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
 128 or
 129 .Dv SIGSTOP
 130 signal also have their status reported.
 131 .El
 132 .Pp
 133 If
 134 .Fa rusage
 135 is non-zero, a summary of the resources used by the terminated
 136 process and all its
 137 children is returned (this information is currently not available
 138 for stopped processes).
 139 .Pp
 140 When the
 141 .Dv WNOHANG
 142 option is specified and no processes wish to report status,
 143 .Fn wait4
 144 returns a process ID of 0.
 145 .Pp
 146 The
 147 .Fn waitpid
 148 call is identical to
 149 .Fn wait4
 150 with an
 151 .Fa rusage
 152 value of zero.
 153 The older
 154 .Fn wait3
 155 call is the same as
 156 .Fn wait4
 157 with a
 158 .Fa wpid
 159 value of \-1.
 160 .Pp
 161 The following macros may be used to test the manner of exit of the process.
 162 One of the first three macros will evaluate to a non-zero (true) value:
 163 .Bl -tag -width Ds
 164 .It Fn WIFCONTINUED status
 165 True if the process has not terminated, and has continued after a job
 166 control stop.
 167 This macro can be true only if the wait call specified the
 168 .Dv WCONTINUED
 169 option.
 170 .It Fn WIFEXITED status
 171 True if the process terminated normally by a call to
 172 .Xr _exit 2
 173 or
 174 .Xr exit 3 .
 175 .It Fn WIFSIGNALED status
 176 True if the process terminated due to receipt of a signal.
 177 .It Fn WIFSTOPPED status
 178 True if the process has not terminated, but has stopped and can be restarted.
 179 This macro can be true only if the wait call specified the
 180 .Dv WUNTRACED
 181 option or if the child process is being traced (see
 182 .Xr ptrace 2 ) .
 183 .El
 184 .Pp
 185 Depending on the values of those macros, the following macros
 186 produce the remaining status information about the child process:
 187 .Bl -tag -width Ds
 188 .It Fn WEXITSTATUS status
 189 If
 190 .Fn WIFEXITED status
 191 is true, evaluates to the low-order 8 bits of the argument passed to
 192 .Xr _exit 2
 193 or
 194 .Xr exit 3
 195 by the child.
 196 .It Fn WTERMSIG status
 197 If
 198 .Fn WIFSIGNALED status
 199 is true, evaluates to the number of the signal
 200 that caused the termination of the process.
 201 .It Fn WCOREDUMP status
 202 If
 203 .Fn WIFSIGNALED status
 204 is true, evaluates as true if the termination
 205 of the process was accompanied by the creation of a core file
 206 containing an image of the process when the signal was received.
 207 .It Fn WSTOPSIG status
 208 If
 209 .Fn WIFSTOPPED status
 210 is true, evaluates to the number of the signal that caused the process
 211 to stop.
 212 .El
 213 .Sh NOTES
 214 See
 215 .Xr sigaction 2
 216 for a list of termination signals.
 217 A status of 0 indicates normal termination.
 218 .Pp
 219 If a parent process terminates without
 220 waiting for all of its child processes to terminate,
 221 the remaining child processes are assigned the parent
 222 process 1 ID (the init process ID).
 223 .Pp
 224 If a signal is caught while any of the
 225 .Fn wait
 226 calls is pending, the call may be interrupted or restarted when the
 227 signal-catching routine returns, depending on the options in effect
 228 for the signal; for further information, see
 229 .Xr siginterrupt 3 .
 230 .Sh RETURN VALUES
 231 If
 232 .Fn wait
 233 returns due to a stopped
 234 or terminated child process, the process ID of the child
 235 is returned to the calling process.
 236 Otherwise, a value of \-1 is returned and
 237 .Va errno
 238 is set to indicate the error.
 239 .Pp
 240 If
 241 .Fn wait4 ,
 242 .Fn wait3
 243 or
 244 .Fn waitpid
 245 returns due to a stopped or terminated child process, the process ID
 246 of the child is returned to the calling process.
 247 If there are no children not previously awaited, \-1 is returned with
 248 .Va errno
 249 set to
 250 .Bq Er ECHILD .
 251 Otherwise, if
 252 .Dv WNOHANG
 253 is specified and there are no stopped or exited children, 0 is returned.
 254 If an error is detected or a caught signal aborts the call, a value of \-1
 255 is returned and
 256 .Va errno
 257 is set to indicate the error.
 258 .Sh ERRORS
 259 .Fn wait
 260 will fail and return immediately if:
 261 .Bl -tag -width Er
 262 .It Bq Er ECHILD
 263 The calling process has no existing unwaited-for child processes.
 264 .It Bq Er EFAULT
 265 The
 266 .Fa status
 267 or
 268 .Fa rusage
 269 arguments point to an illegal address.
 270 (May not be detected before exit of a child process.)
 271 .It Bq Er EINTR
 272 The call was interrupted by a caught signal, or the signal did not have the
 273 .Dv SA_RESTART
 274 flag set.
 275 .It Bq Er EINVAL
 276 Invalid or undefined flags were passed in the
 277 .Fa options
 278 argument.
 279 .El
 280 .Sh SEE ALSO
 281 .Xr _exit 2 ,
 282 .Xr sigaction 2 ,
 283 .Xr exit 3
 284 .Sh STANDARDS
 285 The
 286 .Fn wait
 287 and
 288 .Fn waitpid
 289 functions are defined by POSIX;
 290 .Fn wait4
 291 and
 292 .Fn wait3
 293 are not specified by POSIX.
 294 The
 295 .Fn WCOREDUMP
 296 macro and the ability to restart a pending
 297 .Fn wait
 298 call are extensions to the POSIX interface.
 299 .Sh HISTORY
 300 A
 301 .Fn wait
 302 function call appeared in
 303 .At v2 .