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