1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
2 .TH "WAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
5 wait \- await process completion
8 \fBwait\fP \fB[\fP\fIpid\fP\fB...\fP\fB]\fP
11 When an asynchronous list (see \fIAsynchronous Lists\fP ) is started
13 shell, the process ID of the last command in each element of the asynchronous
14 list shall become known in the current shell
15 execution environment; see \fIShell Execution Environment\fP .
17 If the \fIwait\fP utility is invoked with no operands, it shall wait
18 until all process IDs known to the invoking shell have
19 terminated and exit with a zero exit status.
21 If one or more \fIpid\fP operands are specified that represent known
22 process IDs, the \fIwait\fP utility shall wait until all
23 of them have terminated. If one or more \fIpid\fP operands are specified
24 that represent unknown process IDs, \fIwait\fP shall
25 treat them as if they were known process IDs that exited with exit
26 status 127. The exit status returned by the \fIwait\fP utility
27 shall be the exit status of the process requested by the last \fIpid\fP
30 The known process IDs are applicable only for invocations of \fIwait\fP
31 in the current shell execution environment.
37 The following operand shall be supported:
43 The unsigned decimal integer process ID of a command, for which the
44 utility is to wait for the termination.
47 A job control job ID (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
48 Section 3.203, Job Control Job ID) that identifies a background process
50 waited for. The job control job ID notation is applicable only for
51 invocations of \fIwait\fP in the current shell execution
52 environment; see \fIShell Execution Environment\fP . The exit status
54 be determined by the last command in the pipeline.
58 The job control job ID type of \fIpid\fP is only available on systems
59 supporting the User Portability Utilities option.
71 .SH ENVIRONMENT VARIABLES
73 The following environment variables shall affect the execution of
77 Provide a default value for the internationalization variables that
78 are unset or null. (See the Base Definitions volume of
79 IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
81 the precedence of internationalization variables used to determine
82 the values of locale categories.)
85 If set to a non-empty string value, override the values of all the
86 other internationalization variables.
89 Determine the locale for the interpretation of sequences of bytes
90 of text data as characters (for example, single-byte as
91 opposed to multi-byte characters in arguments).
94 Determine the locale that should be used to affect the format and
95 contents of diagnostic messages written to standard
99 Determine the location of message catalogs for the processing of \fILC_MESSAGES
102 .SH ASYNCHRONOUS EVENTS
110 The standard error shall be used only for diagnostic messages.
114 .SH EXTENDED DESCRIPTION
119 If one or more operands were specified, all of them have terminated
120 or were not known by the invoking shell, and the status of
121 the last operand specified is known, then the exit status of \fIwait\fP
122 shall be the exit status information of the command
123 indicated by the last operand specified. If the process terminated
124 abnormally due to the receipt of a signal, the exit status shall
125 be greater than 128 and shall be distinct from the exit status generated
126 by other signals, but the exact value is unspecified. (See
127 the \fIkill\fP \fB-l\fP option.) Otherwise, the \fIwait\fP utility
128 shall exit with one of
129 the following values:
132 The \fIwait\fP utility was invoked with no operands and all process
133 IDs known by the invoking shell have terminated.
136 The \fIwait\fP utility detected an error.
139 The command identified by the last \fIpid\fP operand specified is
142 .SH CONSEQUENCES OF ERRORS
146 \fIThe following sections are informative.\fP
147 .SH APPLICATION USAGE
149 On most implementations, \fIwait\fP is a shell built-in. If it is
150 called in a subshell or separate utility execution
151 environment, such as one of the following:
158 find . -exec wait ... \\;
163 it returns immediately because there are no known process IDs to wait
164 for in those environments.
166 Historical implementations of interactive shells have discarded the
167 exit status of terminated background processes before each
168 shell prompt. Therefore, the status of background processes was usually
169 lost unless it terminated while \fIwait\fP was waiting for
170 it. This could be a serious problem when a job that was expected to
171 run for a long time actually terminated quickly with a syntax
172 or initialization error because the exit status returned was usually
173 zero if the requested process ID was not found. This volume of
174 IEEE\ Std\ 1003.1-2001 requires the implementation to keep the status
175 of terminated jobs available until the status is
176 requested, so that scripts like:
185 echo Job 1 exited with status $?
187 echo Job 2 exited with status $?
192 work without losing status on any of the jobs. The shell is allowed
193 to discard the status of any process if it determines that
194 the application cannot get the process ID for that process from the
195 shell. It is also required to remember only {CHILD_MAX} number
196 of processes in this way. Since the only way to get the process ID
197 from the shell is by using the \fB'!'\fP shell parameter, the
198 shell is allowed to discard the status of an asynchronous list if
199 \fB"$!"\fP was not referenced before another asynchronous list
200 was started. (This means that the shell only has to keep the status
201 of the last asynchronous list started if the application did
202 not reference \fB"$!"\fP . If the implementation of the shell is smart
203 enough to determine that a reference to \fB"$!"\fP was
204 not saved anywhere that the application can retrieve it later, it
205 can use this information to trim the list of saved information.
206 Note also that a successful call to \fIwait\fP with no operands discards
207 the exit status of all asynchronous lists.)
209 If the exit status of \fIwait\fP is greater than 128, there is no
210 way for the application to know if the waited-for process
211 exited with that value or was killed by a signal. Since most utilities
212 exit with small values, there is seldom any ambiguity. Even
213 in the ambiguous cases, most applications just need to know that the
214 asynchronous job failed; it does not matter whether it
215 detected an error and failed or was killed and did not complete its
219 Although the exact value used when a process is terminated by a signal
220 is unspecified, if it is known that a signal terminated a
221 process, a script can still reliably determine which signal by using
222 \fIkill\fP as shown by
223 the following script:
232 echo $pid was terminated by a SIG$(kill -l $?) signal.
237 If the following sequence of commands is run in less than 31 seconds:
242 \fBsleep 257 | sleep 31 &
248 either of the following commands returns the exit status of the second
255 \fBwait\fP \fI<pid of sleep 31>\fP\fBwait %%
261 The description of \fIwait\fP does not refer to the \fIwaitpid\fP()
263 System Interfaces volume of IEEE\ Std\ 1003.1-2001 because that would
264 needlessly overspecify this interface. However, the
265 wording means that \fIwait\fP is required to wait for an explicit
266 process when it is given an argument so that the status
267 information of other processes is not consumed. Historical implementations
268 use the \fIwait\fP() function defined in the System Interfaces volume
269 of IEEE\ Std\ 1003.1-2001 until
270 \fIwait\fP() returns the requested process ID or finds that the requested
272 exist. Because this means that a shell script could not reliably get
273 the status of all background children if a second background
274 job was ever started before the first job finished, it is recommended
275 that the \fIwait\fP utility use a method such as the
276 functionality provided by the \fIwaitpid\fP() function.
278 The ability to wait for multiple \fIpid\fP operands was adopted from
281 This new functionality was added because it is needed to determine
282 the exit status of any asynchronous list accurately. The only
283 compatibility problem that this change creates is for a script like
289 job& echo Job started $(date) as $! done
294 which causes the shell to monitor all of the jobs started until the
295 script terminates or runs out of memory. This would not be a
296 problem if the loop did not reference \fB"$!"\fP or if the script
297 would occasionally \fIwait\fP for jobs it started.
298 .SH FUTURE DIRECTIONS
303 \fIShell Command Language\fP , \fIkill\fP() , \fIsh\fP , the System
304 Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIwait\fP(), \fIwaitpid\fP()
306 Portions of this text are reprinted and reproduced in electronic form
307 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
308 -- Portable Operating System Interface (POSIX), The Open Group Base
309 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
310 Electrical and Electronics Engineers, Inc and The Open Group. In the
311 event of any discrepancy between this version and the original IEEE and
312 The Open Group Standard, the original IEEE and The Open Group Standard
313 is the referee document. The original Standard can be obtained online at
314 http://www.opengroup.org/unix/online.html .
projects / thirdparty / man-pages.git / blob