1.\" $NetBSD: wait.2,v 1.16 2001/09/16 02:13:32 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 <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/resource.h> 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: 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. If 124.Dv WALTSIG 125is not specified, the call will wait only for processes that 126are configured to post 127.Dv SIGCHLD . 128.It Dv __WCLONE 129This is an alias for 130.Dv WALTSIG . 131It is provided for compatibility with the Linux 132.Xr clone 2 133API. 134.It Dv WALLSIG 135If this option is specified, the call will wait for all children regardless 136of what exit signal they post. 137.It Dv __WALL 138This is an alias for 139.Dv WALLSIG . 140It is provided for compatibility with the Linux 141.Xr clone 2 142API . 143.El 144.Pp 145If 146.Fa rusage 147is non-zero, a summary of the resources used by the terminated 148process and all its 149children is returned (this information is currently not available 150for stopped processes). 151.Pp 152When the 153.Dv WNOHANG 154option is specified and no processes 155wish to report status, 156.Fn wait4 157returns a 158process id 159of 0. 160.Pp 161The 162.Fn waitpid 163call is identical to 164.Fn wait4 165with an 166.Fa rusage 167value of zero. 168The older 169.Fn wait3 170call is the same as 171.Fn wait4 172with a 173.Fa wpid 174value of -1. 175.Pp 176The following macros may be used to test the manner of exit of the process. 177One of the first three macros will evaluate to a non-zero (true) value: 178.Bl -tag -width Ds 179.It Fn WIFEXITED status 180True if the process terminated normally by a call to 181.Xr _exit 2 182or 183.Xr exit 3 . 184.It Fn WIFSIGNALED status 185True if the process terminated due to receipt of a signal. 186.It Fn WIFSTOPPED status 187True if the process has not terminated, but has stopped and can be restarted. 188This macro can be true only if the wait call specified the 189.Dv WUNTRACED 190option 191or if the child process is being traced (see 192.Xr ptrace 2 ) . 193.El 194.Pp 195Depending on the values of those macros, the following macros 196produce the remaining status information about the child process: 197.Bl -tag -width Ds 198.It Fn WEXITSTATUS status 199If 200.Fn WIFEXITED status 201is true, evaluates to the low-order 8 bits 202of the argument passed to 203.Xr _exit 2 204or 205.Xr exit 3 206by the child. 207.It Fn WTERMSIG status 208If 209.Fn WIFSIGNALED status 210is true, evaluates to the number of the signal 211that caused the termination of the process. 212.It Fn WCOREDUMP status 213If 214.Fn WIFSIGNALED status 215is true, evaluates as true if the termination 216of the process was accompanied by the creation of a core file 217containing an image of the process when the signal was received. 218.It Fn WSTOPSIG status 219If 220.Fn WIFSTOPPED status 221is true, evaluates to the number of the signal 222that caused the process to stop. 223.El 224.Sh NOTES 225See 226.Xr sigaction 2 227for a list of termination signals. 228A status of 0 indicates normal termination. 229.Pp 230If a parent process terminates without 231waiting for all of its child processes to terminate, 232the remaining child processes are assigned the parent 233process 1 ID (the init process ID). 234.Pp 235If a signal is caught while any of the 236.Fn wait 237calls is pending, 238the call may be interrupted or restarted when the signal-catching routine 239returns, 240depending on the options in effect for the signal; 241see 242.Xr intro 2 , 243System call restart. 244.Sh RETURN VALUES 245If 246.Fn wait 247returns due to a stopped 248or terminated child process, the process ID of the child 249is returned to the calling process. Otherwise, a value of -1 250is returned and 251.Va errno 252is set to indicate the error. 253.Pp 254If 255.Fn wait4 , 256.Fn wait3 257or 258.Fn waitpid 259returns due to a stopped 260or terminated child process, the process ID of the child 261is returned to the calling process. 262If there are no children not previously awaited, 263-1 is returned with 264.Va errno 265set to 266.Bq Er ECHILD . 267Otherwise, if 268.Dv WNOHANG 269is specified and there are 270no stopped or exited children, 2710 is returned. 272If an error is detected or a caught signal aborts the call, 273a value of -1 274is returned and 275.Va errno 276is set to indicate the error. 277.Sh ERRORS 278.Fn wait 279will fail and return immediately if: 280.Bl -tag -width Er 281.It Bq Er ECHILD 282The calling process has no existing unwaited-for 283child processes. 284.It Bq Er EFAULT 285The 286.Fa status 287or 288.Fa rusage 289arguments point to an illegal address. 290(May not be detected before exit of a child process.) 291.It Bq Er EINTR 292The call was interrupted by a caught signal, 293or the signal did not have the 294.Dv SA_RESTART 295flag set. 296.El 297.Pp 298In addition, 299.Fn wait3 , 300.Fn wait4 , 301and 302.Fn waitpid 303will fail and return immediately if: 304.Bl -tag -width Er 305.It Bq Er EINVAL 306An invalid value was specified for 307.Fa options . 308.El 309.Sh SEE ALSO 310.Xr _exit 2 , 311.Xr sigaction 2 312.Sh STANDARDS 313The 314.Fn wait 315and 316.Fn waitpid 317functions conform to 318.St -p1003.1-90 ; 319the 320.Fn wait3 321function conforms to 322.St -xpg4 ; 323.Fn wait4 324is an extension. 325The 326.Fn WCOREDUMP 327macro 328and the ability to restart a pending 329.Fn wait 330call are extensions to the POSIX interface. 331.Sh HISTORY 332A 333.Fn wait 334function call appeared in 335.At v6 . 336