1WAIT(P) POSIX Programmer's Manual WAIT(P)
2
6 wait - await process completion
7
9 wait [pid...]
10
12 When an asynchronous list (see Asynchronous Lists ) is started by the
13 shell, the process ID of the last command in each element of the asyn‐
14 chronous list shall become known in the current shell execution envi‐
15 ronment; see Shell Execution Environment .
16 If the wait utility is invoked with no operands, it shall wait until
18 all process IDs known to the invoking shell have terminated and exit
19 with a zero exit status.
20 If one or more pid operands are specified that represent known process
22 IDs, the wait utility shall wait until all of them have terminated. If
23 one or more pid operands are specified that represent unknown process
24 IDs, wait shall treat them as if they were known process IDs that
25 exited with exit status 127. The exit status returned by the wait util‐
26 ity shall be the exit status of the process requested by the last pid
27 operand.
28 The known process IDs are applicable only for invocations of wait in
30 the current shell execution environment.
31
33 None.
34
36 The following operand shall be supported:
37 pid One of the following:
39 1. The unsigned decimal integer process ID of a command, for
41 which the utility is to wait for the termination.
42 2. A job control job ID (see the Base Definitions volume of
44 IEEE Std 1003.1-2001, Section 3.203, Job Control Job ID)
45 that identifies a background process group to be waited for.
46 The job control job ID notation is applicable only for invo‐
47 cations of wait in the current shell execution environment;
48 see Shell Execution Environment . The exit status of wait
49 shall be determined by the last command in the pipeline.
50 Note:
52 The job control job ID type of pid is only available on
53 systems supporting the User Portability Utilities option.
54
57 Not used.
58
60 None.
61
63 The following environment variables shall affect the execution of wait:
64 LANG Provide a default value for the internationalization variables
66 that are unset or null. (See the Base Definitions volume of
67 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
68 ables for the precedence of internationalization variables used
69 to determine the values of locale categories.)
70 LC_ALL If set to a non-empty string value, override the values of all
72 the other internationalization variables.
73 LC_CTYPE
75 Determine the locale for the interpretation of sequences of
76 bytes of text data as characters (for example, single-byte as
77 opposed to multi-byte characters in arguments).
78 LC_MESSAGES
80 Determine the locale that should be used to affect the format
81 and contents of diagnostic messages written to standard error.
82 NLSPATH
84 Determine the location of message catalogs for the processing of
85 LC_MESSAGES .
86
89 Default.
90
92 Not used.
93
95 The standard error shall be used only for diagnostic messages.
96
98 None.
99
101 None.
102
104 If one or more operands were specified, all of them have terminated or
105 were not known by the invoking shell, and the status of the last oper‐
106 and specified is known, then the exit status of wait shall be the exit
107 status information of the command indicated by the last operand speci‐
108 fied. If the process terminated abnormally due to the receipt of a sig‐
109 nal, the exit status shall be greater than 128 and shall be distinct
110 from the exit status generated by other signals, but the exact value is
111 unspecified. (See the kill -l option.) Otherwise, the wait utility
112 shall exit with one of the following values:
113 0 The wait utility was invoked with no operands and all process
115 IDs known by the invoking shell have terminated.
116 1-126 The wait utility detected an error.
118 127 The command identified by the last pid operand specified is
120 unknown.
121
124 Default.
125 The following sections are informative.
127
129 On most implementations, wait is a shell built-in. If it is called in a
130 subshell or separate utility execution environment, such as one of the
131 following:
132 (wait)
135 nohup wait ...
136 find . -exec wait ... \;
137 it returns immediately because there are no known process IDs to wait
139 for in those environments.
140 Historical implementations of interactive shells have discarded the
142 exit status of terminated background processes before each shell
143 prompt. Therefore, the status of background processes was usually lost
144 unless it terminated while wait was waiting for it. This could be a
145 serious problem when a job that was expected to run for a long time
146 actually terminated quickly with a syntax or initialization error
147 because the exit status returned was usually zero if the requested
148 process ID was not found. This volume of IEEE Std 1003.1-2001 requires
149 the implementation to keep the status of terminated jobs available
150 until the status is requested, so that scripts like:
151 j1&
154 p1=$!
155 j2&
156 wait $p1
157 echo Job 1 exited with status $?
158 wait $!
159 echo Job 2 exited with status $?
160 work without losing status on any of the jobs. The shell is allowed to
162 discard the status of any process if it determines that the application
163 cannot get the process ID for that process from the shell. It is also
164 required to remember only {CHILD_MAX} number of processes in this way.
165 Since the only way to get the process ID from the shell is by using the
166 '!' shell parameter, the shell is allowed to discard the status of an
167 asynchronous list if "$!" was not referenced before another asynchro‐
168 nous list was started. (This means that the shell only has to keep the
169 status of the last asynchronous list started if the application did not
170 reference "$!" . If the implementation of the shell is smart enough to
171 determine that a reference to "$!" was not saved anywhere that the
172 application can retrieve it later, it can use this information to trim
173 the list of saved information. Note also that a successful call to
174 wait with no operands discards the exit status of all asynchronous
175 lists.)
176 If the exit status of wait is greater than 128, there is no way for the
178 application to know if the waited-for process exited with that value or
179 was killed by a signal. Since most utilities exit with small values,
180 there is seldom any ambiguity. Even in the ambiguous cases, most appli‐
181 cations just need to know that the asynchronous job failed; it does not
182 matter whether it detected an error and failed or was killed and did
183 not complete its job normally.
184
186 Although the exact value used when a process is terminated by a signal
187 is unspecified, if it is known that a signal terminated a process, a
188 script can still reliably determine which signal by using kill as shown
189 by the following script:
190 sleep 1000&
193 pid=$!
194 kill -kill $pid
195 wait $pid
196 echo $pid was terminated by a SIG$(kill -l $?) signal.
197 If the following sequence of commands is run in less than 31 seconds:
199 sleep 257 | sleep 31 &
202 jobs -l %%
203 either of the following commands returns the exit status of the second
205 sleep in the pipeline:
206 wait <pid of sleep 31>wait %%
209
211 The description of wait does not refer to the waitpid() function from
212 the System Interfaces volume of IEEE Std 1003.1-2001 because that would
213 needlessly overspecify this interface. However, the wording means that
214 wait is required to wait for an explicit process when it is given an
215 argument so that the status information of other processes is not con‐
216 sumed. Historical implementations use the wait() function defined in
217 the System Interfaces volume of IEEE Std 1003.1-2001 until wait()
218 returns the requested process ID or finds that the requested process
219 does not exist. Because this means that a shell script could not reli‐
220 ably get the status of all background children if a second background
221 job was ever started before the first job finished, it is recommended
222 that the wait utility use a method such as the functionality provided
223 by the waitpid() function.
224 The ability to wait for multiple pid operands was adopted from the
226 KornShell.
227 This new functionality was added because it is needed to determine the
229 exit status of any asynchronous list accurately. The only compatibility
230 problem that this change creates is for a script like
231 while sleep 60 do
234 job& echo Job started $(date) as $! done
235 which causes the shell to monitor all of the jobs started until the
237 script terminates or runs out of memory. This would not be a problem if
238 the loop did not reference "$!" or if the script would occasionally
239 wait for jobs it started.
240
242 None.
243
245 Shell Command Language , kill() , sh , the System Interfaces volume of
246 IEEE Std 1003.1-2001, wait(), waitpid()
247
249 Portions of this text are reprinted and reproduced in electronic form
250 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
251 -- Portable Operating System Interface (POSIX), The Open Group Base
252 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
253 Electrical and Electronics Engineers, Inc and The Open Group. In the
254 event of any discrepancy between this version and the original IEEE and
255 The Open Group Standard, the original IEEE and The Open Group Standard
256 is the referee document. The original Standard can be obtained online
257 at http://www.opengroup.org/unix/online.html .
258IEEE/The Open Group 2003 WAIT(P)