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