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