lib/libc/sys/wait.2

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