1WAIT(1P)                   POSIX Programmer's Manual                  WAIT(1P)
2
3
4

PROLOG

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

NAME

12       wait — await process completion
13

SYNOPSIS

15       wait [pid...]
16

DESCRIPTION

18       When an asynchronous list (see Section 2.9.3.1, Examples) is started by
19       the  shell,  the  process ID of the last command in each element of the
20       asynchronous list shall become known in  the  current  shell  execution
21       environment; see Section 2.12, Shell Execution Environment.
22
23       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
27       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
35       The  known  process  IDs are applicable only for invocations of wait in
36       the current shell execution environment.
37

OPTIONS

39       None.
40

OPERANDS

42       The following operand shall be supported:
43
44       pid       One of the following:
45
46                  1. The unsigned decimal integer process ID of a command, for
47                     which the utility is to wait for the termination.
48
49                  2. A  job control job ID (see the Base Definitions volume of
50                     POSIX.1‐2017, Section 3.204, Job  Control  Job  ID)  that
51                     identifies  a  background process group to be waited for.
52                     The job control job ID notation is  applicable  only  for
53                     invocations  of wait in the current shell execution envi‐
54                     ronment; see Section 2.12, Shell  Execution  Environment.
55                     The  exit  status of wait shall be determined by the last
56                     command in the pipeline.
57
58                     Note:     The job control job ID  type  of  pid  is  only
59                               available on systems supporting the User Porta‐
60                               bility Utilities option.
61

STDIN

63       Not used.
64

INPUT FILES

66       None.
67

ENVIRONMENT VARIABLES

69       The following environment variables shall affect the execution of wait:
70
71       LANG      Provide a default value for  the  internationalization  vari‐
72                 ables  that are unset or null. (See the Base Definitions vol‐
73                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
74                 ables  for  the  precedence of internationalization variables
75                 used to determine the values of locale categories.)
76
77       LC_ALL    If set to a non-empty string value, override  the  values  of
78                 all the other internationalization variables.
79
80       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
81                 bytes of text data as characters (for example, single-byte as
82                 opposed to multi-byte characters in arguments).
83
84       LC_MESSAGES
85                 Determine the locale that should be used to affect the format
86                 and contents  of  diagnostic  messages  written  to  standard
87                 error.
88
89       NLSPATH   Determine the location of message catalogs for the processing
90                 of LC_MESSAGES.
91

ASYNCHRONOUS EVENTS

93       Default.
94

STDOUT

96       Not used.
97

STDERR

99       The standard error shall be used only for diagnostic messages.
100

OUTPUT FILES

102       None.
103

EXTENDED DESCRIPTION

105       None.
106

EXIT STATUS

108       If one or more operands were specified, all of them have terminated  or
109       were  not known by the invoking shell, and the status of the last oper‐
110       and specified is known, then the exit status of wait shall be the  exit
111       status  information of the command indicated by the last operand speci‐
112       fied. If the process terminated abnormally due to the receipt of a sig‐
113       nal,  the  exit  status shall be greater than 128 and shall be distinct
114       from the exit status generated by other signals, but the exact value is
115       unspecified.  (See  the  kill  -l  option.) Otherwise, the wait utility
116       shall exit with one of the following values:
117
118           0   The wait utility was invoked with no operands and  all  process
119               IDs known by the invoking shell have terminated.
120
121       1‐126   The wait utility detected an error.
122
123         127   The  command  identified  by  the last pid operand specified is
124               unknown.
125

CONSEQUENCES OF ERRORS

127       Default.
128
129       The following sections are informative.
130

APPLICATION USAGE

132       On most implementations, wait is a shell built-in. If it is called in a
133       subshell  or separate utility execution environment, such as one of the
134       following:
135
136
137           (wait)
138           nohup wait ...
139           find . -exec wait ... \;
140
141       it returns immediately because there are no known process IDs  to  wait
142       for in those environments.
143
144       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‐2017  requires  the
152       implementation  to  keep  the status of terminated jobs available until
153       the status is requested, so that scripts like:
154
155
156           j1&
157           p1=$!
158           j2&
159           wait $p1
160           echo Job 1 exited with status $?
161           wait $!
162           echo Job 2 exited with status $?
163
164       work without losing status on any of the jobs. The shell is allowed  to
165       discard the status of any process if it determines that the application
166       cannot get the process ID for that process from the shell. It  is  also
167       required  to remember only {CHILD_MAX} number of processes in this way.
168       Since the only way to get the process ID from the shell is by using the
169       '!'   shell parameter, the shell is allowed to discard the status of an
170       asynchronous list if "$!" was not referenced before  another  asynchro‐
171       nous  list was started. (This means that the shell only has to keep the
172       status of the last asynchronous list started if the application did not
173       reference  "$!".  If the implementation of the shell is smart enough to
174       determine that a reference to "$!" was  not  saved  anywhere  that  the
175       application  can retrieve it later, it can use this information to trim
176       the list of saved information. Note also that a successful call to wait
177       with no operands discards the exit status of all asynchronous lists.)
178
179       If the exit status of wait is greater than 128, there is no way for the
180       application to know if the waited-for process exited with that value or
181       was  killed  by a signal.  Since most utilities exit with small values,
182       there is seldom any ambiguity. Even in the ambiguous cases, most appli‐
183       cations just need to know that the asynchronous job failed; it does not
184       matter whether it detected an error and failed or was  killed  and  did
185       not complete its job normally.
186

EXAMPLES

188       Although  the exact value used when a process is terminated by a signal
189       is unspecified, if it is known that a signal terminated  a  process,  a
190       script can still reliably determine which signal by using kill as shown
191       by the following script:
192
193
194           sleep 1000&
195           pid=$!
196           kill -kill $pid
197           wait $pid
198           echo $pid was terminated by a SIG$(kill -l $?) signal.
199
200       If the following sequence of commands is run in less than 31 seconds:
201
202
203           sleep 257 | sleep 31 &
204           jobs -l %%
205
206       either of the following commands returns the exit status of the  second
207       sleep in the pipeline:
208
209
210           wait <pid of sleep 31>
211           wait %%
212

RATIONALE

214       The  description  of wait does not refer to the waitpid() function from
215       the System Interfaces volume of POSIX.1‐2017 because that  would  need‐
216       lessly overspecify this interface. However, the wording means that wait
217       is required to wait for an explicit process when it is given  an  argu‐
218       ment so that the status information of other processes is not consumed.
219       Historical implementations use the wait() function defined in the  Sys‐
220       tem   Interfaces  volume  of  POSIX.1‐2017  until  wait()  returns  the
221       requested process ID or finds  that  the  requested  process  does  not
222       exist.  Because  this  means that a shell script could not reliably get
223       the status of all background children if a second  background  job  was
224       ever  started before the first job finished, it is recommended that the
225       wait utility use a method such as the  functionality  provided  by  the
226       waitpid() function.
227
228       The  ability  to  wait  for  multiple pid operands was adopted from the
229       KornShell.
230
231       This new functionality was added because it is needed to determine  the
232       exit status of any asynchronous list accurately. The only compatibility
233       problem that this change creates is for a script like
234
235
236           while sleep 60 do
237               job& echo Job started $(date) as $!  done
238
239       which causes the shell to monitor all of the  jobs  started  until  the
240       script terminates or runs out of memory. This would not be a problem if
241       the loop did not reference "$!" or if  the  script  would  occasionally
242       wait for jobs it started.
243

FUTURE DIRECTIONS

245       None.
246

SEE ALSO

248       Chapter 2, Shell Command Language, kill, sh
249
250       The Base Definitions volume of POSIX.1‐2017, Section 3.204, Job Control
251       Job ID, Chapter 8, Environment Variables
252
253       The System Interfaces volume of POSIX.1‐2017, wait()
254
256       Portions of this text are reprinted and reproduced in  electronic  form
257       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
258       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
259       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
260       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
261       event of any discrepancy between this version and the original IEEE and
262       The Open Group Standard, the original IEEE and The Open Group  Standard
263       is  the  referee document. The original Standard can be obtained online
264       at http://www.opengroup.org/unix/online.html .
265
266       Any typographical or formatting errors that appear  in  this  page  are
267       most likely to have been introduced during the conversion of the source
268       files to man page format. To report such errors,  see  https://www.ker
269       nel.org/doc/man-pages/reporting_bugs.html .
270
271
272
273IEEE/The Open Group                  2017                             WAIT(1P)
Impressum