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 October 24, 2018
  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 .Dv (pid_t)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 .Dv (pid_t)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 .Dv 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 .Dv 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 .Dv (uid_t) Fa id .
 216 .It Dv P_GID
 217 Wait for processes whose effective group ID is equal to
 218 .Dv (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 .Dv 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 .Dv 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 .Dv siginfo_t
 369 structure contains the full 32 bit exit status passed to
 370 .Xr _exit 2 ;
 371 the
 372 .Fa status
 373 argument of other calls only returns 8 lowest bits of the exit status.
 374 .Pp
 375 When the
 376 .Dv WNOHANG
 377 option is specified and no processes
 378 wish to report status,
 379 .Fn waitid
 380 sets the
 381 .Fa si_signo
 382 and
 383 .Fa si_pid
 384 fields in
 385 .Fa infop
 386 to zero.
 387 Checking these fields is the only way to know if a status change was reported.
 388 .Pp
 389 When the
 390 .Dv WNOHANG
 391 option is specified and no processes
 392 wish to report status,
 393 .Fn wait4
 394 and
 395 .Fn wait6
 396 return a
 397 process id
 398 of 0.
 399 .Pp
 400 The
 401 .Fn wait
 402 call is the same as
 403 .Fn wait4
 404 with a
 405 .Fa wpid
 406 value of -1,
 407 with an
 408 .Fa options
 409 value of zero,
 410 and a
 411 .Fa rusage
 412 value of
 413 .Dv NULL .
 414 The
 415 .Fn waitpid
 416 function is identical to
 417 .Fn wait4
 418 with an
 419 .Fa rusage
 420 value of
 421 .Dv NULL .
 422 The older
 423 .Fn wait3
 424 call is the same as
 425 .Fn wait4
 426 with a
 427 .Fa wpid
 428 value of -1.
 429 The
 430 .Fn wait4
 431 function is identical to
 432 .Fn wait6
 433 with the flags
 434 .Dv WEXITED
 435 and
 436 .Dv WTRAPPED
 437 set in
 438 .Fa options
 439 and
 440 .Fa infop
 441 set to
 442 .Dv NULL .
 443 .Pp
 444 The following macros may be used to test the current status of the process.
 445 Exactly one of the following four macros will evaluate to a non-zero
 446 .Pq true
 447 value:
 448 .Bl -tag -width Ds
 449 .It Fn WIFCONTINUED status
 450 True if the process has not terminated, and
 451 has continued after a job control stop.
 452 This macro can be true only if the wait call specified the
 453 .Dv WCONTINUED
 454 option.
 455 .It Fn WIFEXITED status
 456 True if the process terminated normally by a call to
 457 .Xr _exit 2
 458 or
 459 .Xr exit 3 .
 460 .It Fn WIFSIGNALED status
 461 True if the process terminated due to receipt of a signal.
 462 .It Fn WIFSTOPPED status
 463 True if the process has not terminated, but has stopped and can be restarted.
 464 This macro can be true only if the wait call specified the
 465 .Dv WUNTRACED
 466 option
 467 or if the child process is being traced (see
 468 .Xr ptrace 2 ) .
 469 .El
 470 .Pp
 471 Depending on the values of those macros, the following macros
 472 produce the remaining status information about the child process:
 473 .Bl -tag -width Ds
 474 .It Fn WEXITSTATUS status
 475 If
 476 .Fn WIFEXITED status
 477 is true, evaluates to the low-order 8 bits
 478 of the argument passed to
 479 .Xr _exit 2
 480 or
 481 .Xr exit 3
 482 by the child.
 483 .It Fn WTERMSIG status
 484 If
 485 .Fn WIFSIGNALED status
 486 is true, evaluates to the number of the signal
 487 that caused the termination of the process.
 488 .It Fn WCOREDUMP status
 489 If
 490 .Fn WIFSIGNALED status
 491 is true, evaluates as true if the termination
 492 of the process was accompanied by the creation of a core file
 493 containing an image of the process when the signal was received.
 494 .It Fn WSTOPSIG status
 495 If
 496 .Fn WIFSTOPPED status
 497 is true, evaluates to the number of the signal
 498 that caused the process to stop.
 499 .El
 500 .Sh NOTES
 501 See
 502 .Xr sigaction 2
 503 for a list of termination signals.
 504 A status of 0 indicates normal termination.
 505 .Pp
 506 If a parent process terminates without
 507 waiting for all of its child processes to terminate,
 508 the remaining child processes are assigned the parent
 509 process 1 ID (the init process ID).
 510 .Pp
 511 If a signal is caught while any of the
 512 .Fn wait
 513 calls are pending,
 514 the call may be interrupted or restarted when the signal-catching routine
 515 returns,
 516 depending on the options in effect for the signal;
 517 see discussion of
 518 .Dv SA_RESTART
 519 in
 520 .Xr sigaction 2 .
 521 .Pp
 522 The implementation queues one
 523 .Dv SIGCHLD
 524 signal for each child process whose
 525 status has changed; if
 526 .Fn wait
 527 returns because the status of a child process is available, the pending
 528 SIGCHLD signal associated with the process ID of the child process will
 529 be discarded.
 530 Any other pending
 531 .Dv SIGCHLD
 532 signals remain pending.
 533 .Pp
 534 If
 535 .Dv SIGCHLD
 536 is blocked and
 537 .Fn wait
 538 returns because the status of a child process is available, the pending
 539 .Dv SIGCHLD
 540 signal will be cleared unless another status of the child process
 541 is available.
 542 .Sh RETURN VALUES
 543 If
 544 .Fn wait
 545 returns due to a stopped, continued,
 546 or terminated child process, the process ID of the child
 547 is returned to the calling process.
 548 Otherwise, a value of \-1
 549 is returned and
 550 .Va errno
 551 is set to indicate the error.
 552 .Pp
 553 If
 554 .Fn wait6 ,
 555 .Fn wait4 ,
 556 .Fn wait3 ,
 557 or
 558 .Fn waitpid
 559 returns due to a stopped, continued,
 560 or terminated child process, the process ID of the child
 561 is returned to the calling process.
 562 If there are no children not previously awaited,
 563 -1 is returned with
 564 .Va errno
 565 set to
 566 .Er ECHILD .
 567 Otherwise, if
 568 .Dv WNOHANG
 569 is specified and there are
 570 no stopped, continued or exited children,
 571 0 is returned.
 572 If an error is detected or a caught signal aborts the call,
 573 a value of -1
 574 is returned and
 575 .Va errno
 576 is set to indicate the error.
 577 .Pp
 578 If
 579 .Fn waitid
 580 returns because one or more processes have a state change to report,
 581 0 is returned.
 582 If an error is detected,
 583 a value of -1
 584 is returned and
 585 .Va errno
 586 is set to indicate the error.
 587 If
 588 .Dv WNOHANG
 589 is specified and there are
 590 no stopped, continued or exited children,
 591 0 is returned.
 592 The
 593 .Fa si_signo
 594 and
 595 .Fa si_pid
 596 fields of
 597 .Fa infop
 598 must be checked against zero to determine if a process reported status.
 599 .Pp
 600 The
 601 .Fn wait
 602 family of functions will not return a child process created with
 603 .Xr pdfork 2
 604 unless specifically directed to do so by specifying its process ID.
 605 .Sh ERRORS
 606 The
 607 .Fn wait
 608 function
 609 will fail and return immediately if:
 610 .Bl -tag -width Er
 611 .It Bq Er ECHILD
 612 The calling process has no existing unwaited-for
 613 child processes.
 614 .It Bq Er ECHILD
 615 No status from the terminated child process is available
 616 because the calling process has asked the system to discard
 617 such status by ignoring the signal
 618 .Dv SIGCHLD
 619 or setting the flag
 620 .Dv SA_NOCLDWAIT
 621 for that signal.
 622 .It Bq Er EFAULT
 623 The
 624 .Fa status
 625 or
 626 .Fa rusage
 627 argument points to an illegal address.
 628 (May not be detected before exit of a child process.)
 629 .It Bq Er EINTR
 630 The call was interrupted by a caught signal,
 631 or the signal did not have the
 632 .Dv SA_RESTART
 633 flag set.
 634 .It Bq Er EINVAL
 635 An invalid value was specified for
 636 .Fa options ,
 637 or
 638 .Fa idtype
 639 and
 640 .Fa id
 641 do not specify a valid set of processes.
 642 .El
 643 .Sh SEE ALSO
 644 .Xr _exit 2 ,
 645 .Xr ptrace 2 ,
 646 .Xr sigaction 2 ,
 647 .Xr exit 3 ,
 648 .Xr siginfo 3
 649 .Sh STANDARDS
 650 The
 651 .Fn wait ,
 652 .Fn waitpid ,
 653 and
 654 .Fn waitid
 655 functions are defined by POSIX;
 656 .Fn wait6 ,
 657 .Fn wait4 ,
 658 and
 659 .Fn wait3
 660 are not specified by POSIX.
 661 The
 662 .Fn WCOREDUMP
 663 macro
 664 is an extension to the POSIX interface.
 665 .Pp
 666 The ability to use the
 667 .Dv WNOWAIT
 668 flag with
 669 .Fn waitpid
 670 is an extension;
 671 .Tn POSIX
 672 only permits this flag with
 673 .Fn waitid .
 674 .Sh HISTORY
 675 The
 676 .Fn wait
 677 function appeared in
 678 .At v1 .