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