1.\" $OpenBSD: wait.2,v 1.30 2017/05/01 00:08:31 millert 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 1 2017 $ 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 , 265.Fn waitpid , 266.Fn wait3 , 267and 268.Fn wait4 269will fail and return immediately if: 270.Bl -tag -width Er 271.It Bq Er ECHILD 272The calling process has no existing unwaited-for child processes. 273.It Bq Er ECHILD 274No status from the terminated child process is available 275because the calling process has asked the system to discard 276such status by ignoring the signal 277.Dv SIGCHLD 278or setting the flag 279.Dv SA_NOCLDWAIT 280for that signal. 281.It Bq Er EFAULT 282The 283.Fa status 284or 285.Fa rusage 286arguments point to an illegal address. 287(May not be detected before exit of a child process.) 288.It Bq Er EINTR 289The call was interrupted by a caught signal, or the signal did not have the 290.Dv SA_RESTART 291flag set. 292.El 293.Pp 294.Fn waitpid 295and 296.Fn wait4 297will fail and return immediately if: 298.Bl -tag -width Er 299.It Bq Er ECHILD 300The process specified by the 301.Ar wpid 302argument does not exist or is not a child of the calling process. 303.It Bq Er EINVAL 304Invalid or undefined flags were passed in the 305.Fa options 306argument. 307.El 308.Sh SEE ALSO 309.Xr _exit 2 , 310.Xr sigaction 2 , 311.Xr exit 3 312.Sh STANDARDS 313The 314.Fn wait 315and 316.Fn waitpid 317functions conform to 318.St -p1003.1-2008 . 319.Pp 320.Fn wait4 321and 322.Fn wait3 323are not specified by POSIX. 324The 325.Fn WCOREDUMP 326macro and the ability to restart a pending 327.Fn wait 328call are extensions to that specification. 329.Sh HISTORY 330A 331.Fn wait 332system call first appeared in 333.At v1 . 334The 335.Fa status 336argument is accepted since 337.At v2 . 338A 339.Fn wait3 340system call first appeared in 341.Bx 4 , 342but the final calling convention was only established in 343.Bx 4.2 . 344The 345.Fn wait4 346and 347.Fn waitpid 348function calls first appeared in 349.Bx 4.3 Reno . 350