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