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