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/types.h>
10       #include <sys/wait.h>
11
12       pid_t wait(int *status);
13
14       pid_t waitpid(pid_t pid, int *status, int options);
15
16       int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       waitid(): _SVID_SOURCE || _XOPEN_SOURCE
21

DESCRIPTION

23       All of these system calls are used to wait for state changes in a child
24       of the calling process, and obtain information about  the  child  whose
25       state  has changed.  A state change is considered to be: the child ter‐
26       minated; the child was stopped by a signal; or the child was resumed by
27       a  signal.  In the case of a terminated child, performing a wait allows
28       the system to release the resources associated with  the  child;  if  a
29       wait  is not performed, then the terminated child remains in a "zombie"
30       state (see NOTES below).
31
32       If a child has already changed state, then these calls  return  immedi‐
33       ately.   Otherwise  they  block until either a child changes state or a
34       signal handler interrupts the call (assuming that system calls are  not
35       automatically restarted using the SA_RESTART flag of sigaction(2)).  In
36       the remainder of this page, a child whose state has changed  and  which
37       has  not  yet  been  waited upon by one of these system calls is termed
38       waitable.
39
40   wait() and waitpid()
41       The wait() system call suspends execution of the calling process  until
42       one  of  its children terminates.  The call wait(&status) is equivalent
43       to:
44
45           waitpid(-1, &status, 0);
46
47       The waitpid() system call suspends execution  of  the  calling  process
48       until a child specified by pid argument has changed state.  By default,
49       waitpid() waits only for terminated children, but this behavior is mod‐
50       ifiable via the options argument, as described below.
51
52       The value of pid can be:
53
54       < -1   meaning  wait  for  any  child process whose process group ID is
55              equal to the absolute value of pid.
56
57       -1     meaning wait for any child process.
58
59       0      meaning wait for any child process whose  process  group  ID  is
60              equal to that of the calling process.
61
62       > 0    meaning  wait  for  the  child  whose process ID is equal to the
63              value of pid.
64
65       The value of options is an OR of zero or more  of  the  following  con‐
66       stants:
67
68       WNOHANG     return immediately if no child has exited.
69
70       WUNTRACED   also  return  if  a  child  has stopped (but not traced via
71                   ptrace(2)).  Status for traced children which have  stopped
72                   is provided even if this option is not specified.
73
74       WCONTINUED (since Linux 2.6.10)
75                   also return if a stopped child has been resumed by delivery
76                   of SIGCONT.
77
78       (For Linux-only options, see below.)
79
80       If status is not NULL, wait() and waitpid() store status information in
81       the  int  to  which  it points.  This integer can be inspected with the
82       following macros (which take the integer itself as an argument,  not  a
83       pointer to it, as is done in wait() and waitpid()!):
84
85       WIFEXITED(status)
86              returns true if the child terminated normally, that is, by call‐
87              ing exit(3) or _exit(2), or by returning from main().
88
89       WEXITSTATUS(status)
90              returns the exit status of the  child.   This  consists  of  the
91              least  significant  8 bits of the status argument that the child
92              specified in a call to exit(3) or _exit(2) or  as  the  argument
93              for  a  return  statement  in main().  This macro should only be
94              employed if WIFEXITED returned true.
95
96       WIFSIGNALED(status)
97              returns true if the child process was terminated by a signal.
98
99       WTERMSIG(status)
100              returns the number of the signal that caused the  child  process
101              to terminate.  This macro should only be employed if WIFSIGNALED
102              returned true.
103
104       WCOREDUMP(status)
105              returns true if the child produced  a  core  dump.   This  macro
106              should  only  be  employed  if  WIFSIGNALED returned true.  This
107              macro is not specified in POSIX.1-2001 and is not  available  on
108              some  Unix  implementations  (e.g.,  AIX, SunOS).  Only use this
109              enclosed in #ifdef WCOREDUMP ... #endif.
110
111       WIFSTOPPED(status)
112              returns true if the child process was stopped by delivery  of  a
113              signal;  this  is  only possible if the call was done using WUN‐
114              TRACED or when the child is being traced (see ptrace(2)).
115
116       WSTOPSIG(status)
117              returns the number of the signal which caused the child to stop.
118              This macro should only be employed if WIFSTOPPED returned true.
119
120       WIFCONTINUED(status)
121              (since  Linux  2.6.10)  returns  true  if  the child process was
122              resumed by delivery of SIGCONT.
123
124   waitid()
125       The waitid() system call (available since Linux  2.6.9)  provides  more
126       precise control over which child state changes to wait for.
127
128       The  idtype and id arguments select the child(ren) to wait for, as fol‐
129       lows:
130
131       idtype == P_PID
132              Wait for the child whose process ID matches id.
133
134       idtype == P_PGID
135              Wait for any child whose process group ID matches id.
136
137       idtype == P_ALL
138              Wait for any child; id is ignored.
139
140       The child state changes to wait for are specified by ORing one or  more
141       of the following flags in options:
142
143       WEXITED     Wait for children that have terminated.
144
145       WSTOPPED    Wait  for  children that have been stopped by delivery of a
146                   signal.
147
148       WCONTINUED  Wait for  (previously  stopped)  children  that  have  been
149                   resumed by delivery of SIGCONT.
150
151       The following flags may additionally be ORed in options:
152
153       WNOHANG     As for waitpid().
154
155       WNOWAIT     Leave  the child in a waitable state; a later wait call can
156                   be used to again retrieve the child status information.
157
158       Upon successful return, waitid() fills in the following fields  of  the
159       siginfo_t structure pointed to by infop:
160
161       si_pid      The process ID of the child.
162
163       si_uid      The  real  user ID of the child.  (This field is not set on
164                   most other implementations.)
165
166       si_signo    Always set to SIGCHLD.
167
168       si_status   Either the exit status of the child, as given  to  _exit(2)
169                   (or exit(3)), or the signal that caused the child to termi‐
170                   nate, stop, or continue.  The si_code field can be used  to
171                   determine how to interpret this field.
172
173       si_code     Set   to   one  of:  CLD_EXITED  (child  called  _exit(2));
174                   CLD_KILLED (child  killed  by  signal);  CLD_DUMPED  (child
175                   killed  by  signal,  and  dumped  core); CLD_STOPPED (child
176                   stopped by signal); CLD_TRAPPED (traced child has trapped);
177                   or CLD_CONTINUED (child continued by SIGCONT).
178
179       If  WNOHANG  was  specified  in options and there were no children in a
180       waitable state, then waitid() returns 0 immediately and  the  state  of
181       the siginfo_t structure pointed to by infop is unspecified.  To distin‐
182       guish this case from that where a child was in a waitable  state,  zero
183       out  the  si_pid field before the call and check for a nonzero value in
184       this field after the call returns.
185

RETURN VALUE

187       wait(): on success, returns the process ID of the terminated child;  on
188       error, -1 is returned.
189
190       waitpid():  on success, returns the process ID of the child whose state
191       has changed; if WNOHANG was specified and one or more child(ren) speci‐
192       fied  by pid exist, but have not yet changed state, then 0 is returned.
193       On error, -1 is returned.
194
195       waitid(): returns 0 on success or  if  WNOHANG  was  specified  and  no
196       child(ren)  specified  by  id  has  yet  changed state; on error, -1 is
197       returned.  Each of these calls sets errno to an  appropriate  value  in
198       the case of an error.
199

ERRORS

201       ECHILD (for  wait()) The calling process does not have any unwaited-for
202              children.
203
204       ECHILD (for waitpid() or waitid()) The process specified by pid  (wait‐
205              pid())  or  idtype  and id (waitid()) does not exist or is not a
206              child of the calling process.  (This can happen  for  one's  own
207              child if the action for SIGCHLD is set to SIG_IGN.  See also the
208              Linux Notes section about threads.)
209
210       EINTR  WNOHANG was not set and an unblocked signal  or  a  SIGCHLD  was
211              caught; see signal(7).
212
213       EINVAL The options argument was invalid.
214

CONFORMING TO

216       SVr4, 4.3BSD, POSIX.1-2001.
217

NOTES

219       A  child  that  terminates, but has not been waited for becomes a "zom‐
220       bie".  The kernel maintains a minimal set of information about the zom‐
221       bie  process  (PID,  termination status, resource usage information) in
222       order to allow the parent to later perform a wait to obtain information
223       about  the  child.   As long as a zombie is not removed from the system
224       via a wait, it will consume a slot in the kernel process table, and  if
225       this  table fills, it will not be possible to create further processes.
226       If a parent process terminates, then its "zombie" children (if any) are
227       adopted  by  init(8), which automatically performs a wait to remove the
228       zombies.
229
230       POSIX.1-2001 specifies that if the disposition of  SIGCHLD  is  set  to
231       SIG_IGN or the SA_NOCLDWAIT flag is set for SIGCHLD (see sigaction(2)),
232       then children that terminate do not become zombies and a call to wait()
233       or  waitpid()  will  block until all children have terminated, and then
234       fail with errno set to ECHILD.  (The original POSIX standard  left  the
235       behavior  of  setting  SIGCHLD  to SIG_IGN unspecified.  Note that even
236       though the default disposition of SIGCHLD is "ignore", explicitly  set‐
237       ting  the disposition to SIG_IGN results in different treatment of zom‐
238       bie process children.)  Linux 2.6 conforms to this specification.  How‐
239       ever,  Linux  2.4 (and earlier) does not: if a wait() or waitpid() call
240       is made while SIGCHLD is being ignored, the call behaves just as though
241       SIGCHLD were not being ignored, that is, the call blocks until the next
242       child terminates and then returns the process ID  and  status  of  that
243       child.
244
245   Linux Notes
246       In  the  Linux kernel, a kernel-scheduled thread is not a distinct con‐
247       struct from a process.  Instead, a thread is simply a process  that  is
248       created  using  the  Linux-unique  clone(2) system call; other routines
249       such as the  portable  pthread_create(3)  call  are  implemented  using
250       clone(2).   Before  Linux  2.4,  a  thread was just a special case of a
251       process, and as a consequence one thread could not wait on the children
252       of  another  thread,  even  when  the latter belongs to the same thread
253       group.  However, POSIX prescribes such functionality, and  since  Linux
254       2.4  a  thread  can,  and  by  default  will, wait on children of other
255       threads in the same thread group.
256
257       The following Linux-specific options are for use with children  created
258       using clone(2); they cannot be used with waitid():
259
260       __WCLONE
261              Wait  for "clone" children only.  If omitted then wait for "non-
262              clone" children only.  (A "clone" child is one which delivers no
263              signal, or a signal other than SIGCHLD to its parent upon termi‐
264              nation.)  This option is ignored if __WALL is also specified.
265
266       __WALL (since Linux 2.4)
267              Wait for all children, regardless  of  type  ("clone"  or  "non-
268              clone").
269
270       __WNOTHREAD (since Linux 2.4)
271              Do  not  wait  for  children of other threads in the same thread
272              group.  This was the default before Linux 2.4.
273

EXAMPLE

275       The following program demonstrates the use of  fork(2)  and  waitpid().
276       The  program  creates  a child process.  If no command-line argument is
277       supplied to the program, then the child suspends  its  execution  using
278       pause(2),  to  allow the user to send signals to the child.  Otherwise,
279       if a command-line argument is supplied, then the  child  exits  immedi‐
280       ately,  using the integer supplied on the command line as the exit sta‐
281       tus.  The parent process executes a loop that monitors the child  using
282       waitpid(), and uses the W*() macros described above to analyze the wait
283       status value.
284
285       The following shell session demonstrates the use of the program:
286
287           $ ./a.out &
288           Child PID is 32360
289           [1] 32359
290           $ kill -STOP 32360
291           stopped by signal 19
292           $ kill -CONT 32360
293           continued
294           $ kill -TERM 32360
295           killed by signal 15
296           [1]+  Done                    ./a.out
297           $
298
299   Program source
300
301       #include <sys/wait.h>
302       #include <stdlib.h>
303       #include <unistd.h>
304       #include <stdio.h>
305
306       int
307       main(int argc, char *argv[])
308       {
309           pid_t cpid, w;
310           int status;
311
312           cpid = fork();
313           if (cpid == -1) {
314               perror("fork");
315               exit(EXIT_FAILURE);
316           }
317
318           if (cpid == 0) {            /* Code executed by child */
319               printf("Child PID is %ld\n", (long) getpid());
320               if (argc == 1)
321                   pause();                    /* Wait for signals */
322               _exit(atoi(argv[1]));
323
324           } else {                    /* Code executed by parent */
325               do {
326                   w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);
327                   if (w == -1) {
328                       perror("waitpid");
329                       exit(EXIT_FAILURE);
330                   }
331
332                   if (WIFEXITED(status)) {
333                       printf("exited, status=%d\n", WEXITSTATUS(status));
334                   } else if (WIFSIGNALED(status)) {
335                       printf("killed by signal %d\n", WTERMSIG(status));
336                   } else if (WIFSTOPPED(status)) {
337                       printf("stopped by signal %d\n", WSTOPSIG(status));
338                   } else if (WIFCONTINUED(status)) {
339                       printf("continued\n");
340                   }
341               } while (!WIFEXITED(status) && !WIFSIGNALED(status));
342               exit(EXIT_SUCCESS);
343           }
344       }
345

SEE ALSO

347       _exit(2), clone(2), fork(2),  kill(2),  ptrace(2),  sigaction(2),  sig‐
348       nal(2), wait4(2), pthread_create(3), credentials(7), signal(7)
349

COLOPHON

351       This  page  is  part of release 3.25 of the Linux man-pages project.  A
352       description of the project, and information about reporting  bugs,  can
353       be found at http://www.kernel.org/doc/man-pages/.
354
355
356
357Linux                             2009-04-21                           WAIT(2)
Impressum