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