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 June 19, 2025 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.Xr ptrace 2 277can also cause a process to be continued, when a 278.Dv PT_DETACH 279request is issued to detach the debugger. 280.It Dv WNOHANG 281Do not block when 282there are no processes wishing to report status. 283.It Dv WUNTRACED 284Report the status of selected processes which are stopped due to a 285.Dv SIGTTIN , SIGTTOU , SIGTSTP , 286or 287.Dv SIGSTOP 288signal. 289.It Dv WSTOPPED 290An alias for 291.Dv WUNTRACED . 292.It Dv WTRAPPED 293Report the status of selected processes which are being traced via 294.Xr ptrace 2 295and have trapped or reached a breakpoint. 296This flag is implicitly set for the functions 297.Fn wait , 298.Fn waitpid , 299.Fn wait3 , 300and 301.Fn wait4 . 302.br 303For the 304.Fn waitid 305and 306.Fn wait6 307functions, the flag has to be explicitly included in 308.Fa options 309if status reports from trapped processes are expected. 310.It Dv WEXITED 311Report the status of selected processes which have terminated. 312This flag is implicitly set for the functions 313.Fn wait , 314.Fn waitpid , 315.Fn wait3 , 316and 317.Fn wait4 . 318.br 319For the 320.Fn waitid 321and 322.Fn wait6 323functions, the flag has to be explicitly included in 324.Fa options 325if status reports from terminated processes are expected. 326.It Dv WNOWAIT 327Keep the process whose status is returned in a waitable state. 328The process may be waited for again after this call completes. 329.El 330.sp 331For the 332.Fn waitid 333and 334.Fn wait6 335functions, at least one of the options 336.Dv WEXITED , 337.Dv WUNTRACED , 338.Dv WSTOPPED , 339.Dv WTRAPPED , 340or 341.Dv WCONTINUED 342must be specified. 343Otherwise there will be no events for the call to report. 344To avoid hanging indefinitely in such a case these functions 345return -1 with 346.Dv errno 347set to 348.Dv EINVAL . 349.Pp 350If 351.Fa rusage 352is non-NULL, a summary of the resources used by the terminated 353process and all its children is returned. 354.Pp 355If 356.Fa wrusage 357is non-NULL, separate summaries are returned for the resources used 358by the terminated process and the resources used by all its children. 359.Pp 360If 361.Fa infop 362is non-NULL, a 363.Dv siginfo_t 364structure is returned with the 365.Fa si_signo 366field set to 367.Dv SIGCHLD 368and the 369.Fa si_pid 370field set to the process ID of the process reporting status. 371For the exited process, the 372.Fa si_status 373field of the 374.Dv siginfo_t 375structure contains the full 32 bit exit status passed to 376.Xr _exit 2 ; 377the 378.Fa status 379argument of other calls only returns 8 lowest bits of the exit status. 380.Pp 381When the 382.Dv WNOHANG 383option is specified and no processes 384wish to report status, 385.Fn waitid 386sets the 387.Fa si_signo 388and 389.Fa si_pid 390fields in 391.Fa infop 392to zero. 393Checking these fields is the only way to know if a status change was reported. 394.Pp 395When the 396.Dv WNOHANG 397option is specified and no processes 398wish to report status, 399.Fn wait4 400and 401.Fn wait6 402return a 403process id 404of 0. 405.Pp 406The 407.Fn wait 408call is the same as 409.Fn wait4 410with a 411.Fa wpid 412value of -1, 413with an 414.Fa options 415value of zero, 416and a 417.Fa rusage 418value of 419.Dv NULL . 420The 421.Fn waitpid 422function is identical to 423.Fn wait4 424with an 425.Fa rusage 426value of 427.Dv NULL . 428The older 429.Fn wait3 430call is the same as 431.Fn wait4 432with a 433.Fa wpid 434value of -1. 435The 436.Fn wait4 437function is identical to 438.Fn wait6 439with the flags 440.Dv WEXITED 441and 442.Dv WTRAPPED 443set in 444.Fa options 445and 446.Fa infop 447set to 448.Dv NULL . 449.Pp 450The following macros may be used to test the current status of the process. 451Exactly one of the following four macros will evaluate to a non-zero 452.Pq true 453value: 454.Bl -tag -width Ds 455.It Fn WIFCONTINUED status 456True if the process has not terminated, and 457has continued after a job control stop or detach of a debugger. 458This macro can be true only if the wait call specified the 459.Dv WCONTINUED 460option. 461.It Fn WIFEXITED status 462True if the process terminated normally by a call to 463.Xr _exit 2 464or 465.Xr exit 3 . 466.It Fn WIFSIGNALED status 467True if the process terminated due to receipt of a signal. 468.It Fn WIFSTOPPED status 469True if the process has not terminated, but has stopped and can be restarted. 470This macro can be true only if the wait call specified the 471.Dv WUNTRACED 472option 473or if the child process is being traced (see 474.Xr ptrace 2 ) . 475.El 476.Pp 477Depending on the values of those macros, the following macros 478produce the remaining status information about the child process: 479.Bl -tag -width Ds 480.It Fn WEXITSTATUS status 481If 482.Fn WIFEXITED status 483is true, evaluates to the low-order 8 bits 484of the argument passed to 485.Xr _exit 2 486or 487.Xr exit 3 488by the child. 489.It Fn WTERMSIG status 490If 491.Fn WIFSIGNALED status 492is true, evaluates to the number of the signal 493that caused the termination of the process. 494.It Fn WCOREDUMP status 495If 496.Fn WIFSIGNALED status 497is true, evaluates as true if the termination 498of the process was accompanied by the creation of a core file 499containing an image of the process when the signal was received. 500.It Fn WSTOPSIG status 501If 502.Fn WIFSTOPPED status 503is true, evaluates to the number of the signal 504that caused the process to stop. 505.El 506.Sh NOTES 507See 508.Xr sigaction 2 509for a list of termination signals. 510A status of 0 indicates normal termination. 511.Pp 512If a parent process terminates without 513waiting for all of its child processes to terminate, 514the remaining child processes are re-assigned to the reaper 515of the exiting process as the parent, see 516.Xr procctl 2 517.Dv PROC_REAP_ACQUIRE . 518If no specific reaper was assigned, the process with ID 1, the init process, 519becomes the parent of the orphaned children by default. 520.Pp 521If a signal is caught while any of the 522.Fn wait 523calls are pending, 524the call may be interrupted or restarted when the signal-catching routine 525returns, 526depending on the options in effect for the signal; 527see discussion of 528.Dv SA_RESTART 529in 530.Xr sigaction 2 . 531.Pp 532The implementation queues one 533.Dv SIGCHLD 534signal for each child process whose 535status has changed; if 536.Fn wait 537returns because the status of a child process is available, the pending 538SIGCHLD signal associated with the process ID of the child process will 539be discarded. 540Any other pending 541.Dv SIGCHLD 542signals remain pending. 543.Pp 544If 545.Dv SIGCHLD 546is blocked and 547.Fn wait 548returns because the status of a child process is available, the pending 549.Dv SIGCHLD 550signal will be cleared unless another status of the child process 551is available. 552.Sh RETURN VALUES 553If 554.Fn wait 555returns due to a stopped, continued, 556or terminated child process, the process ID of the child 557is returned to the calling process. 558Otherwise, a value of \-1 559is returned and 560.Va errno 561is set to indicate the error. 562.Pp 563If 564.Fn wait6 , 565.Fn wait4 , 566.Fn wait3 , 567or 568.Fn waitpid 569returns due to a stopped, continued, 570or terminated child process, the process ID of the child 571is returned to the calling process. 572If there are no children not previously awaited, 573-1 is returned with 574.Va errno 575set to 576.Er ECHILD . 577Otherwise, if 578.Dv WNOHANG 579is specified and there are 580no stopped, continued or exited children, 5810 is returned. 582If an error is detected or a caught signal aborts the call, 583a value of -1 584is returned and 585.Va errno 586is set to indicate the error. 587.Pp 588If 589.Fn waitid 590returns because one or more processes have a state change to report, 5910 is returned. 592If an error is detected, 593a value of -1 594is returned and 595.Va errno 596is set to indicate the error. 597If 598.Dv WNOHANG 599is specified and there are 600no stopped, continued or exited children, 6010 is returned. 602The 603.Fa si_signo 604and 605.Fa si_pid 606fields of 607.Fa infop 608must be checked against zero to determine if a process reported status. 609.Pp 610The 611.Fn wait 612family of functions will only return a child process created with 613.Xr pdfork 2 614if the calling process is not in 615.Xr capsicum 4 616capability mode, and 617.Nm 618has been explicitly given the child's process ID. 619.Sh ERRORS 620The 621.Fn wait 622function 623will fail and return immediately if: 624.Bl -tag -width Er 625.It Bq Er ECHILD 626The calling process has no existing unwaited-for 627child processes. 628.It Bq Er ECHILD 629No status from the terminated child process is available 630because the calling process has asked the system to discard 631such status by ignoring the signal 632.Dv SIGCHLD 633or setting the flag 634.Dv SA_NOCLDWAIT 635for that signal. 636.It Bq Er EFAULT 637The 638.Fa status 639or 640.Fa rusage 641argument points to an illegal address. 642(May not be detected before exit of a child process.) 643.It Bq Er EINTR 644The call was interrupted by a caught signal, 645or the signal did not have the 646.Dv SA_RESTART 647flag set. 648.It Bq Er EINVAL 649An invalid value was specified for 650.Fa options , 651or 652.Fa idtype 653and 654.Fa id 655do not specify a valid set of processes. 656.El 657.Sh SEE ALSO 658.Xr _exit 2 , 659.Xr procctl 2 , 660.Xr ptrace 2 , 661.Xr sigaction 2 , 662.Xr exit 3 , 663.Xr siginfo 3 664.Sh STANDARDS 665The 666.Fn wait , 667.Fn waitpid , 668and 669.Fn waitid 670functions are defined by POSIX; 671.Fn wait6 , 672.Fn wait4 , 673and 674.Fn wait3 675are not specified by POSIX. 676The 677.Fn WCOREDUMP 678macro 679is an extension to the POSIX interface. 680.Pp 681The ability to use the 682.Dv WNOWAIT 683flag with 684.Fn waitpid 685is an extension; 686.Tn POSIX 687only permits this flag with 688.Fn waitid . 689.Sh HISTORY 690The 691.Fn wait 692function appeared in 693.At v1 . 694