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