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