1.\" $NetBSD: wait.2,v 1.13 2001/07/18 19:12:21 thorpej 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 <sys/types.h> 49.Fd #include <sys/wait.h> 50.Ft pid_t 51.Fn wait "int *status" 52.Ft pid_t 53.Fn waitpid "pid_t wpid" "int *status" "int options" 54.Fd #include <sys/time.h> 55.Fd #include <sys/resource.h> 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: 109.Bl -tag -width WUNTRACED 110.It Dv WNOHANG 111This option is used to indicate that the call should not block if 112there are no processes that wish to report status. 113.It Dv WUNTRACED 114If this option is set, children of the current process that are stopped 115due to a 116.Dv SIGTTIN , SIGTTOU , SIGTSTP , 117or 118.Dv SIGSTOP 119signal also have their status reported. 120.It Dv WALTSIG 121If this option is specified, the call will wait only for processes that 122are configured to post a signal other than 123.Dv SIGCHLD 124when they exit. If 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. 178One of the first three macros will evaluate to a non-zero (true) value: 179.Bl -tag -width Ds 180.It Fn WIFEXITED status 181True if the process terminated normally by a call to 182.Xr _exit 2 183or 184.Xr exit 3 . 185.It Fn WIFSIGNALED status 186True if the process terminated due to receipt of a signal. 187.It Fn WIFSTOPPED status 188True if the process has not terminated, but has stopped and can be restarted. 189This macro can be true only if the wait call specified the 190.Dv WUNTRACED 191option 192or if the child process is being traced (see 193.Xr ptrace 2 ) . 194.El 195.Pp 196Depending on the values of those macros, the following macros 197produce the remaining status information about the child process: 198.Bl -tag -width Ds 199.It Fn WEXITSTATUS status 200If 201.Fn WIFEXITED status 202is true, evaluates to the low-order 8 bits 203of the argument passed to 204.Xr _exit 2 205or 206.Xr exit 3 207by the child. 208.It Fn WTERMSIG status 209If 210.Fn WIFSIGNALED status 211is true, evaluates to the number of the signal 212that caused the termination of the process. 213.It Fn WCOREDUMP status 214If 215.Fn WIFSIGNALED status 216is true, evaluates as true if the termination 217of the process was accompanied by the creation of a core file 218containing an image of the process when the signal was received. 219.It Fn WSTOPSIG status 220If 221.Fn WIFSTOPPED status 222is true, evaluates to the number of the signal 223that caused the process to stop. 224.El 225.Sh NOTES 226See 227.Xr sigaction 2 228for a list of termination signals. 229A status of 0 indicates normal termination. 230.Pp 231If a parent process terminates without 232waiting for all of its child processes to terminate, 233the remaining child processes are assigned the parent 234process 1 ID (the init process ID). 235.Pp 236If a signal is caught while any of the 237.Fn wait 238calls is pending, 239the call may be interrupted or restarted when the signal-catching routine 240returns, 241depending on the options in effect for the signal; 242see 243.Xr intro 2 , 244System call restart. 245.Sh RETURN VALUES 246If 247.Fn wait 248returns due to a stopped 249or terminated child process, the process ID of the child 250is returned to the calling process. Otherwise, a value of -1 251is returned and 252.Va errno 253is set to indicate the error. 254.Pp 255If 256.Fn wait4 , 257.Fn wait3 258or 259.Fn waitpid 260returns due to a stopped 261or terminated child process, the process ID of the child 262is returned to the calling process. 263If there are no children not previously awaited, 264-1 is returned with 265.Va errno 266set to 267.Bq Er ECHILD . 268Otherwise, if 269.Dv WNOHANG 270is specified and there are 271no stopped or exited children, 2720 is returned. 273If an error is detected or a caught signal aborts the call, 274a value of -1 275is returned and 276.Va errno 277is set to indicate the error. 278.Sh ERRORS 279.Fn wait 280will fail and return immediately if: 281.Bl -tag -width Er 282.It Bq Er ECHILD 283The calling process has no existing unwaited-for 284child processes. 285.It Bq Er EFAULT 286The 287.Fa status 288or 289.Fa rusage 290arguments point to an illegal address. 291(May not be detected before exit of a child process.) 292.It Bq Er EINTR 293The call was interrupted by a caught signal, 294or the signal did not have the 295.Dv SA_RESTART 296flag set. 297.El 298.Pp 299In addition, 300.Fn wait3 , 301.Fn wait4 , 302and 303.Fn waitpid 304will fail and return immediately if: 305.Bl -tag -width Er 306.It Bq Er EINVAL 307An invalid value was specified for 308.Fa options . 309.El 310.Sh STANDARDS 311The 312.Fn wait 313and 314.Fn waitpid 315functions conform to 316.St -p1003.1-90 ; 317the 318.Fn wait3 319function conforms to 320.St -xpg4 ; 321.Fn wait4 322is an extension. 323The 324.Fn WCOREDUMP 325macro 326and the ability to restart a pending 327.Fn wait 328call are extensions to the POSIX interface. 329.Sh SEE ALSO 330.Xr _exit 2 , 331.Xr sigaction 2 332.Sh HISTORY 333A 334.Fn wait 335function call appeared in 336.At v6 . 337