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