![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to wait.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to wait.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 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: .\"
5: .\" @(#)wait.2 6.3 (Berkeley) 8/14/89
6: .\"
7: .TH WAIT 2 "August 14, 1989"
8: .UC 4
9: .SH NAME
10: wait, waitpid, wait4, wait3 \- wait for process to terminate
11: .SH SYNOPSIS
12: .ft B
13: .nf
14: #include <sys/types.h>
15: #include <sys/wait.h>
16: .PP
17: .ft B
18: pid = wait(status)
19: pid_t pid;
20: int *status;
21: .PP
22: .ft B
23: pid = waitpid(wpid, status, options)
24: pid_t pid, wpid;
25: int *status;
26: int options;
27: .PP
28: .ft B
29: #include <sys/time.h>
30: #include <sys/resource.h>
31: .PP
32: .ft B
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
40: pid = wait3(status, options, rusage)
41: pid_t pid;
42: int *status;
43: int options;
44: struct rusage *rusage;
45: .fi
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
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.
58: .PP
59: On return from a successful
60: .I wait
61: call,
62: the
63: .I status
64: area contains termination information about the process that exited
65: as defined below.
66: .PP
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
97: .I status
98: parameter is defined below. The
99: .I options
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
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,
118: .I wait4
119: returns a
120: .I pid
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.
174: .SH NOTES
175: See
176: .IR sigaction (2)
177: for a list of termination signals.
178: A status of 0 indicates normal termination.
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
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.
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.
200: .PP
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.
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.
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.
249: .SH "SEE ALSO"
250: exit(2), sigaction(2)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.