1WAIT(2)                    Linux Programmer's Manual                   WAIT(2)
2
3
4

NAME

6       wait, waitpid, waitid - wait for process to change state
7

SYNOPSIS

9       #include <sys/wait.h>
10
11       pid_t wait(int *wstatus);
12       pid_t waitpid(pid_t pid, int *wstatus, int options);
13
14       int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);
15                       /* This is the glibc and POSIX interface; see
16                          NOTES for information on the raw system call. */
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       waitid():
21           Since glibc 2.26:
22               _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
23           Glibc 2.25 and earlier:
24               _XOPEN_SOURCE
25                   || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
26                   || /* Glibc <= 2.19: */ _BSD_SOURCE
27

DESCRIPTION

29       All of these system calls are used to wait for state changes in a child
30       of the calling process, and obtain information about  the  child  whose
31       state  has changed.  A state change is considered to be: the child ter‐
32       minated; the child was stopped by a signal; or the child was resumed by
33       a  signal.  In the case of a terminated child, performing a wait allows
34       the system to release the resources associated with  the  child;  if  a
35       wait  is not performed, then the terminated child remains in a "zombie"
36       state (see NOTES below).
37
38       If a child has already changed state, then these calls  return  immedi‐
39       ately.   Otherwise,  they block until either a child changes state or a
40       signal handler interrupts the call (assuming that system calls are  not
41       automatically restarted using the SA_RESTART flag of sigaction(2)).  In
42       the remainder of this page, a child whose state has changed  and  which
43       has  not  yet  been  waited upon by one of these system calls is termed
44       waitable.
45
46   wait() and waitpid()
47       The wait() system call suspends execution of the calling  thread  until
48       one  of its children terminates.  The call wait(&wstatus) is equivalent
49       to:
50
51           waitpid(-1, &wstatus, 0);
52
53       The waitpid() system call suspends execution of the calling thread  un‐
54       til  a  child specified by pid argument has changed state.  By default,
55       waitpid() waits only for terminated children, but this behavior is mod‐
56       ifiable via the options argument, as described below.
57
58       The value of pid can be:
59
60       < -1   meaning  wait  for  any  child process whose process group ID is
61              equal to the absolute value of pid.
62
63       -1     meaning wait for any child process.
64
65       0      meaning wait for any child process whose  process  group  ID  is
66              equal  to that of the calling process at the time of the call to
67              waitpid().
68
69       > 0    meaning wait for the child whose process  ID  is  equal  to  the
70              value of pid.
71
72       The  value  of  options  is an OR of zero or more of the following con‐
73       stants:
74
75       WNOHANG
76              return immediately if no child has exited.
77
78       WUNTRACED
79              also  return  if  a  child  has  stopped  (but  not  traced  via
80              ptrace(2)).   Status  for  traced children which have stopped is
81              provided even if this option is not specified.
82
83       WCONTINUED (since Linux 2.6.10)
84              also return if a stopped child has been resumed by  delivery  of
85              SIGCONT.
86
87       (For Linux-only options, see below.)
88
89       If  wstatus  is not NULL, wait() and waitpid() store status information
90       in the int to which it points.  This integer can be inspected with  the
91       following  macros  (which take the integer itself as an argument, not a
92       pointer to it, as is done in wait() and waitpid()!):
93
94       WIFEXITED(wstatus)
95              returns true if the child terminated normally, that is, by call‐
96              ing exit(3) or _exit(2), or by returning from main().
97
98       WEXITSTATUS(wstatus)
99              returns  the  exit  status  of  the child.  This consists of the
100              least significant 8 bits of the status argument that  the  child
101              specified  in  a  call to exit(3) or _exit(2) or as the argument
102              for a return statement in main().  This macro should be employed
103              only if WIFEXITED returned true.
104
105       WIFSIGNALED(wstatus)
106              returns true if the child process was terminated by a signal.
107
108       WTERMSIG(wstatus)
109              returns  the  number of the signal that caused the child process
110              to terminate.  This macro should be employed only if WIFSIGNALED
111              returned true.
112
113       WCOREDUMP(wstatus)
114              returns  true  if  the child produced a core dump (see core(5)).
115              This macro should be employed only if WIFSIGNALED returned true.
116
117              This macro is not specified in POSIX.1-2001 and is not available
118              on some UNIX implementations (e.g., AIX, SunOS).  Therefore, en‐
119              close its use inside #ifdef WCOREDUMP ... #endif.
120
121       WIFSTOPPED(wstatus)
122              returns true if the child process was stopped by delivery  of  a
123              signal;  this  is  possible only if the call was done using WUN‐
124              TRACED or when the child is being traced (see ptrace(2)).