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