Commit | Line | Data |
---|---|---|
15715acc KB |
1 | .\" Copyright (c) 1980, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
775a8be6 | 3 | .\" |
ad787160 C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
775a8be6 | 19 | .\" |
ad787160 C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
931b8415 | 31 | .\" |
ad787160 C |
32 | .\" @(#)wait.2 8.1 (Berkeley) 6/4/93 |
33 | .\" | |
34 | .Dd June 4, 1993 | |
931b8415 CL |
35 | .Dt WAIT 2 |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm wait , | |
39 | .Nm waitpid , | |
40 | .Nm wait4 , | |
41 | .Nm wait3 | |
42 | .Nd wait for process terminatation | |
43 | .Sh SYNOPSIS | |
44 | .Fd #include <sys/types.h> | |
45 | .Fd #include <sys/wait.h> | |
46 | .Ft pid_t | |
47 | .Fn wait "int *status" | |
48 | .Fd #include <sys/time.h> | |
49 | .Fd #include <sys/resource.h> | |
50 | .Ft pid_t | |
51 | .Fn waitpid "pid_t wpid" "int *status" "int options" | |
52 | .Ft pid_t | |
53 | .Fn wait3 "int *status" "int options" "struct rusage *rusage" | |
54 | .Ft pid_t | |
55 | .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" | |
56 | .Sh DESCRIPTION | |
57 | The | |
58 | .Fn wait | |
59 | function suspends execution of its calling process until | |
60 | .Fa status | |
61 | information is available for a terminated child process, | |
62 | or a signal is received. | |
28494293 | 63 | On return from a successful |
931b8415 CL |
64 | .Fn wait |
65 | call, | |
66 | the | |
67 | .Fa status | |
68 | area contains termination information about the process that exited | |
84d15ab6 | 69 | as defined below. |
931b8415 | 70 | .Pp |
84d15ab6 | 71 | The |
931b8415 | 72 | .Fn wait4 |
84d15ab6 | 73 | call provides a more general interface for programs |
931b8415 CL |
74 | that need to wait for certain child processes, |
75 | that need resource utilization statistics accummulated by child processes, | |
84d15ab6 MK |
76 | or that require options. |
77 | The other wait functions are implemented using | |
931b8415 CL |
78 | .Fn wait4 . |
79 | .Pp | |
84d15ab6 | 80 | The |
931b8415 | 81 | .Fa wpid |
84d15ab6 MK |
82 | parameter specifies the set of child processes for which to wait. |
83 | If | |
931b8415 CL |
84 | .Fa wpid |
85 | is -1, the call waits for any child process. | |
84d15ab6 | 86 | If |
931b8415 | 87 | .Fa wpid |
84d15ab6 MK |
88 | is 0, |
89 | the call waits for any child process in the process group of the caller. | |
90 | If | |
931b8415 | 91 | .Fa wpid |
84d15ab6 | 92 | is greater than zero, the call waits for the process with process id |
931b8415 | 93 | .Fa wpid . |
84d15ab6 | 94 | If |
931b8415 CL |
95 | .Fa wpid |
96 | is less than -1, the call waits for any process whose process group id | |
84d15ab6 | 97 | equals the absolute value of |
931b8415 CL |
98 | .Fa wpid . |
99 | .Pp | |
84d15ab6 | 100 | The |
931b8415 | 101 | .Fa status |
84d15ab6 | 102 | parameter is defined below. The |
931b8415 | 103 | .Fa options |
84d15ab6 | 104 | parameter contains the bitwise OR of any of the following options. |
931b8415 CL |
105 | The |
106 | .Dv WNOHANG | |
107 | option | |
84d15ab6 MK |
108 | is used to indicate that the call should not block if |
109 | there are no processes that wish to report status. | |
931b8415 CL |
110 | If the |
111 | .Dv WUNTRACED | |
112 | option is set, | |
84d15ab6 | 113 | children of the current process that are stopped |
931b8415 CL |
114 | due to a |
115 | .Dv SIGTTIN , SIGTTOU , SIGTSTP , | |
116 | or | |
117 | .Dv SIGSTOP | |
118 | signal also have | |
84d15ab6 | 119 | their status reported. |
931b8415 | 120 | .Pp |
84d15ab6 | 121 | If |
931b8415 | 122 | .Fa rusage |
28494293 KM |
123 | is non-zero, a summary of the resources used by the terminated |
124 | process and all its | |
125 | children is returned (this information is currently not available | |
126 | for stopped processes). | |
931b8415 CL |
127 | .Pp |
128 | When the | |
129 | .Dv WNOHANG | |
130 | option is specified and no processes | |
28494293 | 131 | wish to report status, |
931b8415 | 132 | .Fn wait4 |
28494293 | 133 | returns a |
931b8415 | 134 | process id |
84d15ab6 | 135 | of 0. |
931b8415 | 136 | .Pp |
84d15ab6 | 137 | The |
931b8415 | 138 | .Fn waitpid |
84d15ab6 | 139 | call is identical to |
931b8415 | 140 | .Fn wait4 |
84d15ab6 | 141 | with an |
931b8415 | 142 | .Fa rusage |
84d15ab6 MK |
143 | value of zero. |
144 | The older | |
931b8415 | 145 | .Fn wait3 |
84d15ab6 | 146 | call is the same as |
931b8415 | 147 | .Fn wait4 |
84d15ab6 | 148 | with a |
931b8415 CL |
149 | .Fa wpid |
150 | value of -1. | |
151 | .Pp | |
152 | The following macros may be used to test the manner of exit of the process. | |
84d15ab6 | 153 | One of the first three macros will evaluate to a non-zero (true) value: |
931b8415 CL |
154 | .Bl -tag -width Ds |
155 | .It Fn WIFEXITED status | |
84d15ab6 | 156 | True if the process terminated normally by a call to |
931b8415 | 157 | .Xr _exit 2 |
84d15ab6 | 158 | or |
931b8415 CL |
159 | .Xr exit 2 . |
160 | .It Fn WIFSIGNALED status | |
84d15ab6 | 161 | True if the process terminated due to receipt of a signal. |
931b8415 | 162 | .It Fn WIFSTOPPED status |
84d15ab6 MK |
163 | True if the process has not terminated, but has stopped and can be restarted. |
164 | This macro can be true only if the wait call specified the | |
931b8415 | 165 | .Dv WUNTRACED |
84d15ab6 MK |
166 | option |
167 | or if the child process is being traced (see | |
931b8415 CL |
168 | .Xr ptrace 2 ) . |
169 | .El | |
170 | .Pp | |
84d15ab6 MK |
171 | Depending on the values of those macros, the following macros |
172 | produce the remaining status information about the child process: | |
931b8415 CL |
173 | .Bl -tag -width Ds |
174 | .It Fn WEXITSTATUS status | |
175 | If | |
176 | .Fn WIFEXITED status | |
177 | is true, evaluates to the low-order 8 bits | |
84d15ab6 | 178 | of the argument passed to |
931b8415 | 179 | .Xr _exit 2 |
84d15ab6 | 180 | or |
931b8415 | 181 | .Xr exit 2 |
84d15ab6 | 182 | by the child. |
931b8415 CL |
183 | .It Fn WTERMSIG status |
184 | If | |
185 | .Fn WIFSIGNALED status | |
186 | is true, evaluates to the number of the signal | |
84d15ab6 | 187 | that caused the termination of the process. |
931b8415 CL |
188 | .It Fn WCOREDUMP status |
189 | If | |
190 | .Fn WIFSIGNALED status | |
191 | is true, evaluates as true if the termination | |
84d15ab6 MK |
192 | of the process was accompanied by the creation of a core file |
193 | containing an image of the process when the signal was received. | |
931b8415 CL |
194 | .It Fn WSTOPSIG status |
195 | If | |
196 | .Fn WIFSTOPPED status | |
197 | is true, evaluates to the number of the signal | |
84d15ab6 | 198 | that caused the process to stop. |
931b8415 CL |
199 | .El |
200 | .Sh NOTES | |
775a8be6 | 201 | See |
931b8415 | 202 | .Xr sigaction 2 |
84d15ab6 MK |
203 | for a list of termination signals. |
204 | A status of 0 indicates normal termination. | |
931b8415 CL |
205 | .Pp |
206 | If a parent process terminates without | |
207 | waiting for all of its child processes to terminate, | |
208 | the remaining child processes are assigned the parent | |
209 | process 1 ID (the init process ID). | |
210 | .Pp | |
84d15ab6 | 211 | If a signal is caught while any of the |
931b8415 | 212 | .Fn wait |
84d15ab6 MK |
213 | calls is pending, |
214 | the call may be interrupted or restarted when the signal-catching routine | |
215 | returns, | |
216 | depending on the options in effect for the signal; | |
217 | see | |
931b8415 | 218 | .Xr intro 2 , |
84d15ab6 | 219 | System call restart. |
931b8415 CL |
220 | .Sh RETURN VALUES |
221 | If | |
222 | .Fn wait | |
223 | returns due to a stopped | |
28494293 | 224 | or terminated child process, the process ID of the child |
931b8415 CL |
225 | is returned to the calling process. Otherwise, a value of -1 |
226 | is returned and | |
227 | .Va errno | |
228 | is set to indicate the error. | |
229 | .Pp | |
84d15ab6 | 230 | If |
931b8415 CL |
231 | .Fn wait4 , |
232 | .Fn wait3 | |
84d15ab6 | 233 | or |
931b8415 | 234 | .Fn waitpid |
84d15ab6 MK |
235 | returns due to a stopped |
236 | or terminated child process, the process ID of the child | |
237 | is returned to the calling process. | |
238 | If there are no children not previously awaited, | |
931b8415 CL |
239 | -1 is returned with |
240 | .Va errno | |
241 | set to | |
242 | .Bq Er ECHILD . | |
243 | Otherwise, if | |
244 | .Dv WNOHANG | |
245 | is specified and there are | |
84d15ab6 MK |
246 | no stopped or exited children, |
247 | 0 is returned. | |
248 | If an error is detected or a caught signal aborts the call, | |
931b8415 CL |
249 | a value of -1 |
250 | is returned and | |
251 | .Va errno | |
252 | is set to indicate the error. | |
253 | .Sh ERRORS | |
254 | .Fn Wait | |
255 | will fail and return immediately if: | |
256 | .Bl -tag -width Er | |
257 | .It Bq Er ECHILD | |
28494293 KM |
258 | The calling process has no existing unwaited-for |
259 | child processes. | |
931b8415 CL |
260 | .It Bq Er EFAULT |
261 | The | |
262 | .Fa status | |
263 | or | |
264 | .Fa rusage | |
265 | arguments point to an illegal address. | |
84d15ab6 | 266 | (May not be detected before exit of a child process.) |
931b8415 | 267 | .It Bq Er EINTR |
84d15ab6 | 268 | The call was interrupted by a caught signal, |
931b8415 CL |
269 | or the signal did not have the |
270 | .Dv SA_RESTART | |
271 | flag set. | |
272 | .El | |
273 | .Sh STANDARDS | |
84d15ab6 | 274 | The |
931b8415 | 275 | .Fn wait |
84d15ab6 | 276 | and |
931b8415 | 277 | .Fn waitpid |
84d15ab6 | 278 | functions are defined by POSIX; |
931b8415 | 279 | .Fn wait4 |
84d15ab6 | 280 | and |
931b8415 | 281 | .Fn wait3 |
84d15ab6 | 282 | are not specified by POSIX. |
931b8415 CL |
283 | The |
284 | .Fn WCOREDUMP | |
285 | macro | |
84d15ab6 | 286 | and the ability to restart a pending |
931b8415 | 287 | .Fn wait |
84d15ab6 | 288 | call are extensions to the POSIX interface. |
931b8415 CL |
289 | .Sh SEE ALSO |
290 | .Xr exit 2 , | |
291 | .Xr sigaction 2 | |
292 | .Sh HISTORY | |
293 | A | |
294 | .Nm | |
295 | function call appeared in Version 6 AT&T UNIX. |