1.\" $NetBSD: wait.2,v 1.42 2022/12/04 11:25:09 uwe Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)wait.2 8.2 (Berkeley) 4/19/94 31.\" 32.Dd October 17, 2022 33.Dt WAIT 2 34.Os 35.Sh NAME 36.Nm wait , 37.Nm waitid , 38.Nm waitpid , 39.Nm wait6 , 40.Nm wait4 , 41.Nm wait3 42.Nd wait for process termination 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 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.Ft int 52.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options" 53.In sys/resource.h 54.Ft pid_t 55.Fn wait3 "int *status" "int options" "struct rusage *rusage" 56.Ft pid_t 57.Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" 58.Ft pid_t 59.Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct wrusage *wrusage" "siginfo_t *infop" 60.Sh DESCRIPTION 61The 62.Fn wait 63function suspends execution of its calling process until 64.Fa status 65information is available for a terminated child process, 66or a signal is received. 67On return from a successful 68.Fn wait 69call, 70the 71.Fa status 72area contains termination information about the process that exited 73as defined below. 74.Pp 75The 76.Fn wait4 77and 78.Fn wait6 79call provides a more general interface for programs 80that need to wait for certain child processes, 81that need resource utilization statistics accumulated by child processes, 82or that require options. 83The other wait functions are implemented using 84.Fn wait4 . 85or 86.Fn wait6 . 87.Pp 88The 89.Fn wait6 90function is the most general function in this family and its distinct 91features are: 92.Pp 93All of the desired process statuses to be waited on must be explicitly 94specified in 95.Fa options . 96The 97.Fn wait , 98.Fn waitpid , 99.Fn wait3 , 100and 101.Fn wait4 102functions all implicitly wait for exited and trapped processes, 103but the 104.Fn waitid 105and 106.Fn wait6 107functions require the corresponding 108.Dv WEXITED 109and 110.Dv WTRAPPED 111flags to be explicitly specified. 112This allows waiting for processes which have experienced other 113status changes without having to also handle the exit status from 114terminated processes. 115.Pp 116The 117.Fn wait6 118function accepts a 119.Fa wrusage 120argument which points to a structure defined as: 121.Bd -literal 122struct wrusage { 123 struct rusage wru_self; 124 struct rusage wru_children; 125}; 126.Ed 127.Pp 128This allows the calling process to collect resource usage statistics 129from both its own child process as well as from its grand children. 130When no resource usage statistics are needed this pointer can be 131.Dv NULL . 132.Pp 133The last argument 134.Fa infop 135must be either 136.Dv NULL 137or a pointer to a 138.Fa siginfo_t 139structure. 140If 141.Pf non- Dv NULL , 142the structure is filled with the same data as for a 143.Dv SIGCHLD 144signal delivered when the process changed state. 145.Pp 146The set of child processes to be queried is specified by the arguments 147.Fa idtype 148and 149.Fa id . 150The separate 151.Fa idtype 152and 153.Fa id 154arguments support many other types of 155identifiers in addition to process IDs and process group IDs. 156.Bl -bullet -offset indent 157.It 158If 159.Fa idtype 160is 161.Dv P_PID , 162.Fn waitid 163and 164.Fn wait6 165wait for the child process with a process ID equal to 166.Dv (pid_t)id . 167.It 168If 169.Fa idtype 170is 171.Dv P_PGID , 172.Fn waitid 173and 174.Fn wait6 175wait for the child process with a process group ID equal to 176.Dv (pid_t)id . 177.It 178If 179.Fa idtype 180is 181.Dv P_ALL , 182.Fn waitid 183and 184.Fn wait6 185wait for any child process and the 186.Dv id 187is ignored. 188.It 189If 190.Fa idtype 191is 192.Dv P_PID 193or 194.Dv P_PGID 195and the 196.Dv id 197is zero, 198.Fn waitid 199and 200.Fn wait6 201wait for any child process in the same process group as the caller. 202.El 203.Pp 204Non-standard identifier types supported by this 205implementation of 206.Fn waitid 207and 208.Fn wait6 209are: 210.Bl -tag -width P_JAILID 211.It Dv P_UID 212Wait for processes whose effective user ID is equal to 213.Dv (uid_t) Fa id . 214.It Dv P_GID 215Wait for processes whose effective group ID is equal to 216.Dv (gid_t) Fa id . 217.It Dv P_SID 218Wait for processes whose session ID is equal to 219.Fa id . 220.\" This is just how sessions work, not sure this needs to be documented here 221If the child process started its own session, 222its session ID will be the same as its process ID. 223Otherwise the session ID of a child process will match the caller's session ID. 224.\" .It Dv P_JAILID 225.\" Waits for processes within a jail whose jail identifier is equal to 226.\" .Fa id . 227.El 228.Pp 229For the 230.Fn waitpid 231and 232.Fn wait4 233functions, the single 234.Fa wpid 235argument specifies the set of child processes for which to wait. 236The following symbolic constants are defined in 237.In sys/wait.h 238.Bd -literal -offset indent 239#define WAIT_ANY (-1) /* any process */ 240#define WAIT_MYPGRP 0 /* any process in my process group */ 241.Ed 242.Bl -bullet -offset indent 243.It 244If 245.Fa wpid 246is 247.Dv WAIT_ANY , 248the call waits for any child process. 249.It 250If 251.Fa wpid 252is 253.Dv WAIT_MYPGRP , 254the call waits for any child process in the process group of the caller. 255.It 256If 257.Fa wpid 258is greater than zero, the call waits for the process with process ID 259.Fa wpid . 260.It 261If 262.Fa wpid 263is less than \-1, the call waits for any process whose process group ID 264equals the absolute value of 265.Fa wpid . 266.El 267.Pp 268The 269.Fa status 270argument is defined below. 271.Pp 272The 273.Fa options 274argument contains the bitwise OR of any of the following options. 275.Bl -tag -width WCONTINUED 276.It Dv WALLSIG 277If this option is specified, the call will wait for all children regardless 278of what exit signal they post. 279.It Dv WALTSIG 280If this option is specified, the call will wait only for processes that 281are configured to post a signal other than 282.Dv SIGCHLD 283when they exit. 284If 285.Dv WALTSIG 286is not specified, the call will wait only for processes that 287are configured to post 288.Dv SIGCHLD . 289.It Dv WCONTINUED 290Report the status of selected processes that 291have continued from a job control stop by receiving a 292.Dv SIGCONT 293signal. 294.It Dv WEXITED 295Report the status of selected processes which have terminated. 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 terminated processes are expected. 310.It Dv WNOHANG 311Do not block when 312there are no processes wishing to report status. 313.It Dv WNOWAIT 314Keep the process whose status is returned in a waitable state. 315The process may be waited for again after this call completes. 316.It Dv WNOZOMBIE 317Exclude zombie processes from the child selection criteria. 318.It Dv WSTOPPED 319An alias for 320.Dv WUNTRACED . 321.It Dv WTRAPPED 322Report the status of selected processes which are being traced via 323.Xr ptrace 2 324and have trapped or reached a breakpoint. 325This flag is implicitly set for the functions 326.Fn wait , 327.Fn waitpid , 328.Fn wait3 , 329and 330.Fn wait4 . 331.br 332For the 333.Fn waitid 334and 335.Fn wait6 336functions, the flag has to be explicitly included in 337.Fa options 338if status reports from trapped processes are expected. 339.It Dv WUNTRACED 340Report the status of selected processes which are stopped due to a 341.Dv SIGTTIN , SIGTTOU , SIGTSTP , 342or 343.Dv SIGSTOP 344signal. 345.It Dv __WALL 346This is an alias for 347.Dv WALLSIG . 348It is provided for compatibility with the Linux 349.Xr clone 2 350API . 351.It Dv __WCLONE 352This is an alias for 353.Dv WALTSIG . 354It is provided for compatibility with the Linux 355.Xr clone 2 356API. 357.El 358.sp 359For the 360.Fn waitid 361and 362.Fn wait6 363functions, at least one of the options 364.Dv WEXITED , 365.Dv WUNTRACED , 366.Dv WSTOPPED , 367.Dv WTRAPPED , 368or 369.Dv WCONTINUED 370must be specified. 371Otherwise there will be no events for the call to report. 372To avoid hanging indefinitely in such a case these functions 373return \-1 with 374.Dv errno 375set to 376.Er EINVAL . 377.Pp 378If 379.Fa rusage 380is 381.Pf non- Dv NULL , 382a summary of the resources used by the terminated 383process and all its children is returned. 384.Pp 385If 386.Fa wrusage 387is 388.Pf non- Dv NULL , 389separate summaries are returned for the resources used 390by the terminated process and the resources used by all its children. 391.Pp 392If 393.Fa infop 394is 395.Pf non- Dv NULL , 396a 397.Dv siginfo_t 398structure is returned with the 399.Fa si_signo 400field set to 401.Dv SIGCHLD 402and the 403.Fa si_pid 404field set to the process ID of the process reporting status. 405For the exited process, the 406.Fa si_status 407field of the 408.Dv siginfo_t 409structure contains the full 32 bit exit status passed to 410.Xr _exit 2 ; 411the 412.Fa status 413argument of other calls only returns the 8 lowest bits of the exit status. 414.Pp 415When the 416.Dv WNOHANG 417option is specified and no processes 418wish to report status, 419.Fn waitid 420sets the 421.Fa si_signo 422and 423.Fa si_pid 424fields in 425.Fa infop 426to zero. 427Checking these fields is the only way to know if a status change was reported. 428.Pp 429When the 430.Dv WNOHANG 431option is specified and no processes 432wish to report status, 433.Fn wait4 434returns a 435process id 436of 0. 437.Pp 438The 439.Fn waitpid 440call is identical to 441.Fn wait4 442with an 443.Fa rusage 444value of zero. 445The older 446.Fn wait3 447call is the same as 448.Fn wait4 449with a 450.Fa wpid 451value of \-1. 452.Pp 453The following macros may be used to test the manner of exit of the process. 454Note that these macros expect the 455.Fa status 456value itself, not a pointer to the 457.Fa status 458value. 459One of the first three macros will evaluate to a non-zero (true) value: 460.Bl -tag -width Ds 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.It Fn WIFCONTINUED status 476True if the process has not terminated, but has been continued via the 477delivery of the 478.Dv SIGCONT 479signal. 480This macro can be true only if the wait call specified the 481.Dv WCONTINUED 482option. 483.El 484.Pp 485Depending on the values of those macros, the following macros 486produce the remaining status information about the child process: 487.Bl -tag -width Ds 488.It Fn WEXITSTATUS status 489If 490.Fn WIFEXITED status 491is true, evaluates to the low-order 8 bits 492of the argument passed to 493.Xr _exit 2 494or 495.Xr exit 3 496by the child. 497.It Fn WTERMSIG status 498If 499.Fn WIFSIGNALED status 500is true, evaluates to the number of the signal 501that caused the termination of the process. 502.It Fn WCOREDUMP status 503If 504.Fn WIFSIGNALED status 505is true, evaluates as true if the termination 506of the process was accompanied by the creation of a core file 507containing an image of the process when the signal was received. 508.It Fn WSTOPSIG status 509If 510.Fn WIFSTOPPED status 511is true, evaluates to the number of the signal 512that caused the process to stop. 513.El 514.Sh NOTES 515See 516.Xr sigaction 2 517for a list of termination signals. 518A status of 0 indicates normal termination. 519.Pp 520If a parent process terminates without 521waiting for all of its child processes to terminate, 522the remaining child processes are assigned the parent 523process 1 ID (the init process ID). 524.Pp 525If a signal is caught while any of the 526.Fn wait 527calls is pending, 528the call may be interrupted or restarted when the signal-catching routine 529returns, 530depending on the options in effect for the signal; 531see 532.Xr siginterrupt 3 . 533.Sh RETURN VALUES 534If 535.Fn wait 536returns due to a stopped 537or terminated child process, the process ID of the child 538is returned to the calling process. 539Otherwise, a value of \-1 is returned and 540.Va errno 541is set to indicate the error. 542.Pp 543If 544.Fn wait6 , 545.Fn wait4 , 546.Fn wait3 547or 548.Fn waitpid 549returns due to a stopped 550or terminated child process, the process ID of the child 551is returned to the calling process. 552If there are no children not previously awaited, 553\-1 is returned with 554.Va errno 555set to 556.Bq Er ECHILD . 557Otherwise, if 558.Dv WNOHANG 559is specified and there are 560no stopped or exited children, 0 is returned. 561If an error is detected or a caught signal aborts the call, 562a value of \-1 is returned and 563.Va errno 564is set to indicate the error. 565.Pp 566If 567.Fn waitid 568returns because one or more processes have a state change to report, 5690 is returned. 570If an error is detected, 571a value of -1 572is returned and 573.Va errno 574is set to indicate the error. 575If 576.Dv WNOHANG 577is specified and there are 578no stopped, continued or exited children, 5790 is returned. 580The 581.Fa si_signo 582and 583.Fa si_pid 584fields of 585.Fa infop 586must be checked against zero to determine if a process reported status. 587.Sh ERRORS 588.Fn wait 589will fail and return immediately if: 590.Bl -tag -width Er 591.It Bq Er ECHILD 592The calling process has no existing unwaited-for child processes; or 593no status from the terminated child process is available 594because the calling process has asked the system to discard 595such status by ignoring the signal 596.Dv SIGCHLD 597or setting the flag 598.Dv SA_NOCLDWAIT 599for that signal. 600.It Bq Er EFAULT 601The 602.Fa status 603or 604.Fa rusage 605arguments point to an illegal address. 606(May not be detected before exit of a child process.) 607.It Bq Er EINTR 608The call was interrupted by a caught signal, 609or the signal did not have the 610.Dv SA_RESTART 611flag set. 612.El 613.Pp 614In addition, 615.Fn wait6 , 616.Fn wait3 , 617.Fn wait4 , 618.Fn waitid , 619and 620.Fn waitpid 621will fail and return immediately if: 622.Bl -tag -width Er 623.It Bq Er EINVAL 624An invalid value was specified for 625.Fa options . 626.El 627.Sh SEE ALSO 628.Xr _exit 2 , 629.Xr fork 2 , 630.Xr ptrace 2 , 631.Xr sigaction 2 , 632.Xr siginfo 2 , 633.Xr exit 3 , 634.Xr siginterrupt 3 635.Sh STANDARDS 636The 637.Fn wait 638and 639.Fn waitpid 640functions conform to 641.St -p1003.1-90 ; 642the 643.Fn waitid 644function conforms to 645.St -p1003.1-2004 ; 646the 647.Fn wait3 648function conforms to 649.St -xpg4 ; 650.Fn wait4 651is an extension. 652The 653.Fn WCOREDUMP 654macro 655and the ability to restart a pending 656.Fn wait 657call are extensions to the POSIX interface. 658.Sh HISTORY 659A 660.Fn wait 661function call appeared in 662.At v1 . 663