original/man2/wait.2

   1 .\" Copyright (c) 1993 by Thomas Koenig <ig25@rz.uni-karlsruhe.de>
   2 .\" and Copyright (c) 2004 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith <faith@cs.unc.edu>
  27 .\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith <faith@cs.unc.edu>
  28 .\"          (Thanks to Koen Holtman <koen@win.tue.nl>)
  29 .\" Modified Wed May 17 15:54:12 1995 by Rik Faith <faith@cs.unc.edu>
  30 .\"           To remove *'s from status in macros (Thanks to Michael Shields).
  31 .\" Modified as suggested by Nick Duffek <nsd@bbc.com>, aeb, 960426
  32 .\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR.
  33 .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
  34 .\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler
  35 .\"          <dwheeler@dwheeler.com> - noted thread issues.
  36 .\" Modified 26 Jun 01 by Michael Kerrisk
  37 .\"          Added __WCLONE, __WALL, and __WNOTHREAD descriptions
  38 .\" Modified 2001-09-25, aeb
  39 .\" Modified 26 Jun 01 by Michael Kerrisk, <mtk.manpages@gmail.com>
  40 .\"     Updated notes on setting disposition of SIGCHLD to SIG_IGN
  41 .\" 2004-11-11, mtk
  42 .\"     Added waitid(2); added WCONTINUED and WIFCONTINUED()
  43 .\"     Added text on SA_NOCLDSTOP
  44 .\"     Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior
  45 .\"     Much other text rewritten
  46 .\" 2005-05-10, mtk, __W* flags can't be used with waitid()
  47 .\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP
  48 .\"
  49 .TH WAIT 2 2012-12-21 "Linux" "Linux Programmer's Manual"
  50 .SH NAME
  51 wait, waitpid, waitid \- wait for process to change state
  52 .SH SYNOPSIS
  53 .B #include <sys/types.h>
  54 .br
  55 .B #include <sys/wait.h>
  56 .sp
  57 .BI "pid_t wait(int *" "status" );
  58
  59 .BI "pid_t waitpid(pid_t " pid ", int *" status ", int " options );
  60
  61 .BI "int waitid(idtype_t " idtype ", id_t " id \
  62 ", siginfo_t *" infop ", int " options );
  63 .sp
  64 .in -4n
  65 Feature Test Macro Requirements for glibc (see
  66 .BR feature_test_macros (7)):
  67 .in
  68 .sp
  69 .ad l
  70 .PD 0
  71 .BR waitid ():
  72 .RS 4
  73 _SVID_SOURCE ||
  74 _XOPEN_SOURCE\ >=\ 500 ||
  75 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  76 .br
  77 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  78 .RE
  79 .PD
  80 .ad
  81 .SH DESCRIPTION
  82 All of these system calls are used to wait for state changes
  83 in a child of the calling process, and obtain information
  84 about the child whose state has changed.
  85 A state change is considered to be: the child terminated;
  86 the child was stopped by a signal; or the child was resumed by a signal.
  87 In the case of a terminated child, performing a wait allows
  88 the system to release the resources associated with the child;
  89 if a wait is not performed, then the terminated child remains in
  90 a "zombie" state (see NOTES below).
  91
  92 If a child has already changed state, then these calls return immediately.
  93 Otherwise they block until either a child changes state or
  94 a signal handler interrupts the call (assuming that system calls
  95 are not automatically restarted using the
  96 .B SA_RESTART
  97 flag of
  98 .BR sigaction (2)).
  99 In the remainder of this page, a child whose state has changed
 100 and which has not yet been waited upon by one of these system
 101 calls is termed
 102 .IR waitable .
 103 .SS wait() and waitpid()
 104 The
 105 .BR wait ()
 106 system call suspends execution of the calling process until one of its
 107 children terminates.
 108 The call
 109 .I wait(&status)
 110 is equivalent to:
 111 .nf
 112
 113     waitpid(\-1, &status, 0);
 114 .fi
 115
 116 The
 117 .BR waitpid ()
 118 system call suspends execution of the calling process until a
 119 child specified by
 120 .I pid
 121 argument has changed state.
 122 By default,
 123 .BR waitpid ()
 124 waits only for terminated children, but this behavior is modifiable
 125 via the
 126 .I options
 127 argument, as described below.
 128
 129 The value of
 130 .I pid
 131 can be:
 132 .IP "< \-1"
 133 meaning wait for any child process whose process group ID is
 134 equal to the absolute value of
 135 .IR pid .
 136 .IP \-1
 137 meaning wait for any child process.
 138 .IP 0
 139 meaning wait for any child process whose process group ID is
 140 equal to that of the calling process.
 141 .IP "> 0"
 142 meaning wait for the child whose process ID is equal to the
 143 value of
 144 .IR pid .
 145 .PP
 146 The value of
 147 .I options
 148 is an OR of zero or more of the following constants:
 149 .TP 12
 150 .B WNOHANG
 151 return immediately if no child has exited.
 152 .TP
 153 .B WUNTRACED
 154 also return if a child has stopped
 155 (but not traced via
 156 .BR ptrace (2)).
 157 Status for
 158 .I traced
 159 children which have stopped is provided
 160 even if this option is not specified.
 161 .TP
 162 .BR WCONTINUED " (since Linux 2.6.10)"
 163 also return if a stopped child has been resumed by delivery of
 164 .BR SIGCONT .
 165 .PP
 166 (For Linux-only options, see below.)
 167 .PP
 168 If
 169 .I status
 170 is not NULL,
 171 .BR wait ()
 172 and
 173 .BR waitpid ()
 174 store status information in the \fIint\fP to which it points.
 175 This integer can be inspected with the following macros (which
 176 take the integer itself as an argument, not a pointer to it,
 177 as is done in
 178 .BR wait ()
 179 and
 180 .BR waitpid ()!):
 181 .TP
 182 .BI WIFEXITED( status )
 183 returns true if the child terminated normally, that is,
 184 by calling
 185 .BR exit (3)
 186 or
 187 .BR _exit (2),
 188 or by returning from main().
 189 .TP
 190 .BI WEXITSTATUS( status )
 191 returns the exit status of the child.
 192 This consists of the least significant 8 bits of the
 193 .I status
 194 argument that the child specified in a call to
 195 .BR exit (3)
 196 or
 197 .BR _exit (2)
 198 or as the argument for a return statement in main().
 199 This macro should be employed only if
 200 .B WIFEXITED
 201 returned true.
 202 .TP
 203 .BI WIFSIGNALED( status )
 204 returns true if the child process was terminated by a signal.
 205 .TP
 206 .BI WTERMSIG( status )
 207 returns the number of the signal that caused the child process to
 208 terminate.
 209 This macro should be employed only if
 210 .B WIFSIGNALED
 211 returned true.
 212 .TP
 213 .BI WCOREDUMP( status )
 214 returns true if the child produced a core dump.
 215 This macro should be employed only if
 216 .B WIFSIGNALED
 217 returned true.
 218 This macro is not specified in POSIX.1-2001 and is not available on
 219 some UNIX implementations (e.g., AIX, SunOS).
 220 Only use this enclosed in #ifdef WCOREDUMP ... #endif.
 221 .TP
 222 .BI WIFSTOPPED( status )
 223 returns true if the child process was stopped by delivery of a signal;
 224 this is possible only if the call was done using
 225 .B WUNTRACED
 226 or when the child is being traced (see
 227 .BR ptrace (2)).
 228 .TP
 229 .BI WSTOPSIG( status )
 230 returns the number of the signal which caused the child to stop.
 231 This macro should be employed only if
 232 .B WIFSTOPPED
 233 returned true.
 234 .TP
 235 .BI WIFCONTINUED( status )
 236 (since Linux 2.6.10)
 237 returns true if the child process was resumed by delivery of
 238 .BR SIGCONT .
 239 .SS waitid()
 240 The
 241 .BR waitid ()
 242 system call (available since Linux 2.6.9) provides more precise
 243 control over which child state changes to wait for.
 244
 245 The
 246 .I idtype
 247 and
 248 .I id
 249 arguments select the child(ren) to wait for, as follows:
 250 .IP "\fIidtype\fP == \fBP_PID\fP"
 251 Wait for the child whose process ID matches
 252 .IR id .
 253 .IP "\fIidtype\fP == \fBP_PGID\fP"
 254 Wait for any child whose process group ID matches
 255 .IR id .
 256 .IP "\fIidtype\fP == \fBP_ALL\fP"
 257 Wait for any child;
 258 .I id
 259 is ignored.
 260 .PP
 261 The child state changes to wait for are specified by ORing
 262 one or more of the following flags in
 263 .IR options :
 264 .TP 12
 265 .B WEXITED
 266 Wait for children that have terminated.
 267 .TP
 268 .B WSTOPPED
 269 Wait for children that have been stopped by delivery of a signal.
 270 .TP
 271 .B WCONTINUED
 272 Wait for (previously stopped) children that have been
 273 resumed by delivery of
 274 .BR SIGCONT .
 275 .PP
 276 The following flags may additionally be ORed in
 277 .IR options :
 278 .TP 12
 279 .B WNOHANG
 280 As for
 281 .BR waitpid ().
 282 .TP
 283 .B WNOWAIT
 284 Leave the child in a waitable state; a later wait call
 285 can be used to again retrieve the child status information.
 286 .PP
 287 Upon successful return,
 288 .BR waitid ()
 289 fills in the following fields of the
 290 .I siginfo_t
 291 structure pointed to by
 292 .IR infop :
 293 .TP 12
 294 \fIsi_pid\fP
 295 The process ID of the child.
 296 .TP
 297 \fIsi_uid\fP
 298 The real user ID of the child.
 299 (This field is not set on most other implementations.)
 300 .TP
 301 \fIsi_signo\fP
 302 Always set to
 303 .BR SIGCHLD .
 304 .TP
 305 \fIsi_status\fP
 306 Either the exit status of the child, as given to
 307 .BR _exit (2)
 308 (or
 309 .BR exit (3)),
 310 or the signal that caused the child to terminate, stop, or continue.
 311 The
 312 .I si_code
 313 field can be used to determine how to interpret this field.
 314 .TP
 315 \fIsi_code\fP
 316 Set to one of:
 317 .B CLD_EXITED
 318 (child called
 319 .BR _exit (2));
 320 .B CLD_KILLED
 321 (child killed by signal);
 322 .B CLD_DUMPED
 323 (child killed by signal, and dumped core);
 324 .B CLD_STOPPED
 325 (child stopped by signal);
 326 .B CLD_TRAPPED
 327 (traced child has trapped); or
 328 .B CLD_CONTINUED
 329 (child continued by
 330 .BR SIGCONT ).
 331 .PP
 332 If
 333 .B WNOHANG
 334 was specified in
 335 .I options
 336 and there were no children in a waitable state, then
 337 .BR waitid ()
 338 returns 0 immediately and
 339 the state of the
 340 .I siginfo_t
 341 structure pointed to by
 342 .I infop
 343 is unspecified.
 344 .\" POSIX.1-2001 leaves this possibility unspecified; most
 345 .\" implementations (including Linux) zero out the structure
 346 .\" in this case, but at least one implementation (AIX 5.1)
 347 .\" does not -- MTK Nov 04
 348 To distinguish this case from that where a child was in a
 349 waitable state, zero out the
 350 .I si_pid
 351 field before the call and check for a nonzero value in this field
 352 after the call returns.
 353 .SH RETURN VALUE
 354 .BR wait ():
 355 on success, returns the process ID of the terminated child;
 356 on error, \-1 is returned.
 357
 358 .BR waitpid ():
 359 on success, returns the process ID of the child whose state has changed;
 360 if
 361 .B WNOHANG
 362 was specified and one or more child(ren) specified by
 363 .I pid
 364 exist, but have not yet changed state, then 0 is returned.
 365 On error, \-1 is returned.
 366
 367 .BR waitid ():
 368 returns 0 on success or
 369 if
 370 .B WNOHANG
 371 was specified and no child(ren) specified by
 372 .I id
 373 has yet changed state;
 374 on error, \-1 is returned.
 375 .\" FIXME: As reported by Vegard Nossum, if infop is NULL, then waitid()
 376 .\" returns the PID of the child.  Either this is a bug, or it is intended
 377 .\" behavior that needs to be documented.  See my Jan 2009 LKML mail
 378 .\" "waitid() return value strangeness when infop is NULL".
 379 Each of these calls sets
 380 .I errno
 381 to an appropriate value in the case of an error.
 382 .SH ERRORS
 383 .TP
 384 .B ECHILD
 385 (for
 386 .BR wait ())
 387 The calling process does not have any unwaited-for children.
 388 .TP
 389 .B ECHILD
 390 (for
 391 .BR waitpid ()
 392 or
 393 .BR waitid ())
 394 The process specified by
 395 .I pid
 396 .RB ( waitpid ())
 397 or
 398 .I idtype
 399 and
 400 .I id
 401 .RB ( waitid ())
 402 does not exist or is not a child of the calling process.
 403 (This can happen for one's own child if the action for
 404 .B SIGCHLD
 405 is set to
 406 .BR SIG_IGN .
 407 See also the \fILinux Notes\fP section about threads.)
 408 .TP
 409 .B EINTR
 410 .B WNOHANG
 411 was not set and an unblocked signal or a
 412 .B SIGCHLD
 413 was caught; see
 414 .BR signal (7).
 415 .TP
 416 .B EINVAL
 417 The
 418 .I options
 419 argument was invalid.
 420 .SH CONFORMING TO
 421 SVr4, 4.3BSD, POSIX.1-2001.
 422 .SH NOTES
 423 A child that terminates, but has not been waited for becomes a "zombie".
 424 The kernel maintains a minimal set of information about the zombie
 425 process (PID, termination status, resource usage information)
 426 in order to allow the parent to later perform a wait to obtain
 427 information about the child.
 428 As long as a zombie is not removed from the system via a wait,
 429 it will consume a slot in the kernel process table, and if
 430 this table fills, it will not be possible to create further processes.
 431 If a parent process terminates, then its "zombie" children (if any)
 432 are adopted by
 433 .BR init (8),
 434 which automatically performs a wait to remove the zombies.
 435
 436 POSIX.1-2001 specifies that if the disposition of
 437 .B SIGCHLD
 438 is set to
 439 .B SIG_IGN
 440 or the
 441 .B SA_NOCLDWAIT
 442 flag is set for
 443 .B SIGCHLD
 444 (see
 445 .BR sigaction (2)),
 446 then children that terminate do not become zombies and a call to
 447 .BR wait ()
 448 or
 449 .BR waitpid ()
 450 will block until all children have terminated, and then fail with
 451 .I errno
 452 set to
 453 .BR ECHILD .
 454 (The original POSIX standard left the behavior of setting
 455 .B SIGCHLD
 456 to
 457 .B SIG_IGN
 458 unspecified.
 459 Note that even though the default disposition of
 460 .B SIGCHLD
 461 is "ignore", explicitly setting the disposition to
 462 .B SIG_IGN
 463 results in different treatment of zombie process children.)
 464 Linux 2.6 conforms to this specification.
 465 However, Linux 2.4 (and earlier) does not:
 466 if a
 467 .BR wait ()
 468 or
 469 .BR waitpid ()
 470 call is made while
 471 .B SIGCHLD
 472 is being ignored, the call behaves just as though
 473 .B SIGCHLD
 474 were not being ignored, that is, the call blocks until the next child
 475 terminates and then returns the process ID and status of that child.
 476 .SS Linux notes
 477 In the Linux kernel, a kernel-scheduled thread is not a distinct
 478 construct from a process.
 479 Instead, a thread is simply a process
 480 that is created using the Linux-unique
 481 .BR clone (2)
 482 system call; other routines such as the portable
 483 .BR pthread_create (3)
 484 call are implemented using
 485 .BR clone (2).
 486 Before Linux 2.4, a thread was just a special case of a process,
 487 and as a consequence one thread could not wait on the children
 488 of another thread, even when the latter belongs to the same thread group.
 489 However, POSIX prescribes such functionality, and since Linux 2.4
 490 a thread can, and by default will, wait on children of other threads
 491 in the same thread group.
 492 .LP
 493 The following Linux-specific
 494 .I options
 495 are for use with children created using
 496 .BR clone (2);
 497 they cannot be used with
 498 .BR waitid ():
 499 .TP
 500 .B __WCLONE
 501 .\" since 0.99pl10
 502 Wait for "clone" children only.
 503 If omitted then wait for "non-clone" children only.
 504 (A "clone" child is one which delivers no signal, or a signal other than
 505 .B SIGCHLD
 506 to its parent upon termination.)
 507 This option is ignored if
 508 .B __WALL
 509 is also specified.
 510 .TP
 511 .BR __WALL " (since Linux 2.4)"
 512 .\" since patch-2.3.48
 513 Wait for all children, regardless of
 514 type ("clone" or "non-clone").
 515 .TP
 516 .BR __WNOTHREAD " (since Linux 2.4)"
 517 .\" since patch-2.4.0-test8
 518 Do not wait for children of other threads in
 519 the same thread group.
 520 This was the default before Linux 2.4.
 521 .SH BUGS
 522 According to POSIX.1-2008, an application calling
 523 .BR waitid ()
 524 must ensure that
 525 .I infop
 526 points to a
 527 .I siginfo_t
 528 structure (i.e., that it is a non-NULL pointer).
 529 On Linux, if
 530 .I infop
 531 is NULL,
 532 .BR waitid ()
 533 succeeds, and returns the process ID of the waited-for child.
 534 Applications should avoid relying on this inconsistent,
 535 nonstandard, and unnecessary feature.
 536 .SH EXAMPLE
 537 .\" fork.2 refers to this example program.
 538 The following program demonstrates the use of
 539 .BR fork (2)
 540 and
 541 .BR waitpid ().
 542 The program creates a child process.
 543 If no command-line argument is supplied to the program,
 544 then the child suspends its execution using
 545 .BR pause (2),
 546 to allow the user to send signals to the child.
 547 Otherwise, if a command-line argument is supplied,
 548 then the child exits immediately,
 549 using the integer supplied on the command line as the exit status.
 550 The parent process executes a loop that monitors the child using
 551 .BR waitpid (),
 552 and uses the W*() macros described above to analyze the wait status value.
 553
 554 The following shell session demonstrates the use of the program:
 555 .in +4n
 556 .nf
 557
 558 .RB "$" " ./a.out &"
 559 Child PID is 32360
 560 [1] 32359
 561 .RB "$" " kill \-STOP 32360"
 562 stopped by signal 19
 563 .RB "$" " kill \-CONT 32360"
 564 continued
 565 .RB "$" " kill \-TERM 32360"
 566 killed by signal 15
 567 [1]+  Done                    ./a.out
 568 $
 569 .fi
 570 .in
 571 .SS Program source
 572 \&
 573 .nf
 574 #include <sys/wait.h>
 575 #include <stdlib.h>
 576 #include <unistd.h>
 577 #include <stdio.h>
 578
 579 int
 580 main(int argc, char *argv[])
 581 {
 582     pid_t cpid, w;
 583     int status;
 584
 585     cpid = fork();
 586     if (cpid == \-1) {
 587         perror("fork");
 588         exit(EXIT_FAILURE);
 589     }
 590
 591     if (cpid == 0) {            /* Code executed by child */
 592         printf("Child PID is %ld\\n", (long) getpid());
 593         if (argc == 1)
 594             pause();                    /* Wait for signals */
 595         _exit(atoi(argv[1]));
 596
 597     } else {                    /* Code executed by parent */
 598         do {
 599             w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);
 600             if (w == \-1) {
 601                 perror("waitpid");
 602                 exit(EXIT_FAILURE);
 603             }
 604
 605             if (WIFEXITED(status)) {
 606                 printf("exited, status=%d\\n", WEXITSTATUS(status));
 607             } else if (WIFSIGNALED(status)) {
 608                 printf("killed by signal %d\\n", WTERMSIG(status));
 609             } else if (WIFSTOPPED(status)) {
 610                 printf("stopped by signal %d\\n", WSTOPSIG(status));
 611             } else if (WIFCONTINUED(status)) {
 612                 printf("continued\\n");
 613             }
 614         } while (!WIFEXITED(status) && !WIFSIGNALED(status));
 615         exit(EXIT_SUCCESS);
 616     }
 617 }
 618 .fi
 619 .SH SEE ALSO
 620 .BR _exit (2),
 621 .BR clone (2),
 622 .BR fork (2),
 623 .BR kill (2),
 624 .BR ptrace (2),
 625 .BR sigaction (2),
 626 .BR signal (2),
 627 .BR wait4 (2),
 628 .BR pthread_create (3),
 629 .BR credentials (7),
 630 .BR signal (7)