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