man2/wait.2

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