Commit | Line | Data |
---|---|---|
a863413e | 1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
931b8415 | 2 | .\" All rights reserved. |
775a8be6 | 3 | .\" |
931b8415 | 4 | .\" %sccs.include.redist.man% |
775a8be6 | 5 | .\" |
931b8415 CL |
6 | .\" @(#)wait.2 6.5 (Berkeley) %G% |
7 | .\" | |
8 | .Dd | |
9 | .Dt WAIT 2 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm wait , | |
13 | .Nm waitpid , | |
14 | .Nm wait4 , | |
15 | .Nm wait3 | |
16 | .Nd wait for process terminatation | |
17 | .Sh SYNOPSIS | |
18 | .Fd #include <sys/types.h> | |
19 | .Fd #include <sys/wait.h> | |
20 | .Ft pid_t | |
21 | .Fn wait "int *status" | |
22 | .Fd #include <sys/time.h> | |
23 | .Fd #include <sys/resource.h> | |
24 | .Ft pid_t | |
25 | .Fn waitpid "pid_t wpid" "int *status" "int options" | |
26 | .Ft pid_t | |
27 | .Fn wait3 "int *status" "int options" "struct rusage *rusage" | |
28 | .Ft pid_t | |
29 | .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" | |
30 | .Sh DESCRIPTION | |
31 | The | |
32 | .Fn wait | |
33 | function suspends execution of its calling process until | |
34 | .Fa status | |
35 | information is available for a terminated child process, | |
36 | or a signal is received. | |
28494293 | 37 | On return from a successful |
931b8415 CL |
38 | .Fn wait |
39 | call, | |
40 | the | |
41 | .Fa status | |
42 | area contains termination information about the process that exited | |
84d15ab6 | 43 | as defined below. |
931b8415 | 44 | .Pp |
84d15ab6 | 45 | The |
931b8415 | 46 | .Fn wait4 |
84d15ab6 | 47 | call provides a more general interface for programs |
931b8415 CL |
48 | that need to wait for certain child processes, |
49 | that need resource utilization statistics accummulated by child processes, | |
84d15ab6 MK |
50 | or that require options. |
51 | The other wait functions are implemented using | |
931b8415 CL |
52 | .Fn wait4 . |
53 | .Pp | |
84d15ab6 | 54 | The |
931b8415 | 55 | .Fa wpid |
84d15ab6 MK |
56 | parameter specifies the set of child processes for which to wait. |
57 | If | |
931b8415 CL |
58 | .Fa wpid |
59 | is -1, the call waits for any child process. | |
84d15ab6 | 60 | If |
931b8415 | 61 | .Fa wpid |
84d15ab6 MK |
62 | is 0, |
63 | the call waits for any child process in the process group of the caller. | |
64 | If | |
931b8415 | 65 | .Fa wpid |
84d15ab6 | 66 | is greater than zero, the call waits for the process with process id |
931b8415 | 67 | .Fa wpid . |
84d15ab6 | 68 | If |
931b8415 CL |
69 | .Fa wpid |
70 | is less than -1, the call waits for any process whose process group id | |
84d15ab6 | 71 | equals the absolute value of |
931b8415 CL |
72 | .Fa wpid . |
73 | .Pp | |
84d15ab6 | 74 | The |
931b8415 | 75 | .Fa status |
84d15ab6 | 76 | parameter is defined below. The |
931b8415 | 77 | .Fa options |
84d15ab6 | 78 | parameter contains the bitwise OR of any of the following options. |
931b8415 CL |
79 | The |
80 | .Dv WNOHANG | |
81 | option | |
84d15ab6 MK |
82 | is used to indicate that the call should not block if |
83 | there are no processes that wish to report status. | |
931b8415 CL |
84 | If the |
85 | .Dv WUNTRACED | |
86 | option is set, | |
84d15ab6 | 87 | children of the current process that are stopped |
931b8415 CL |
88 | due to a |
89 | .Dv SIGTTIN , SIGTTOU , SIGTSTP , | |
90 | or | |
91 | .Dv SIGSTOP | |
92 | signal also have | |
84d15ab6 | 93 | their status reported. |
931b8415 | 94 | .Pp |
84d15ab6 | 95 | If |
931b8415 | 96 | .Fa rusage |
28494293 KM |
97 | is non-zero, a summary of the resources used by the terminated |
98 | process and all its | |
99 | children is returned (this information is currently not available | |
100 | for stopped processes). | |
931b8415 CL |
101 | .Pp |
102 | When the | |
103 | .Dv WNOHANG | |
104 | option is specified and no processes | |
28494293 | 105 | wish to report status, |
931b8415 | 106 | .Fn wait4 |
28494293 | 107 | returns a |
931b8415 | 108 | process id |
84d15ab6 | 109 | of 0. |
931b8415 | 110 | .Pp |
84d15ab6 | 111 | The |
931b8415 | 112 | .Fn waitpid |
84d15ab6 | 113 | call is identical to |
931b8415 | 114 | .Fn wait4 |
84d15ab6 | 115 | with an |
931b8415 | 116 | .Fa rusage |
84d15ab6 MK |
117 | value of zero. |
118 | The older | |
931b8415 | 119 | .Fn wait3 |
84d15ab6 | 120 | call is the same as |
931b8415 | 121 | .Fn wait4 |
84d15ab6 | 122 | with a |
931b8415 CL |
123 | .Fa wpid |
124 | value of -1. | |
125 | .Pp | |
126 | The following macros may be used to test the manner of exit of the process. | |
84d15ab6 | 127 | One of the first three macros will evaluate to a non-zero (true) value: |
931b8415 CL |
128 | .Bl -tag -width Ds |
129 | .It Fn WIFEXITED status | |
84d15ab6 | 130 | True if the process terminated normally by a call to |
931b8415 | 131 | .Xr _exit 2 |
84d15ab6 | 132 | or |
931b8415 CL |
133 | .Xr exit 2 . |
134 | .It Fn WIFSIGNALED status | |
84d15ab6 | 135 | True if the process terminated due to receipt of a signal. |
931b8415 | 136 | .It Fn WIFSTOPPED status |
84d15ab6 MK |
137 | True if the process has not terminated, but has stopped and can be restarted. |
138 | This macro can be true only if the wait call specified the | |
931b8415 | 139 | .Dv WUNTRACED |
84d15ab6 MK |
140 | option |
141 | or if the child process is being traced (see | |
931b8415 CL |
142 | .Xr ptrace 2 ) . |
143 | .El | |
144 | .Pp | |
84d15ab6 MK |
145 | Depending on the values of those macros, the following macros |
146 | produce the remaining status information about the child process: | |
931b8415 CL |
147 | .Bl -tag -width Ds |
148 | .It Fn WEXITSTATUS status | |
149 | If | |
150 | .Fn WIFEXITED status | |
151 | is true, evaluates to the low-order 8 bits | |
84d15ab6 | 152 | of the argument passed to |
931b8415 | 153 | .Xr _exit 2 |
84d15ab6 | 154 | or |
931b8415 | 155 | .Xr exit 2 |
84d15ab6 | 156 | by the child. |
931b8415 CL |
157 | .It Fn WTERMSIG status |
158 | If | |
159 | .Fn WIFSIGNALED status | |
160 | is true, evaluates to the number of the signal | |
84d15ab6 | 161 | that caused the termination of the process. |
931b8415 CL |
162 | .It Fn WCOREDUMP status |
163 | If | |
164 | .Fn WIFSIGNALED status | |
165 | is true, evaluates as true if the termination | |
84d15ab6 MK |
166 | of the process was accompanied by the creation of a core file |
167 | containing an image of the process when the signal was received. | |
931b8415 CL |
168 | .It Fn WSTOPSIG status |
169 | If | |
170 | .Fn WIFSTOPPED status | |
171 | is true, evaluates to the number of the signal | |
84d15ab6 | 172 | that caused the process to stop. |
931b8415 CL |
173 | .El |
174 | .Sh NOTES | |
775a8be6 | 175 | See |
931b8415 | 176 | .Xr sigaction 2 |
84d15ab6 MK |
177 | for a list of termination signals. |
178 | A status of 0 indicates normal termination. | |
931b8415 CL |
179 | .Pp |
180 | If a parent process terminates without | |
181 | waiting for all of its child processes to terminate, | |
182 | the remaining child processes are assigned the parent | |
183 | process 1 ID (the init process ID). | |
184 | .Pp | |
84d15ab6 | 185 | If a signal is caught while any of the |
931b8415 | 186 | .Fn wait |
84d15ab6 MK |
187 | calls is pending, |
188 | the call may be interrupted or restarted when the signal-catching routine | |
189 | returns, | |
190 | depending on the options in effect for the signal; | |
191 | see | |
931b8415 | 192 | .Xr intro 2 , |
84d15ab6 | 193 | System call restart. |
931b8415 CL |
194 | .Sh RETURN VALUES |
195 | If | |
196 | .Fn wait | |
197 | returns due to a stopped | |
28494293 | 198 | or terminated child process, the process ID of the child |
931b8415 CL |
199 | is returned to the calling process. Otherwise, a value of -1 |
200 | is returned and | |
201 | .Va errno | |
202 | is set to indicate the error. | |
203 | .Pp | |
84d15ab6 | 204 | If |
931b8415 CL |
205 | .Fn wait4 , |
206 | .Fn wait3 | |
84d15ab6 | 207 | or |
931b8415 | 208 | .Fn waitpid |
84d15ab6 MK |
209 | returns due to a stopped |
210 | or terminated child process, the process ID of the child | |
211 | is returned to the calling process. | |
212 | If there are no children not previously awaited, | |
931b8415 CL |
213 | -1 is returned with |
214 | .Va errno | |
215 | set to | |
216 | .Bq Er ECHILD . | |
217 | Otherwise, if | |
218 | .Dv WNOHANG | |
219 | is specified and there are | |
84d15ab6 MK |
220 | no stopped or exited children, |
221 | 0 is returned. | |
222 | If an error is detected or a caught signal aborts the call, | |
931b8415 CL |
223 | a value of -1 |
224 | is returned and | |
225 | .Va errno | |
226 | is set to indicate the error. | |
227 | .Sh ERRORS | |
228 | .Fn Wait | |
229 | will fail and return immediately if: | |
230 | .Bl -tag -width Er | |
231 | .It Bq Er ECHILD | |
28494293 KM |
232 | The calling process has no existing unwaited-for |
233 | child processes. | |
931b8415 CL |
234 | .It Bq Er EFAULT |
235 | The | |
236 | .Fa status | |
237 | or | |
238 | .Fa rusage | |
239 | arguments point to an illegal address. | |
84d15ab6 | 240 | (May not be detected before exit of a child process.) |
931b8415 | 241 | .It Bq Er EINTR |
84d15ab6 | 242 | The call was interrupted by a caught signal, |
931b8415 CL |
243 | or the signal did not have the |
244 | .Dv SA_RESTART | |
245 | flag set. | |
246 | .El | |
247 | .Sh STANDARDS | |
84d15ab6 | 248 | The |
931b8415 | 249 | .Fn wait |
84d15ab6 | 250 | and |
931b8415 | 251 | .Fn waitpid |
84d15ab6 | 252 | functions are defined by POSIX; |
931b8415 | 253 | .Fn wait4 |
84d15ab6 | 254 | and |
931b8415 | 255 | .Fn wait3 |
84d15ab6 | 256 | are not specified by POSIX. |
931b8415 CL |
257 | The |
258 | .Fn WCOREDUMP | |
259 | macro | |
84d15ab6 | 260 | and the ability to restart a pending |
931b8415 | 261 | .Fn wait |
84d15ab6 | 262 | call are extensions to the POSIX interface. |
931b8415 CL |
263 | .Sh SEE ALSO |
264 | .Xr exit 2 , | |
265 | .Xr sigaction 2 | |
266 | .Sh HISTORY | |
267 | A | |
268 | .Nm | |
269 | function call appeared in Version 6 AT&T UNIX. |