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