1WAIT(1P) POSIX Programmer's Manual WAIT(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 wait — await process completion
14
16 wait [pid...]
17
19 When an asynchronous list (see Section 2.9.3.1, Examples) is started by
20 the shell, the process ID of the last command in each element of the
21 asynchronous list shall become known in the current shell execution
22 environment; see Section 2.12, Shell Execution Environment.
23 If the wait utility is invoked with no operands, it shall wait until
25 all process IDs known to the invoking shell have terminated and exit
26 with a zero exit status.
27 If one or more pid operands are specified that represent known process
29 IDs, the wait utility shall wait until all of them have terminated. If
30 one or more pid operands are specified that represent unknown process
31 IDs, wait shall treat them as if they were known process IDs that
32 exited with exit status 127. The exit status returned by the wait util‐
33 ity shall be the exit status of the process requested by the last pid
34 operand.
35 The known process IDs are applicable only for invocations of wait in
37 the current shell execution environment.
38
40 None.
41
43 The following operand shall be supported:
44 pid One of the following:
46 1. The unsigned decimal integer process ID of a command, for
48 which the utility is to wait for the termination.
49 2. A job control job ID (see the Base Definitions volume of
51 POSIX.1‐2008, Section 3.204, Job Control Job ID) that
52 identifies a background process group to be waited for.
53 The job control job ID notation is applicable only for
54 invocations of wait in the current shell execution envi‐
55 ronment; see Section 2.12, Shell Execution Environment.
56 The exit status of wait shall be determined by the last
57 command in the pipeline.
58 Note: The job control job ID type of pid is only
60 available on systems supporting the User Porta‐
61 bility Utilities option.
62
64 Not used.
65
67 None.
68
70 The following environment variables shall affect the execution of wait:
71 LANG Provide a default value for the internationalization vari‐
73 ables that are unset or null. (See the Base Definitions vol‐
74 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
75 ables for the precedence of internationalization variables
76 used to determine the values of locale categories.)
77 LC_ALL If set to a non-empty string value, override the values of
79 all the other internationalization variables.
80 LC_CTYPE Determine the locale for the interpretation of sequences of
82 bytes of text data as characters (for example, single-byte as
83 opposed to multi-byte characters in arguments).
84 LC_MESSAGES
86 Determine the locale that should be used to affect the format
87 and contents of diagnostic messages written to standard
88 error.
89 NLSPATH Determine the location of message catalogs for the processing
91 of LC_MESSAGES.
92
94 Default.
95
97 Not used.
98
100 The standard error shall be used only for diagnostic messages.
101
103 None.
104
106 None.
107
109 If one or more operands were specified, all of them have terminated or
110 were not known by the invoking shell, and the status of the last oper‐
111 and specified is known, then the exit status of wait shall be the exit
112 status information of the command indicated by the last operand speci‐
113 fied. If the process terminated abnormally due to the receipt of a sig‐
114 nal, the exit status shall be greater than 128 and shall be distinct
115 from the exit status generated by other signals, but the exact value is
116 unspecified. (See the kill −l option.) Otherwise, the wait utility
117 shall exit with one of the following values:
118 0 The wait utility was invoked with no operands and all process
120 IDs known by the invoking shell have terminated.
121 1‐126 The wait utility detected an error.
123 127 The command identified by the last pid operand specified is
125 unknown.
126
128 Default.
129 The following sections are informative.
131
133 On most implementations, wait is a shell built-in. If it is called in a
134 subshell or separate utility execution environment, such as one of the
135 following:
136 (wait)
138 nohup wait ...
139 find . −exec wait ... \;
140 it returns immediately because there are no known process IDs to wait
142 for in those environments.
143 Historical implementations of interactive shells have discarded the
145 exit status of terminated background processes before each shell
146 prompt. Therefore, the status of background processes was usually lost
147 unless it terminated while wait was waiting for it. This could be a
148 serious problem when a job that was expected to run for a long time
149 actually terminated quickly with a syntax or initialization error
150 because the exit status returned was usually zero if the requested
151 process ID was not found. This volume of POSIX.1‐2008 requires the
152 implementation to keep the status of terminated jobs available until
153 the status is requested, so that scripts like:
154 j1&
156 p1=$!
157 j2&
158 wait $p1
159 echo Job 1 exited with status $?
160 wait $!
161 echo Job 2 exited with status $?
162 work without losing status on any of the jobs. The shell is allowed to
164 discard the status of any process if it determines that the application
165 cannot get the process ID for that process from the shell. It is also
166 required to remember only {CHILD_MAX} number of processes in this way.
167 Since the only way to get the process ID from the shell is by using the
168 '!' shell parameter, the shell is allowed to discard the status of an
169 asynchronous list if "$!" was not referenced before another asynchro‐
170 nous list was started. (This means that the shell only has to keep the
171 status of the last asynchronous list started if the application did not
172 reference "$!". If the implementation of the shell is smart enough to
173 determine that a reference to "$!" was not saved anywhere that the
174 application can retrieve it later, it can use this information to trim
175 the list of saved information. Note also that a successful call to wait
176 with no operands discards the exit status of all asynchronous lists.)
177 If the exit status of wait is greater than 128, there is no way for the
179 application to know if the waited-for process exited with that value or
180 was killed by a signal. Since most utilities exit with small values,
181 there is seldom any ambiguity. Even in the ambiguous cases, most appli‐
182 cations just need to know that the asynchronous job failed; it does not
183 matter whether it detected an error and failed or was killed and did
184 not complete its job normally.
185
187 Although the exact value used when a process is terminated by a signal
188 is unspecified, if it is known that a signal terminated a process, a
189 script can still reliably determine which signal by using kill as shown
190 by the following script:
191 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 &
201 jobs −l %%
202 either of the following commands returns the exit status of the second
204 sleep in the pipeline:
205 wait <pid of sleep 31>
207 wait %%
208
210 The description of wait does not refer to the waitpid() function from
211 the System Interfaces volume of POSIX.1‐2008 because that would need‐
212 lessly overspecify this interface. However, the wording means that wait
213 is required to wait for an explicit process when it is given an argu‐
214 ment so that the status information of other processes is not consumed.
215 Historical implementations use the wait() function defined in the Sys‐
216 tem Interfaces volume of POSIX.1‐2008 until wait() returns the
217 requested process ID or finds that the requested process does not
218 exist. Because this means that a shell script could not reliably get
219 the status of all background children if a second background job was
220 ever started before the first job finished, it is recommended that the
221 wait utility use a method such as the functionality provided by the
222 waitpid() function.
223 The ability to wait for multiple pid operands was adopted from the
225 KornShell.
226 This new functionality was added because it is needed to determine the
228 exit status of any asynchronous list accurately. The only compatibility
229 problem that this change creates is for a script like
230 while sleep 60 do
232 job& echo Job started $(date) as $! done
233 which causes the shell to monitor all of the jobs started until the
235 script terminates or runs out of memory. This would not be a problem if
236 the loop did not reference "$!" or if the script would occasionally
237 wait for jobs it started.
238
240 None.
241
243 Chapter 2, Shell Command Language, kill, sh
244 The Base Definitions volume of POSIX.1‐2008, Section 3.204, Job Control
246 Job ID, Chapter 8, Environment Variables
247 The System Interfaces volume of POSIX.1‐2008, wait()
249
251 Portions of this text are reprinted and reproduced in electronic form
252 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
253 -- Portable Operating System Interface (POSIX), The Open Group Base
254 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
255 cal and Electronics Engineers, Inc and The Open Group. (This is
256 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
257 event of any discrepancy between this version and the original IEEE and
258 The Open Group Standard, the original IEEE and The Open Group Standard
259 is the referee document. The original Standard can be obtained online
260 at http://www.unix.org/online.html .
261 Any typographical or formatting errors that appear in this page are
263 most likely to have been introduced during the conversion of the source
264 files to man page format. To report such errors, see https://www.ker‐
265 nel.org/doc/man-pages/reporting_bugs.html .
266IEEE/The Open Group 2013 WAIT(1P)