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