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.Vt ( pid_t ) Fa 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.Vt ( pid_t ) Fa 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.Fa id 189is ignored. 190.It 191If 192.Fa idtype 193is 194.Dv P_PID 195or 196.Dv P_PGID 197and the 198.Fa 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.Vt ( uid_t ) Fa id . 216.It Dv P_GID 217Wait for processes whose effective group ID is equal to 218.Vt ( 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.Va errno 341set to 342.Er 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.Vt 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.Vt siginfo_t 369structure contains the fully decoded exit code passed to 370.Xr _exit 2 . 371Note that exit codes are limited to the values 0-255. 372For a process killed by a signal, the 373.Fa si_status 374field contains the fully decoded signal. 375.Pp 376The si_code field of the 377.Vt siginfo_t 378structure may be set to the following values: 379.Bl -tag -width Dv 380.It Dv CLD_EXITED 381Child exited with an exit code. 382.It Dv CLD_KILLED 383Child terminated abnormally with a signal. 384.It Dv CLD_DUMPED 385Child terminated abnormally and dumped (not implemented by 386.Dx ) . 387.It Dv CLD_TRAPPED 388Traced child has trapped. 389.It Dv CLD_STOPPED 390Child has stopped. 391.It Dv CLD_CONTINUED 392Child has been resumed. 393.El 394.Pp 395When the 396.Dv WNOHANG 397option is specified and no processes 398wish to report status, 399.Fn waitid 400sets the 401.Fa si_signo 402and 403.Fa si_pid 404fields in 405.Fa infop 406to zero. 407Checking these fields is the only way to know if a status change was reported. 408.Pp 409When the 410.Dv WNOHANG 411option is specified and no processes 412wish to report status, 413.Fn wait4 414and 415.Fn wait6 416return a 417process id 418of 0. 419.Pp 420The 421.Fn wait 422call is the same as 423.Fn wait4 424with a 425.Fa wpid 426value of -1, 427with an 428.Fa options 429value of zero, 430and a 431.Fa rusage 432value of 433.Dv NULL . 434The 435.Fn waitpid 436function is identical to 437.Fn wait4 438with an 439.Fa rusage 440value of 441.Dv NULL . 442The older 443.Fn wait3 444call is the same as 445.Fn wait4 446with a 447.Fa wpid 448value of -1. 449The 450.Fn wait4 451function is identical to 452.Fn wait6 453with the flags 454.Dv WEXITED 455and 456.Dv WTRAPPED 457set in 458.Fa options 459and 460.Fa infop 461set to 462.Dv NULL . 463.Pp 464The following macros may be used to test the current status of the process. 465Exactly one of the following four macros will evaluate to a non-zero 466.Pq true 467value: 468.Bl -tag -width Ds 469.It Fn WIFCONTINUED status 470True if the process has not terminated, and 471has continued after a job control stop. 472This macro can be true only if the wait call specified the 473.Dv WCONTINUED 474option. 475.It Fn WIFEXITED status 476True if the process terminated normally by a call to 477.Xr _exit 2 478or 479.Xr exit 3 . 480.It Fn WIFSIGNALED status 481True if the process terminated due to receipt of a signal. 482.It Fn WIFSTOPPED status 483True if the process has not terminated, but has stopped and can be restarted. 484This macro can be true only if the wait call specified the 485.Dv WUNTRACED 486option 487or if the child process is being traced (see 488.Xr ptrace 2 ) . 489.El 490.Pp 491Depending on the values of those macros, the following macros 492produce the remaining status information about the child process: 493.Bl -tag -width Ds 494.It Fn WEXITSTATUS status 495If 496.Fn WIFEXITED status 497is true, evaluates to the low-order 8 bits 498of the argument passed to 499.Xr _exit 2 500or 501.Xr exit 3 502by the child. 503.It Fn WTERMSIG status 504If 505.Fn WIFSIGNALED status 506is true, evaluates to the number of the signal 507that caused the termination of the process. 508.It Fn WCOREDUMP status 509If 510.Fn WIFSIGNALED status 511is true, evaluates as true if the termination 512of the process was accompanied by the creation of a core file 513containing an image of the process when the signal was received. 514.It Fn WSTOPSIG status 515If 516.Fn WIFSTOPPED status 517is true, evaluates to the number of the signal 518that caused the process to stop. 519.El 520.Sh NOTES 521See 522.Xr sigaction 2 523for a list of termination signals. 524A status of 0 indicates normal termination. 525.Pp 526If a parent process terminates without 527waiting for all of its child processes to terminate, 528the remaining child processes are assigned the parent 529process 1 ID (the init process ID). 530.Pp 531If a signal is caught while any of the 532.Fn wait 533calls are pending, 534the call may be interrupted or restarted when the signal-catching routine 535returns, 536depending on the options in effect for the signal; 537see discussion of 538.Dv SA_RESTART 539in 540.Xr sigaction 2 . 541.Pp 542The implementation queues one 543.Dv SIGCHLD 544signal for each child process whose 545status has changed; if 546.Fn wait 547returns because the status of a child process is available, the pending 548SIGCHLD signal associated with the process ID of the child process will 549be discarded. 550Any other pending 551.Dv SIGCHLD 552signals remain pending. 553.Pp 554If 555.Dv SIGCHLD 556is blocked and 557.Fn wait 558returns because the status of a child process is available, the pending 559.Dv SIGCHLD 560signal will be cleared unless another status of the child process 561is available. 562.Sh RETURN VALUES 563If 564.Fn wait 565returns due to a stopped, continued, 566or terminated child process, the process ID of the child 567is returned to the calling process. 568Otherwise, a value of \-1 569is returned and 570.Va errno 571is set to indicate the error. 572.Pp 573If 574.Fn wait6 , 575.Fn wait4 , 576.Fn wait3 , 577or 578.Fn waitpid 579returns due to a stopped, continued, 580or terminated child process, the process ID of the child 581is returned to the calling process. 582If there are no children not previously awaited, 583-1 is returned with 584.Va errno 585set to 586.Er ECHILD . 587Otherwise, if 588.Dv WNOHANG 589is specified and there are 590no stopped, continued or exited children, 5910 is returned. 592If an error is detected or a caught signal aborts the call, 593a value of -1 594is returned and 595.Va errno 596is set to indicate the error. 597.Pp 598If 599.Fn waitid 600returns because one or more processes have a state change to report, 6010 is returned. 602If an error is detected, 603a value of -1 604is returned and 605.Va errno 606is set to indicate the error. 607If 608.Dv WNOHANG 609is specified and there are 610no stopped, continued or exited children, 6110 is returned. 612The 613.Fa si_signo 614and 615.Fa si_pid 616fields of 617.Fa infop 618must be checked against zero to determine if a process reported status. 619.Pp 620.Fn wait 621called with -1 to wait for any child process will ignore a child that is 622referenced by a process descriptor. 623.\"(see 624.\".Xr pdfork 2 ) 625Specific processes can still be waited on by specifying the process ID. 626.Sh ERRORS 627The 628.Fn wait 629function 630will fail and return immediately if: 631.Bl -tag -width Er 632.It Bq Er ECHILD 633The calling process has no existing unwaited-for 634child processes. 635.It Bq Er ECHILD 636No status from the terminated child process is available 637because the calling process has asked the system to discard 638such status by ignoring the signal 639.Dv SIGCHLD 640or setting the flag 641.Dv SA_NOCLDWAIT 642for that signal. 643.It Bq Er EFAULT 644The 645.Fa status 646or 647.Fa rusage 648argument points to an illegal address. 649(May not be detected before exit of a child process.) 650.It Bq Er EINTR 651The call was interrupted by a caught signal, 652or the signal did not have the 653.Dv SA_RESTART 654flag set. 655.It Bq Er EINVAL 656An invalid value was specified for 657.Fa options , 658or 659.Fa idtype 660and 661.Fa id 662do not specify a valid set of processes. 663.El 664.Sh SEE ALSO 665.Xr _exit 2 , 666.Xr ptrace 2 , 667.Xr sigaction 2 , 668.Xr exit 3 669.\".Xr siginfo 3 670.Sh STANDARDS 671The 672.Fn wait , 673.Fn waitpid , 674and 675.Fn waitid 676functions are defined by POSIX; 677.Fn wait6 , 678.Fn wait4 , 679and 680.Fn wait3 681are not specified by POSIX. 682The 683.Fn WCOREDUMP 684macro 685is an extension to the POSIX interface. 686.Pp 687The ability to use the 688.Dv WNOWAIT 689flag with 690.Fn waitpid 691is an extension; 692.Tn POSIX 693only permits this flag with 694.Fn waitid . 695.Sh HISTORY 696The 697.Fn wait 698function appeared in 699.At v1 . 700