1waitpid(3C) Standard C Library Functions waitpid(3C)
2
3
4
6 waitpid - wait for child process to change state
7
9 #include <sys/types.h>
10 #include <sys/wait.h>
11
12 pid_t waitpid(pid_t pid, int *stat_loc, int options);
13
14
16 The waitpid() function will suspend execution of the calling thread
17 until status information for one of its terminated child processes is
18 available, or until delivery of a signal whose action is either to exe‐
19 cute a signal-catching function or to terminate the process. If more
20 than one thread is suspended in waitpid(), wait(3C), or waitid(2)
21 awaiting termination of the same process, exactly one thread will
22 return the process status at the time of the target process termina‐
23 tion. If status information is available prior to the call to wait‐
24 pid(), return will be immediate.
25
26
27 The pid argument specifies a set of child processes for which status is
28 requested, as follows:
29
30 o If pid is less than (pid_t)−1, status is requested for any
31 child process whose process group ID is equal to the abso‐
32 lute value of pid.
33
34 o If pid is equal to (pid_t)−1, status is requested for any
35 child process.
36
37 o If pid is equal to (pid_t)0 status is requested for any
38 child process whose process group ID is equal to that of
39 the calling process.
40
41 o If pid is greater than (pid_t)0, it specifies the process
42 ID of the child process for which status is requested.
43
44
45 One instance of a SIGCHLD signal is queued for each child process whose
46 status has changed. If waitpid() returns because the status of a child
47 process is available, and WNOWAIT was not specified in options, any
48 pending SIGCHLD signal associated with the process ID of that child
49 process is discarded. Any other pending SIGCHLD signals remain pending.
50
51
52 If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to
53 SIG_IGN and the process has no unwaited children that were transformed
54 into zombie processes, it will block until all of its children termi‐
55 nate, and waitpid() will fail and set errno to ECHILD.
56
57
58 If waitpid() returns because the status of a child process is avail‐
59 able, then that status may be evaluated with the macros defined by
60 wait.h(3HEAD) If the calling process had specified a non-zero value of
61 stat_loc, the status of the child process will be stored in the loca‐
62 tion pointed to by stat_loc.
63
64
65 The options argument is constructed from the bitwise-inclusive OR of
66 zero or more of the following flags, defined in the header
67 <sys/wait.h>:
68
69 WCONTINUED The status of any continued child process specified by
70 pid, whose status has not been reported since it contin‐
71 ued, is also reported to the calling process.
72
73
74 WNOHANG The waitpid() function will not suspend execution of the
75 calling process if status is not immediately available
76 for one of the child processes specified by pid.
77
78
79 WNOWAIT Keep the process whose status is returned in stat_loc in
80 a waitable state. The process may be waited for again
81 with identical results.
82
83
84 WUNTRACED The status of any child processes specified by pid that
85 are stopped, and whose status has not yet been reported
86 since they stopped, is also reported to the calling
87 process. WSTOPPED is a synonym for WUNTRACED.
88
89
91 If waitpid() returns because the status of a child process is avail‐
92 able, it returns a value equal to the process ID of the child process
93 for which status is reported. If waitpid() returns due to the delivery
94 of a signal to the calling process, −1 is returned and errno is set to
95 EINTR. If waitpid() was invoked with WNOHANG set in options, it has at
96 least one child process specified by pid for which status is not avail‐
97 able, and status is not available for any process specified by pid,
98 then 0 is returned. Otherwise, −1 is returned and errno is set to
99 indicate the error.
100
102 The waitpid() function will fail if:
103
104 ECHILD The process or process group specified by pid does not exist
105 or is not a child of the calling process or can never be in
106 the states specified by options.
107
108
109 EINTR The waitpid() function was interrupted due to the receipt of
110 a signal sent by the calling process.
111
112
113 EINVAL An invalid value was specified for options.
114
115
117 With options equal to 0 and pid equal to (pid_t)−1, waitpid() is iden‐
118 tical to wait(3C). The waitpid() function is implemented as a call to
119 the more general waitid(2) function.
120
122 See attributes(5) for descriptions of the following attributes:
123
124
125
126
127 ┌─────────────────────────────┬─────────────────────────────┐
128 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
129 ├─────────────────────────────┼─────────────────────────────┤
130 │Interface Stability │Committed │
131 ├─────────────────────────────┼─────────────────────────────┤
132 │MT-Level │Async-Signal-Safe │
133 ├─────────────────────────────┼─────────────────────────────┤
134 │Standard │See standards(5). │
135 └─────────────────────────────┴─────────────────────────────┘
136
138 Intro(2), exec(2), exit(2), fork(2), pause(2), sigaction(2),
139 ptrace(3C), signal(3C), siginfo.h(3HEAD), wait(3C), wait.h(3HEAD),
140 attributes(5), standards(5)
141
142
143
144SunOS 5.11 7 Dec 2007 waitpid(3C)