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