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