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