| blob | fcf5c4351ad6e82aefb49bc4d8358a20b923ae5f |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1992 X/Open Company Limited
4 .\" Copyright 1989 AT&T
5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
7 .\" http://www.opengroup.org/bookstore/.
8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH WAIT 1 "Mar 13, 2008"
14 .SH NAME
15 wait \- await process completion
16 .SH SYNOPSIS
17 .LP
18 .nf
20 .fi
22 .SS "/bin/sh"
23 .LP
24 .nf
25 \fBwait\fR [\fIpid\fR]...
26 .fi
28 .SS "/bin/jsh /bin/ksh /usr/bin/sh"
29 .LP
30 .nf
31 \fBwait\fR [\fIpid\fR]...
32 .fi
34 .LP
35 .nf
36 \fBwait\fR [% \fIjobid\fR...]
37 .fi
39 .SS "/bin/csh"
40 .LP
41 .nf
42 \fBwait\fR
43 .fi
45 .SS "ksh93"
46 .LP
47 .nf
48 \fBwait\fR [\fIjob...\fR]
49 .fi
51 .SH DESCRIPTION
52 .sp
53 .LP
54 The shell itself executes \fBwait\fR, without creating a new process. If you
55 get the error message \fBcannot fork,too many processes\fR, try using the
56 \fBwait\fR command to clean up your background processes. If this doesn't help,
57 the system process table is probably full or you have too many active
58 foreground processes. There is a limit to the number of process \fBID\fRs
59 associated with your login, and to the number the system can keep track of.
60 .sp
61 .LP
62 Not all the processes of a pipeline with three or more stages are children of
63 the shell, and thus cannot be waited for.
64 .SS "/bin/sh, /bin/jsh"
65 .sp
66 .LP
67 Wait for your background process whose process \fBID\fR is \fIpid\fR and report
68 its termination status. If \fIpid\fR is omitted, all your shell's currently
69 active background processes are waited for and the return code is \fB0\fR. The
70 \fBwait\fR utility accepts a job identifier, when Job Control is enabled (jsh),
71 and the argument, \fIjobid\fR, is preceded by a percent sign (\fB%\fR).
72 .sp
73 .LP
74 If \fIpid\fR is not an active process \fBID,\fR the \fBwait\fR utility returns
75 immediately and the return code is \fB0\fR.
76 .SS "csh"
77 .sp
78 .LP
79 Wait for your background processes.
80 .SS "ksh"
81 .sp
82 .LP
83 When an asynchronous list is started by the shell, the process \fBID\fR of the
84 last command in each element of the asynchronous list becomes known in the
85 current shell execution environment.
86 .sp
87 .LP
88 If the \fBwait\fR utility is invoked with no operands, it waits until all
89 process \fBIDs\fR known to the invoking shell have terminated and exit with an
90 exit status of \fB0\fR.
91 .sp
92 .LP
93 If one or more \fIpid\fR or \fIjobid\fR operands are specified that represent
94 known process \fBID\fRs (or jobids), the \fBwait\fR utility waits until all of
95 them have terminated. If one or more \fIpid\fR or \fIjobid\fR operands are
96 specified that represent unknown process \fBID\fRs (or jobids), \fBwait\fR
97 treats them as if they were known process \fBID\fRs (or jobids) that exited
98 with exit status \fB127\fR. The exit status returned by the \fBwait\fR utility
99 is the exit status of the process requested by the last \fIpid\fR or
100 \fIjobid\fR operand.
101 .sp
102 .LP
103 The known process \fBID\fRs are applicable only for invocations of \fBwait\fR
104 in the current shell execution environment.
105 .SS "ksh93"
106 .sp
107 .LP
108 wait with no operands, waits until all jobs known to the invoking shell have
109 terminated. If one or more job operands are specified, wait waits until all of
110 them have completed. Each job can be specified as one of the following:
111 .sp
112 .ne 2
113 .na
114 \fB\fInumber\fR\fR
115 .ad
116 .RS 12n
117 \fInumber\fR refers to a process ID.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fB-\fR\fInumber\fR\fR
124 .ad
125 .RS 12n
126 \fInumber\fR refers to a process group ID.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fB%\fR\fInumber\fR\fR
133 .ad
134 .RS 12n
135 \fInumber\fR refers to a job number
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fB%\fR\fIstring\fR\fR
142 .ad
143 .RS 12n
144 Refers to a job whose name begins with \fIstring\fR
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fB%?\fR\fIstring\fR\fR
151 .ad
152 .RS 12n
153 Refers to a job whose name contains \fIstring\fR
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fB%+\fR\fR
160 .ad
161 .br
162 .na
163 \fB\fB%%\fR\fR
164 .ad
165 .RS 12n
166 Refers to the current job
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fB%-\fR\fR
173 .ad
174 .RS 12n
175 Refers to the previous job
176 .RE
178 .sp
179 .LP
180 If one ore more job operands is a process id or process group id not known by
181 the current shell environment, \fBwait\fR treats each of them as if it were a
182 process that exited with status 127.
183 .SH OPERANDS
184 .sp
185 .LP
186 The following operands are supported:
187 .sp
188 .ne 2
189 .na
190 \fB\fIpid\fR\fR
191 .ad
192 .RS 9n
193 The unsigned decimal integer process \fBID\fR of a command, for which the
194 utility is to wait for the termination.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fB\fIjobid\fR\fR
201 .ad
202 .RS 9n
203 A job control job \fBID\fR that identifies a background process group to be
204 waited for. The job control job \fBID\fR notation is applicable only for
205 invocations of \fBwait\fR in the current shell execution environment, and only
206 on systems supporting the job control option.
207 .RE
209 .SH USAGE
210 .sp
211 .LP
212 On most implementations, \fBwait\fR is a shell built-in. If it is called in a
213 subshell or separate utility execution environment, such as one of the
214 following,
215 .sp
216 .in +2
217 .nf
218 (wait)
219 nohup wait ...
220 find . -exec wait ... \e;
221 .fi
222 .in -2
223 .sp
225 .sp
226 .LP
227 it returns immediately because there is no known process \fBID\fRs to wait for
228 in those environments.
229 .SH EXAMPLES
230 .LP
231 \fBExample 1 \fRUsing A Script To Identify The Termination Signal
232 .sp
233 .LP
234 Although the exact value used when a process is terminated by a signal is
235 unspecified, if it is known that a signal terminated a process, a script can
236 still reliably figure out which signal is using \fBkill\fR, as shown by the
237 following (\fB/bin/ksh\fR and \fB/usr/bin/sh\fR):
239 .sp
240 .in +2
241 .nf
242 sleep 1000&
243 pid=$!
244 kill -kill $pid
245 wait $pid
246 echo $pid was terminated by a SIG$(kill -l $(($?\(mi128))) signal.
247 .fi
248 .in -2
249 .sp
251 .LP
252 \fBExample 2 \fRReturning The Exit Status Of A Process
253 .sp
254 .LP
255 If the following sequence of commands is run in less than 31 seconds
256 (\fB/bin/ksh\fR and \fB/usr/bin/sh\fR):
258 .sp
259 .in +2
260 .nf
261 sleep 257 | sleep 31 &
263 jobs -l %%
264 .fi
265 .in -2
266 .sp
268 .sp
269 .LP
270 then either of the following commands returns the exit status of the second
271 \fBsleep\fR in the pipeline:
273 .sp
274 .in +2
275 .nf
276 wait <\fIpid of sleep 31\fR>
277 wait %%
278 .fi
279 .in -2
280 .sp
282 .SH ENVIRONMENT VARIABLES
283 .sp
284 .LP
285 See \fBenviron\fR(5) for descriptions of the following environment variables
286 that affect the execution of \fBwait\fR: \fBLANG\fR, \fBLC_ALL\fR,
287 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
288 .SH EXIT STATUS
289 .SS "ksh93"
290 .sp
291 .LP
292 The following exit values are returned by the \fBwait\fR built-in in
293 \fBksh93\fR:
294 .sp
295 .ne 2
296 .na
297 \fB\fB0\fR\fR
298 .ad
299 .RS 7n
300 \fBwait\fR was invoked with no operands. All processes known by the invoking
301 process have terminated.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fB127\fR\fR
308 .ad
309 .RS 7n
310 \fIjob\fR is a process id or process group id that is unknown to the current
311 shell environment.
312 .RE
314 .SH ATTRIBUTES
315 .sp
316 .LP
317 See \fBattributes\fR(5) for descriptions of the following attributes:
318 .sp
320 .sp
321 .TS
322 box;
323 c | c
324 l | l .
325 ATTRIBUTE TYPE ATTRIBUTE VALUE
326 _
327 Interface Stability Committed
328 _
329 Standard See \fBstandards\fR(5).
330 .TE
332 .SH SEE ALSO
333 .sp
334 .LP
335 \fBcsh\fR(1), \fBjobs\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBsh\fR(1),
336 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)