1wait(2) System Calls Manual wait(2)
2
6 wait, waitpid, waitid - wait for process to change state
7
9 Standard C library (libc, -lc)
10
12 #include <sys/wait.h>
13 pid_t wait(int *_Nullable wstatus);
15 pid_t waitpid(pid_t pid, int *_Nullable wstatus, int options);
16 int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);
18 /* This is the glibc and POSIX interface; see
19 NOTES for information on the raw system call. */
20 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22 waitid():
24 Since glibc 2.26:
25 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
26 glibc 2.25 and earlier:
27 _XOPEN_SOURCE
28 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
29 || /* glibc <= 2.19: */ _BSD_SOURCE
30
32 All of these system calls are used to wait for state changes in a child
33 of the calling process, and obtain information about the child whose
34 state has changed. A state change is considered to be: the child ter‐
35 minated; the child was stopped by a signal; or the child was resumed by
36 a signal. In the case of a terminated child, performing a wait allows
37 the system to release the resources associated with the child; if a
38 wait is not performed, then the terminated child remains in a "zombie"
39 state (see NOTES below).
40 If a child has already changed state, then these calls return immedi‐
42 ately. Otherwise, they block until either a child changes state or a
43 signal handler interrupts the call (assuming that system calls are not
44 automatically restarted using the SA_RESTART flag of sigaction(2)). In
45 the remainder of this page, a child whose state has changed and which
46 has not yet been waited upon by one of these system calls is termed
47 waitable.
48 wait() and waitpid()
50 The wait() system call suspends execution of the calling thread until
51 one of its children terminates. The call wait(&wstatus) is equivalent
52 to:
53 waitpid(-1, &wstatus, 0);
55 The waitpid() system call suspends execution of the calling thread un‐
57 til a child specified by pid argument has changed state. By default,
58 waitpid() waits only for terminated children, but this behavior is mod‐
59 ifiable via the options argument, as described below.
60 The value of pid can be:
62 < -1 meaning wait for any child process whose process group ID is
64 equal to the absolute value of pid.
65 -1 meaning wait for any child process.
67 0 meaning wait for any child process whose process group ID is
69 equal to that of the calling process at the time of the call to
70 waitpid().
71 > 0 meaning wait for the child whose process ID is equal to the
73 value of pid.
74 The value of options is an OR of zero or more of the following con‐
76 stants:
77 WNOHANG
79 return immediately if no child has exited.
80 WUNTRACED
82 also return if a child has stopped (but not traced via
83 ptrace(2)). Status for traced children which have stopped is
84 provided even if this option is not specified.
85 WCONTINUED (since Linux 2.6.10)
87 also return if a stopped child has been resumed by delivery of
88 SIGCONT.
89 (For Linux-only options, see below.)
91 If wstatus is not NULL, wait() and waitpid() store status information
93 in the int to which it points. This integer can be inspected with the
94 following macros (which take the integer itself as an argument, not a
95 pointer to it, as is done in wait() and waitpid()!):
96 WIFEXITED(wstatus)
98 returns true if the child terminated normally, that is, by call‐
99 ing exit(3) or _exit(2), or by returning from main().
100 WEXITSTATUS(wstatus)
102 returns the exit status of the child. This consists of the
103 least significant 8 bits of the status argument that the child
104 specified in a call to exit(3) or _exit(2) or as the argument
105 for a return statement in main(). This macro should be employed
106 only if WIFEXITED returned true.
107 WIFSIGNALED(wstatus)
109 returns true if the child process was terminated by a signal.
110 WTERMSIG(wstatus)
112 returns the number of the signal that caused the child process
113 to terminate. This macro should be employed only if WIFSIGNALED
114 returned true.
115 WCOREDUMP(wstatus)
117 returns true if the child produced a core dump (see core(5)).
118 This macro should be employed only if WIFSIGNALED returned true.
119 This macro is not specified in POSIX.1-2001 and is not available
121 on some UNIX implementations (e.g., AIX, SunOS). Therefore, en‐
122 close its use inside #ifdef WCOREDUMP ... #endif.
123 WIFSTOPPED(wstatus)
125 returns true if the child process was stopped by delivery of a
126 signal; this is possible only if the call was done using WUN‐
127 TRACED or when the child is being traced (see ptrace(2)).
128 WSTOPSIG(wstatus)
130 returns the number of the signal which caused the child to stop.
131 This macro should be employed only if WIFSTOPPED returned true.
132 WIFCONTINUED(wstatus)
134 (since Linux 2.6.10) returns true if the child process was re‐
135 sumed by delivery of SIGCONT.
136 waitid()
138 The waitid() system call (available since Linux 2.6.9) provides more
139 precise control over which child state changes to wait for.
140 The idtype and id arguments select the child(ren) to wait for, as fol‐
142 lows:
143 idtype == P_PID
145 Wait for the child whose process ID matches id.
146 idtype == P_PIDFD (since Linux 5.4)
148 Wait for the child referred to by the PID file descriptor speci‐
149 fied in id. (See pidfd_open(2) for further information on PID
150 file descriptors.)
151 idtype == P_PGID
153 Wait for any child whose process group ID matches id. Since
154 Linux 5.4, if id is zero, then wait for any child that is in the
155 same process group as the caller's process group at the time of
156 the call.
157 idtype == P_ALL
159 Wait for any child; id is ignored.
160 The child state changes to wait for are specified by ORing one or more
162 of the following flags in options:
163 WEXITED
165 Wait for children that have terminated.
166 WSTOPPED
168 Wait for children that have been stopped by delivery of a sig‐
169 nal.
170 WCONTINUED
172 Wait for (previously stopped) children that have been resumed by
173 delivery of SIGCONT.
174 The following flags may additionally be ORed in options:
176 WNOHANG
178 As for waitpid().
179 WNOWAIT
181 Leave the child in a waitable state; a later wait call can be
182 used to again retrieve the child status information.
183 Upon successful return, waitid() fills in the following fields of the
185 siginfo_t structure pointed to by infop:
186 si_pid The process ID of the child.
188 si_uid The real user ID of the child. (This field is not set on most
190 other implementations.)
191 si_signo
193 Always set to SIGCHLD.
194 si_status
196 Either the exit status of the child, as given to _exit(2) (or
197 exit(3)), or the signal that caused the child to terminate,
198 stop, or continue. The si_code field can be used to determine
199 how to interpret this field.
200 si_code
202 Set to one of: CLD_EXITED (child called _exit(2)); CLD_KILLED
203 (child killed by signal); CLD_DUMPED (child killed by signal,
204 and dumped core); CLD_STOPPED (child stopped by signal);
205 CLD_TRAPPED (traced child has trapped); or CLD_CONTINUED (child
206 continued by SIGCONT).
207 If WNOHANG was specified in options and there were no children in a
209 waitable state, then waitid() returns 0 immediately and the state of
210 the siginfo_t structure pointed to by infop depends on the implementa‐
211 tion. To (portably) distinguish this case from that where a child was
212 in a waitable state, zero out the si_pid field before the call and
213 check for a nonzero value in this field after the call returns.
214 POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that
216 when WNOHANG is specified in options and there were no children in a
217 waitable state, then waitid() should zero out the si_pid and si_signo
218 fields of the structure. On Linux and other implementations that ad‐
219 here to this requirement, it is not necessary to zero out the si_pid
220 field before calling waitid(). However, not all implementations follow
221 the POSIX.1 specification on this point.
222
224 wait(): on success, returns the process ID of the terminated child; on
225 failure, -1 is returned.
226 waitpid(): on success, returns the process ID of the child whose state
228 has changed; if WNOHANG was specified and one or more child(ren) speci‐
229 fied by pid exist, but have not yet changed state, then 0 is returned.
230 On failure, -1 is returned.
231 waitid(): returns 0 on success or if WNOHANG was specified and no
233 child(ren) specified by id has yet changed state; on failure, -1 is re‐
234 turned.
235 On failure, each of these calls sets errno to indicate the error.
237
239 EAGAIN The PID file descriptor specified in id is nonblocking and the
240 process that it refers to has not terminated.
241 ECHILD (for wait()) The calling process does not have any unwaited-for
243 children.
244 ECHILD (for waitpid() or waitid()) The process specified by pid (wait‐
246 pid()) or idtype and id (waitid()) does not exist or is not a
247 child of the calling process. (This can happen for one's own
248 child if the action for SIGCHLD is set to SIG_IGN. See also the
249 Linux Notes section about threads.)
250 EINTR WNOHANG was not set and an unblocked signal or a SIGCHLD was
252 caught; see signal(7).
253 EINVAL The options argument was invalid.
255 ESRCH (for wait() or waitpid()) pid is equal to INT_MIN.
257
259 C library/kernel differences
260 wait() is actually a library function that (in glibc) is implemented as
261 a call to wait4(2).
262 On some architectures, there is no waitpid() system call; instead, this
264 interface is implemented via a C library wrapper function that calls
265 wait4(2).
266 The raw waitid() system call takes a fifth argument, of type struct
268 rusage *. If this argument is non-NULL, then it is used to return re‐
269 source usage information about the child, in the same manner as
270 wait4(2). See getrusage(2) for details.
271
273 POSIX.1-2008.
274
276 SVr4, 4.3BSD, POSIX.1-2001.
277
279 A child that terminates, but has not been waited for becomes a "zom‐
280 bie". The kernel maintains a minimal set of information about the zom‐
281 bie process (PID, termination status, resource usage information) in
282 order to allow the parent to later perform a wait to obtain information
283 about the child. As long as a zombie is not removed from the system
284 via a wait, it will consume a slot in the kernel process table, and if
285 this table fills, it will not be possible to create further processes.
286 If a parent process terminates, then its "zombie" children (if any) are
287 adopted by init(1), (or by the nearest "subreaper" process as defined
288 through the use of the prctl(2) PR_SET_CHILD_SUBREAPER operation);
289 init(1) automatically performs a wait to remove the zombies.
290 POSIX.1-2001 specifies that if the disposition of SIGCHLD is set to
292 SIG_IGN or the SA_NOCLDWAIT flag is set for SIGCHLD (see sigaction(2)),
293 then children that terminate do not become zombies and a call to wait()
294 or waitpid() will block until all children have terminated, and then
295 fail with errno set to ECHILD. (The original POSIX standard left the
296 behavior of setting SIGCHLD to SIG_IGN unspecified. Note that even
297 though the default disposition of SIGCHLD is "ignore", explicitly set‐
298 ting the disposition to SIG_IGN results in different treatment of zom‐
299 bie process children.)
300 Linux 2.6 conforms to the POSIX requirements. However, Linux 2.4 (and
302 earlier) does not: if a wait() or waitpid() call is made while SIGCHLD
303 is being ignored, the call behaves just as though SIGCHLD were not be‐
304 ing ignored, that is, the call blocks until the next child terminates
305 and then returns the process ID and status of that child.
306 Linux notes
308 In the Linux kernel, a kernel-scheduled thread is not a distinct con‐
309 struct from a process. Instead, a thread is simply a process that is
310 created using the Linux-unique clone(2) system call; other routines
311 such as the portable pthread_create(3) call are implemented using
312 clone(2). Before Linux 2.4, a thread was just a special case of a
313 process, and as a consequence one thread could not wait on the children
314 of another thread, even when the latter belongs to the same thread
315 group. However, POSIX prescribes such functionality, and since Linux
316 2.4 a thread can, and by default will, wait on children of other
317 threads in the same thread group.
318 The following Linux-specific options are for use with children created
320 using clone(2); they can also, since Linux 4.7, be used with waitid():
321 __WCLONE
323 Wait for "clone" children only. If omitted, then wait for "non-
324 clone" children only. (A "clone" child is one which delivers no
325 signal, or a signal other than SIGCHLD to its parent upon termi‐
326 nation.) This option is ignored if __WALL is also specified.
327 __WALL (since Linux 2.4)
329 Wait for all children, regardless of type ("clone" or "non-
330 clone").
331 __WNOTHREAD (since Linux 2.4)
333 Do not wait for children of other threads in the same thread
334 group. This was the default before Linux 2.4.
335 Since Linux 4.7, the __WALL flag is automatically implied if the child
337 is being ptraced.
338
340 According to POSIX.1-2008, an application calling waitid() must ensure
341 that infop points to a siginfo_t structure (i.e., that it is a non-null
342 pointer). On Linux, if infop is NULL, waitid() succeeds, and returns
343 the process ID of the waited-for child. Applications should avoid re‐
344 lying on this inconsistent, nonstandard, and unnecessary feature.
345
347 The following program demonstrates the use of fork(2) and waitpid().
348 The program creates a child process. If no command-line argument is
349 supplied to the program, then the child suspends its execution using
350 pause(2), to allow the user to send signals to the child. Otherwise,
351 if a command-line argument is supplied, then the child exits immedi‐
352 ately, using the integer supplied on the command line as the exit sta‐
353 tus. The parent process executes a loop that monitors the child using
354 waitpid(), and uses the W*() macros described above to analyze the wait
355 status value.
356 The following shell session demonstrates the use of the program:
358 $ ./a.out &
360 Child PID is 32360
361 [1] 32359
362 $ kill -STOP 32360
363 stopped by signal 19
364 $ kill -CONT 32360
365 continued
366 $ kill -TERM 32360
367 killed by signal 15
368 [1]+ Done ./a.out
369 $
370 Program source
372 #include <stdint.h>
374 #include <stdio.h>
375 #include <stdlib.h>
376 #include <sys/wait.h>
377 #include <unistd.h>
378 int
380 main(int argc, char *argv[])
381 {
382 int wstatus;
383 pid_t cpid, w;
384 cpid = fork();
386 if (cpid == -1) {
387 perror("fork");
388 exit(EXIT_FAILURE);
389 }
390 if (cpid == 0) { /* Code executed by child */
392 printf("Child PID is %jd\n", (intmax_t) getpid());
393 if (argc == 1)
394 pause(); /* Wait for signals */
395 _exit(atoi(argv[1]));
396 } else { /* Code executed by parent */
398 do {
399 w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED);
400 if (w == -1) {
401 perror("waitpid");
402 exit(EXIT_FAILURE);
403 }
404 if (WIFEXITED(wstatus)) {
406 printf("exited, status=%d\n", WEXITSTATUS(wstatus));
407 } else if (WIFSIGNALED(wstatus)) {
408 printf("killed by signal %d\n", WTERMSIG(wstatus));
409 } else if (WIFSTOPPED(wstatus)) {
410 printf("stopped by signal %d\n", WSTOPSIG(wstatus));
411 } else if (WIFCONTINUED(wstatus)) {
412 printf("continued\n");
413 }
414 } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus));
415 exit(EXIT_SUCCESS);
416 }
417 }
418
420 _exit(2), clone(2), fork(2), kill(2), ptrace(2), sigaction(2), sig‐
421 nal(2), wait4(2), pthread_create(3), core(5), credentials(7), signal(7)
422Linux man-pages 6.05 2023-05-03 wait(2)