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