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