1.\" $NetBSD: wait.2,v 1.6 1995/02/27 12:39:37 cgd 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 BSD 4 39.Sh NAME 40.Nm wait , 41.Nm wait3 , 42.Nm wait4 , 43.Nm waitpid 44.Nd wait for process termination 45.Sh SYNOPSIS 46.Fd #include <sys/wait.h> 47.Ft pid_t 48.Fo wait 49.Fa "int *stat_loc" 50.Fc 51.Ft pid_t 52.Fo wait3 53.Fa "int *stat_loc" 54.Fa "int options" 55.Fa "struct rusage *rusage" 56.Fc 57.Ft pid_t 58.Fo wait4 59.Fa "pid_t pid" 60.Fa "int *stat_loc" 61.Fa "int options" 62.Fa "struct rusage *rusage" 63.Fc 64.Ft pid_t 65.Fo waitpid 66.Fa "pid_t pid" 67.Fa "int *stat_loc" 68.Fa "int options" 69.Fc 70.Sh DESCRIPTION 71The 72.Fn wait 73function suspends execution of its calling process until 74.Fa stat_loc 75information is available for a terminated child process, 76or a signal is received. 77On return from a successful 78.Fn wait 79call, 80the 81.Fa stat_loc 82area contains termination information about the process that exited 83as defined below. 84.Pp 85The 86.Fn wait4 87call provides a more general interface for programs 88that need to wait for certain child processes, 89that need resource utilization statistics accumulated by child processes, 90or that require options. 91The other wait functions are implemented using 92.Fn wait4 . 93.Pp 94The 95.Fa pid 96parameter specifies the set of child processes for which to wait. 97If 98.Fa pid 99is -1, the call waits for any child process. 100If 101.Fa pid 102is 0, 103the call waits for any child process in the process group of the caller. 104If 105.Fa pid 106is greater than zero, the call waits for the process with process id 107.Fa pid . 108If 109.Fa pid 110is less than -1, the call waits for any process whose process group id 111equals the absolute value of 112.Fa pid . 113.Pp 114The 115.Fa stat_loc 116parameter is defined below. The 117.Fa options 118parameter contains the bitwise OR of any of the following options. 119The 120.Dv WNOHANG 121option 122is used to indicate that the call should not block if 123there are no processes that wish to report status. 124If the 125.Dv WUNTRACED 126option is set, 127children of the current process that are stopped 128due to a 129.Dv SIGTTIN , SIGTTOU , SIGTSTP , 130or 131.Dv SIGSTOP 132signal also have 133their status reported. 134.Pp 135If 136.Fa rusage 137is non-zero, a summary of the resources used by the terminated 138process and all its 139children is returned (this information is currently not available 140for stopped processes). 141.Pp 142When the 143.Dv WNOHANG 144option is specified and no processes 145wish to report status, 146.Fn wait4 147returns a 148process id 149of 0. 150.Pp 151The 152.Fn waitpid 153call is identical to 154.Fn wait4 155with an 156.Fa rusage 157value of zero. 158The older 159.Fn wait3 160call is the same as 161.Fn wait4 162with a 163.Fa pid 164value of -1. 165.Pp 166The following macros may be used to test the manner of exit of the process. 167One of the first three macros will evaluate to a non-zero (true) value: 168.Bl -tag -width Ds 169.It Fn WIFEXITED status 170True if the process terminated normally by a call to 171.Xr _exit 2 172or 173.Xr exit 3 . 174.It Fn WIFSIGNALED status 175True if the process terminated due to receipt of a signal. 176.It Fn WIFSTOPPED status 177True if the process has not terminated, but has stopped and can be restarted. 178This macro can be true only if the wait call specified the 179.Dv WUNTRACED 180option 181or 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 192of the argument passed to 193.Xr _exit 2 194or 195.Xr exit 3 196by the child. 197.It Fn WTERMSIG status 198If 199.Fn WIFSIGNALED status 200is true, evaluates to the number of the signal 201that caused the termination of the process. 202.It Fn WCOREDUMP status 203If 204.Fn WIFSIGNALED status 205is true, evaluates as true if the termination 206of the process was accompanied by the creation of a core file 207containing an image of the process when the signal was received. 208.It Fn WSTOPSIG status 209If 210.Fn WIFSTOPPED status 211is true, evaluates to the number of the signal 212that caused the process to stop. 213.El 214.Sh NOTES 215See 216.Xr sigaction 2 217for a list of termination signals. 218A status of 0 indicates normal termination. 219.Pp 220If a parent process terminates without 221waiting for all of its child processes to terminate, 222the remaining child processes are assigned the parent 223process 1 ID (the init process ID). 224.Pp 225If a signal is caught while any of the 226.Fn wait 227calls is pending, 228the call may be interrupted or restarted when the signal-catching routine 229returns, 230depending on the options in effect for the signal; 231see 232.Xr intro 2 , 233System call restart. 234.Sh RETURN VALUES 235If 236.Fn wait 237returns due to a stopped 238or terminated child process, the process ID of the child 239is returned to the calling process. Otherwise, a value of -1 240is returned and 241.Va errno 242is set to indicate the error. 243.Pp 244If 245.Fn wait3 , 246.Fn wait4 , 247or 248.Fn waitpid 249returns due to a stopped 250or terminated child process, the process ID of the child 251is returned to the calling process. 252If there are no children not previously awaited, 253-1 is returned with 254.Va errno 255set to 256.Bq Er ECHILD . 257Otherwise, if 258.Dv WNOHANG 259is specified and there are 260no stopped or exited children, 2610 is returned. 262If an error is detected or a caught signal aborts the call, 263a value of -1 264is returned and 265.Va errno 266is set to indicate the error. 267.Sh ERRORS 268The 269.Fn wait 270system call will fail and return immediately if: 271.Bl -tag -width Er 272.\" =========== 273.It Bq Er ECHILD 274The calling process has no existing unwaited-for child processes. 275.\" =========== 276.It Bq Er EFAULT 277The 278.Fa status 279or 280.Fa rusage 281argument points to an illegal address 282(may not be detected before the exit of a child process). 283.\" =========== 284.It Bq Er EINVAL 285Invalid or undefined flags are passed in the 286.Fa options 287argument. 288.El 289.Pp 290The 291.Fn wait3 292and 293.Fn waitpid 294calls will fail and return immediately if: 295.Bl -tag -width Er 296.\" =========== 297.It Bq Er ECHILD 298The process specified by 299.Fa pid 300does not exist or is not a child of the calling process, 301or the process group specified by 302.Fa pid 303does not exist or does not have any member process 304that is a child of the calling process. 305.El 306.Pp 307The 308.Fn waitpid 309call will fail and return immediately if: 310.Bl -tag -width Er 311.\" =========== 312.It Bq Er EINVAL 313The options argument is not valid. 314.El 315.Pp 316Any of these calls will fail and return immediately if: 317.Bl -tag -width Er 318.\" =========== 319.It Bq Er EINTR 320The call is interrupted by a caught signal 321or the signal does not have the 322.Dv SA_RESTART 323flag set. 324.El 325.Sh STANDARDS 326The 327.Fn wait 328and 329.Fn waitpid 330functions are defined by POSIX; 331.Fn wait3 332and 333.Fn wait4 334are not specified by POSIX. 335The 336.Fn WCOREDUMP 337macro 338and the ability to restart a pending 339.Fn wait 340call are extensions to the POSIX interface. 341.Sh LEGACY SYNOPSIS 342.Fd #include <sys/types.h> 343.Fd #include <sys/wait.h> 344.Pp 345The include file 346.In sys/types.h 347is necessary. 348.Sh SEE ALSO 349.Xr sigaction 2 , 350.Xr exit 3 , 351.Xr compat 5 352.Sh HISTORY 353A 354.Fn wait 355function call appeared in 356.At v6 . 357