1.\" Copyright (c) 1980, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)wait.2 8.2 (Berkeley) 4/19/94 29.\" $FreeBSD$ 30.\" 31.Dd December 1, 2017 32.Dt WAIT 2 33.Os 34.Sh NAME 35.Nm wait , 36.Nm waitid , 37.Nm waitpid , 38.Nm wait3 , 39.Nm wait4 , 40.Nm wait6 41.Nd wait for processes to change status 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/wait.h 47.Ft pid_t 48.Fn wait "int *status" 49.Ft pid_t 50.Fn waitpid "pid_t wpid" "int *status" "int options" 51.In signal.h 52.Ft int 53.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options" 54.In sys/time.h 55.In 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.Ft pid_t 61.Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct __wrusage *wrusage" "siginfo_t *infop" 62.Sh DESCRIPTION 63The 64.Fn wait 65function suspends execution of its calling thread until 66.Fa status 67information is available for a child process 68or a signal is received. 69On return from a successful 70.Fn wait 71call, 72the 73.Fa status 74area contains information about the process that reported a status change 75as defined below. 76.Pp 77The 78.Fn wait4 79and 80.Fn wait6 81system calls provide a more general interface for programs 82that need to wait for specific child processes, 83that need resource utilization statistics accumulated by child processes, 84or that require options. 85The other wait functions are implemented using either 86.Fn wait4 87or 88.Fn wait6 . 89.Pp 90The 91.Fn wait6 92function is the most general function in this family and its distinct 93features are: 94.Pp 95All of the desired process statuses to be waited on must be explicitly 96specified in 97.Fa options . 98The 99.Fn wait , 100.Fn waitpid , 101.Fn wait3 , 102and 103.Fn wait4 104functions all implicitly wait for exited and trapped processes, 105but the 106.Fn waitid 107and 108.Fn wait6 109functions require the corresponding 110.Dv WEXITED 111and 112.Dv WTRAPPED 113flags to be explicitly specified. 114This allows waiting for processes which have experienced other 115status changes without having to also handle the exit status from 116terminated processes. 117.Pp 118The 119.Fn wait6 120function accepts a 121.Fa wrusage 122argument which points to a structure defined as: 123.Bd -literal 124struct __wrusage { 125 struct rusage wru_self; 126 struct rusage wru_children; 127}; 128.Ed 129.Pp 130This allows the calling process to collect resource usage statistics 131from both its own child process as well as from its grand children. 132When no resource usage statistics are needed this pointer can be 133.Dv NULL . 134.Pp 135The last argument 136.Fa infop 137must be either 138.Dv NULL 139or a pointer to a 140.Fa siginfo_t 141structure. 142If 143.Pf non- Dv NULL , 144the structure is filled with the same data as for a 145.Dv SIGCHLD 146signal delivered when the process changed state. 147.Pp 148The set of child processes to be queried is specified by the arguments 149.Fa idtype 150and 151.Fa id . 152The separate 153.Fa idtype 154and 155.Fa id 156arguments support many other types of 157identifiers in addition to process IDs and process group IDs. 158.Bl -bullet -offset indent 159.It 160If 161.Fa idtype 162is 163.Dv P_PID , 164.Fn waitid 165and 166.Fn wait6 167wait for the child process with a process ID equal to 168.Dv (pid_t)id . 169.It 170If 171.Fa idtype 172is 173.Dv P_PGID , 174.Fn waitid 175and 176.Fn wait6 177wait for the child process with a process group ID equal to 178.Dv (pid_t)id . 179.It 180If 181.Fa idtype 182is 183.Dv P_ALL , 184.Fn waitid 185and 186.Fn wait6 187wait for any child process and the 188.Dv id 189is ignored. 190.It 191If 192.Fa idtype 193is 194.Dv P_PID 195or 196.Dv P_PGID 197and the 198.Dv id 199is zero, 200.Fn waitid 201and 202.Fn wait6 203wait for any child process in the same process group as the caller. 204.El 205.Pp 206Non-standard identifier types supported by this 207implementation of 208.Fn waitid 209and 210.Fn wait6 211are: 212.Bl -tag -width P_JAILID 213.It Dv P_UID 214Wait for processes whose effective user ID is equal to 215.Dv (uid_t) Fa id . 216.It Dv P_GID 217Wait for processes whose effective group ID is equal to 218.Dv (gid_t) Fa id . 219.It Dv P_SID 220Wait for processes whose session ID is equal to 221.Fa id . 222.\" This is just how sessions work, not sure this needs to be documented here 223If the child process started its own session, 224its session ID will be the same as its process ID. 225Otherwise the session ID of a child process will match the caller's session ID. 226.It Dv P_JAILID 227Waits for processes within a jail whose jail identifier is equal to 228.Fa id . 229.El 230.Pp 231For the 232.Fn waitpid 233and 234.Fn wait4 235functions, the single 236.Fa wpid 237argument specifies the set of child processes for which to wait. 238.Bl -bullet -offset indent 239.It 240If 241.Fa wpid 242is -1, the call waits for any child process. 243.It 244If 245.Fa wpid 246is 0, 247the call waits for any child process in the process group of the caller. 248.It 249If 250.Fa wpid 251is greater than zero, the call waits for the process with process ID 252.Fa wpid . 253.It 254If 255.Fa wpid 256is less than -1, the call waits for any process whose process group ID 257equals the absolute value of 258.Fa wpid . 259.El 260.Pp 261The 262.Fa status 263argument is defined below. 264.Pp 265The 266.Fa options 267argument contains the bitwise OR of any of the following options. 268.Bl -tag -width WCONTINUED 269.It Dv WCONTINUED 270Report the status of selected processes that 271have continued from a job control stop by receiving a 272.Dv SIGCONT 273signal. 274.It Dv WNOHANG 275Do not block when 276there are no processes wishing to report status. 277.It Dv WUNTRACED 278Report the status of selected processes which are stopped due to a 279.Dv SIGTTIN , SIGTTOU , SIGTSTP , 280or 281.Dv SIGSTOP 282signal. 283.It Dv WSTOPPED 284An alias for 285.Dv WUNTRACED . 286.It Dv WTRAPPED 287Report the status of selected processes which are being traced via 288.Xr ptrace 2 289and have trapped or reached a breakpoint. 290This flag is implicitly set for the functions 291.Fn wait , 292.Fn waitpid , 293.Fn wait3 , 294and 295.Fn wait4 . 296.br 297For the 298.Fn waitid 299and 300.Fn wait6 301functions, the flag has to be explicitly included in 302.Fa options 303if status reports from trapped processes are expected. 304.It Dv WEXITED 305Report the status of selected processes which have terminated. 306This flag is implicitly set for the functions 307.Fn wait , 308.Fn waitpid , 309.Fn wait3 , 310and 311.Fn wait4 . 312.br 313For the 314.Fn waitid 315and 316.Fn wait6 317functions, the flag has to be explicitly included in 318.Fa options 319if status reports from terminated processes are expected. 320.It Dv WNOWAIT 321Keep the process whose status is returned in a waitable state. 322The process may be waited for again after this call completes. 323.El 324.sp 325For the 326.Fn waitid 327and 328.Fn wait6 329functions, at least one of the options 330.Dv WEXITED , 331.Dv WUNTRACED , 332.Dv WSTOPPED , 333.Dv WTRAPPED , 334or 335.Dv WCONTINUED 336must be specified. 337Otherwise there will be no events for the call to report. 338To avoid hanging indefinitely in such a case these functions 339return -1 with 340.Dv errno 341set to 342.Dv EINVAL . 343.Pp 344If 345.Fa rusage 346is non-NULL, a summary of the resources used by the terminated 347process and all its children is returned. 348.Pp 349If 350.Fa wrusage 351is non-NULL, separate summaries are returned for the resources used 352by the terminated process and the resources used by all its children. 353.Pp 354If 355.Fa infop 356is non-NULL, a 357.Dv siginfo_t 358structure is returned with the 359.Fa si_signo 360field set to 361.Dv SIGCHLD 362and the 363.Fa si_pid 364field set to the process ID of the process reporting status. 365For the exited process, the 366.Fa si_status 367field of the 368.Dv siginfo_t 369structure contains the full 32 bit exit status passed to 370.Xr _exit 2 ; 371the 372.Fa status 373argument of other calls only returns 8 lowest bits of the exit status. 374.Pp 375When the 376.Dv WNOHANG 377option is specified and no processes 378wish to report status, 379.Fn waitid 380sets the 381.Fa si_signo 382and 383.Fa si_pid 384fields in 385.Fa infop 386to zero. 387Checking these fields is the only way to know if a status change was reported. 388.Pp 389When the 390.Dv WNOHANG 391option is specified and no processes 392wish to report status, 393.Fn wait4 394and 395.Fn wait6 396return a 397process id 398of 0. 399.Pp 400The 401.Fn wait 402call is the same as 403.Fn wait4 404with a 405.Fa wpid 406value of -1, 407with an 408.Fa options 409value of zero, 410and a 411.Fa rusage 412value of 413.Dv NULL . 414The 415.Fn waitpid 416function is identical to 417.Fn wait4 418with an 419.Fa rusage 420value of 421.Dv NULL . 422The older 423.Fn wait3 424call is the same as 425.Fn wait4 426with a 427.Fa wpid 428value of -1. 429The 430.Fn wait4 431function is identical to 432.Fn wait6 433with the flags 434.Dv WEXITED 435and 436.Dv WTRAPPED 437set in 438.Fa options 439and 440.Fa infop 441set to 442.Dv NULL . 443.Pp 444The following macros may be used to test the current status of the process. 445Exactly one of the following four macros will evaluate to a non-zero 446.Pq true 447value: 448.Bl -tag -width Ds 449.It Fn WIFCONTINUED status 450True if the process has not terminated, and 451has continued after a job control stop. 452This macro can be true only if the wait call specified the 453.Dv WCONTINUED 454option. 455.It Fn WIFEXITED status 456True if the process terminated normally by a call to 457.Xr _exit 2 458or 459.Xr exit 3 . 460.It Fn WIFSIGNALED status 461True if the process terminated due to receipt of a signal. 462.It Fn WIFSTOPPED status 463True if the process has not terminated, but has stopped and can be restarted. 464This macro can be true only if the wait call specified the 465.Dv WUNTRACED 466option 467or if the child process is being traced (see 468.Xr ptrace 2 ) . 469.El 470.Pp 471Depending on the values of those macros, the following macros 472produce the remaining status information about the child process: 473.Bl -tag -width Ds 474.It Fn WEXITSTATUS status 475If 476.Fn WIFEXITED status 477is true, evaluates to the low-order 8 bits 478of the argument passed to 479.Xr _exit 2 480or 481.Xr exit 3 482by the child. 483.It Fn WTERMSIG status 484If 485.Fn WIFSIGNALED status 486is true, evaluates to the number of the signal 487that caused the termination of the process. 488.It Fn WCOREDUMP status 489If 490.Fn WIFSIGNALED status 491is true, evaluates as true if the termination 492of the process was accompanied by the creation of a core file 493containing an image of the process when the signal was received. 494.It Fn WSTOPSIG status 495If 496.Fn WIFSTOPPED status 497is true, evaluates to the number of the signal 498that caused the process to stop. 499.El 500.Sh NOTES 501See 502.Xr sigaction 2 503for a list of termination signals. 504A status of 0 indicates normal termination. 505.Pp 506If a parent process terminates without 507waiting for all of its child processes to terminate, 508the remaining child processes are assigned the parent 509process 1 ID (the init process ID). 510.Pp 511If a signal is caught while any of the 512.Fn wait 513calls are pending, 514the call may be interrupted or restarted when the signal-catching routine 515returns, 516depending on the options in effect for the signal; 517see discussion of 518.Dv SA_RESTART 519in 520.Xr sigaction 2 . 521.Pp 522The implementation queues one 523.Dv SIGCHLD 524signal for each child process whose 525status has changed; if 526.Fn wait 527returns because the status of a child process is available, the pending 528SIGCHLD signal associated with the process ID of the child process will 529be discarded. 530Any other pending 531.Dv SIGCHLD 532signals remain pending. 533.Pp 534If 535.Dv SIGCHLD 536is blocked and 537.Fn wait 538returns because the status of a child process is available, the pending 539.Dv SIGCHLD 540signal will be cleared unless another status of the child process 541is available. 542.Sh RETURN VALUES 543If 544.Fn wait 545returns due to a stopped, continued, 546or terminated child process, the process ID of the child 547is returned to the calling process. 548Otherwise, a value of \-1 549is returned and 550.Va errno 551is set to indicate the error. 552.Pp 553If 554.Fn wait6 , 555.Fn wait4 , 556.Fn wait3 , 557or 558.Fn waitpid 559returns due to a stopped, continued, 560or terminated child process, the process ID of the child 561is returned to the calling process. 562If there are no children not previously awaited, 563-1 is returned with 564.Va errno 565set to 566.Er ECHILD . 567Otherwise, if 568.Dv WNOHANG 569is specified and there are 570no stopped, continued or exited children, 5710 is returned. 572If an error is detected or a caught signal aborts the call, 573a value of -1 574is returned and 575.Va errno 576is set to indicate the error. 577.Pp 578If 579.Fn waitid 580returns because one or more processes have a state change to report, 5810 is returned. 582If an error is detected, 583a value of -1 584is returned and 585.Va errno 586is set to indicate the error. 587If 588.Dv WNOHANG 589is specified and there are 590no stopped, continued or exited children, 5910 is returned. 592The 593.Fa si_signo 594and 595.Fa si_pid 596fields of 597.Fa infop 598must be checked against zero to determine if a process reported status. 599.Pp 600.Fn wait 601called with -1 to wait for any child process will ignore a child that is 602referenced by a process descriptor (see 603.Xr pdfork 2 ) . 604Specific processes can still be waited on by specifying the process ID. 605.Sh ERRORS 606The 607.Fn wait 608function 609will fail and return immediately if: 610.Bl -tag -width Er 611.It Bq Er ECHILD 612The calling process has no existing unwaited-for 613child processes. 614.It Bq Er ECHILD 615No status from the terminated child process is available 616because the calling process has asked the system to discard 617such status by ignoring the signal 618.Dv SIGCHLD 619or setting the flag 620.Dv SA_NOCLDWAIT 621for that signal. 622.It Bq Er EFAULT 623The 624.Fa status 625or 626.Fa rusage 627argument points to an illegal address. 628(May not be detected before exit of a child process.) 629.It Bq Er EINTR 630The call was interrupted by a caught signal, 631or the signal did not have the 632.Dv SA_RESTART 633flag set. 634.It Bq Er EINVAL 635An invalid value was specified for 636.Fa options , 637or 638.Fa idtype 639and 640.Fa id 641do not specify a valid set of processes. 642.El 643.Sh SEE ALSO 644.Xr _exit 2 , 645.Xr ptrace 2 , 646.Xr sigaction 2 , 647.Xr exit 3 , 648.Xr siginfo 3 649.Sh STANDARDS 650The 651.Fn wait , 652.Fn waitpid , 653and 654.Fn waitid 655functions are defined by POSIX; 656.Fn wait6 , 657.Fn wait4 , 658and 659.Fn wait3 660are not specified by POSIX. 661The 662.Fn WCOREDUMP 663macro 664is an extension to the POSIX interface. 665.Pp 666The ability to use the 667.Dv WNOWAIT 668flag with 669.Fn waitpid 670is an extension; 671.Tn POSIX 672only permits this flag with 673.Fn waitid . 674.Sh HISTORY 675The 676.Fn wait 677function appeared in 678.At v1 . 679