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