logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

wait.1p (10657B)


  1. '\" et
  2. .TH WAIT "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. wait
  12. \(em await process completion
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. wait \fB[\fIpid\fR...\fB]\fR
  17. .fi
  18. .SH DESCRIPTION
  19. When an asynchronous list (see
  20. .IR "Section 2.9.3.1" ", " "Examples")
  21. is started by the shell, the process ID of the last command in each
  22. element of the asynchronous list shall become known in the current
  23. shell execution environment; see
  24. .IR "Section 2.12" ", " "Shell Execution Environment".
  25. .P
  26. If the
  27. .IR wait
  28. utility is invoked with no operands, it shall wait until all process
  29. IDs known to the invoking shell have terminated and exit with a zero
  30. exit status.
  31. .P
  32. If one or more
  33. .IR pid
  34. operands are specified that represent known process IDs, the
  35. .IR wait
  36. utility shall wait until all of them have terminated. If one or more
  37. .IR pid
  38. operands are specified that represent unknown process IDs,
  39. .IR wait
  40. shall treat them as if they were known process IDs that exited with
  41. exit status 127. The exit status returned by the
  42. .IR wait
  43. utility shall be the exit status of the process requested by the last
  44. .IR pid
  45. operand.
  46. .P
  47. The known process IDs are applicable only for invocations of
  48. .IR wait
  49. in the current shell execution environment.
  50. .SH OPTIONS
  51. None.
  52. .SH OPERANDS
  53. The following operand shall be supported:
  54. .IP "\fIpid\fR" 10
  55. One of the following:
  56. .RS 10
  57. .IP " 1." 4
  58. The unsigned decimal integer process ID of a command, for which the
  59. utility is to wait for the termination.
  60. .IP " 2." 4
  61. A job control job ID (see the Base Definitions volume of POSIX.1\(hy2017,
  62. .IR "Section 3.204" ", " "Job Control Job ID")
  63. that identifies a background process group to be waited for. The job
  64. control job ID notation is applicable only for invocations of
  65. .IR wait
  66. in the current shell execution environment; see
  67. .IR "Section 2.12" ", " "Shell Execution Environment".
  68. The exit status of
  69. .IR wait
  70. shall be determined by the last command in the pipeline.
  71. .RS 4
  72. .TP 10
  73. .BR Note:
  74. The job control job ID type of
  75. .IR pid
  76. is only available on systems supporting the User Portability Utilities
  77. option.
  78. .P
  79. .RE
  80. .RE
  81. .SH STDIN
  82. Not used.
  83. .SH "INPUT FILES"
  84. None.
  85. .SH "ENVIRONMENT VARIABLES"
  86. The following environment variables shall affect the execution of
  87. .IR wait :
  88. .IP "\fILANG\fP" 10
  89. Provide a default value for the internationalization variables that are
  90. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  91. .IR "Section 8.2" ", " "Internationalization Variables"
  92. for the precedence of internationalization variables used to determine
  93. the values of locale categories.)
  94. .IP "\fILC_ALL\fP" 10
  95. If set to a non-empty string value, override the values of all the
  96. other internationalization variables.
  97. .IP "\fILC_CTYPE\fP" 10
  98. Determine the locale for the interpretation of sequences of bytes of
  99. text data as characters (for example, single-byte as opposed to
  100. multi-byte characters in arguments).
  101. .IP "\fILC_MESSAGES\fP" 10
  102. .br
  103. Determine the locale that should be used to affect the format and
  104. contents of diagnostic messages written to standard error.
  105. .IP "\fINLSPATH\fP" 10
  106. Determine the location of message catalogs for the processing of
  107. .IR LC_MESSAGES .
  108. .SH "ASYNCHRONOUS EVENTS"
  109. Default.
  110. .SH STDOUT
  111. Not used.
  112. .SH STDERR
  113. The standard error shall be used only for diagnostic messages.
  114. .SH "OUTPUT FILES"
  115. None.
  116. .SH "EXTENDED DESCRIPTION"
  117. None.
  118. .SH "EXIT STATUS"
  119. If one or more operands were specified, all of them have terminated or
  120. were not known by the invoking shell, and the status of the last
  121. operand specified is known, then the exit status of
  122. .IR wait
  123. shall be the exit status information of the command indicated by the
  124. last operand specified. If the process terminated abnormally due to
  125. the receipt of a signal, the exit status shall be greater than 128 and
  126. shall be distinct from the exit status generated by other signals, but
  127. the exact value is unspecified. (See the
  128. .IR kill
  129. .BR \-l
  130. option.) Otherwise, the
  131. .IR wait
  132. utility shall exit with one of the following values:
  133. .IP "\0\0\0\00" 8
  134. The
  135. .IR wait
  136. utility was invoked with no operands and all process IDs known by the
  137. invoking shell have terminated.
  138. .IP "1\(hy126" 8
  139. The
  140. .IR wait
  141. utility detected an error.
  142. .IP "\0\0127" 8
  143. The command identified by the last
  144. .IR pid
  145. operand specified is unknown.
  146. .SH "CONSEQUENCES OF ERRORS"
  147. Default.
  148. .LP
  149. .IR "The following sections are informative."
  150. .SH "APPLICATION USAGE"
  151. On most implementations,
  152. .IR wait
  153. is a shell built-in. If it is called in a subshell or separate utility
  154. execution environment, such as one of the following:
  155. .sp
  156. .RS 4
  157. .nf
  158. (wait)
  159. nohup wait ...
  160. find . -exec wait ... \e;
  161. .fi
  162. .P
  163. .RE
  164. .P
  165. it returns immediately because there are no known process IDs to wait
  166. for in those environments.
  167. .P
  168. Historical implementations of interactive shells have discarded the
  169. exit status of terminated background processes before each shell
  170. prompt. Therefore, the status of background processes was usually lost
  171. unless it terminated while
  172. .IR wait
  173. was waiting for it. This could be a serious problem when a job that
  174. was expected to run for a long time actually terminated quickly with a
  175. syntax or initialization error because the exit status returned was
  176. usually zero if the requested process ID was not found. This volume of POSIX.1\(hy2017 requires
  177. the implementation to keep the status of terminated jobs available
  178. until the status is requested, so that scripts like:
  179. .sp
  180. .RS 4
  181. .nf
  182. j1&
  183. p1=$!
  184. j2&
  185. wait $p1
  186. echo Job 1 exited with status $?
  187. wait $!
  188. echo Job 2 exited with status $?
  189. .fi
  190. .P
  191. .RE
  192. .P
  193. work without losing status on any of the jobs. The shell is allowed to
  194. discard the status of any process if it determines that the application
  195. cannot get the process ID for that process from the shell. It is also
  196. required to remember only
  197. {CHILD_MAX}
  198. number of processes in this way. Since the only way to get the process
  199. ID from the shell is by using the
  200. .BR '!'
  201. shell parameter, the shell is allowed to discard the status of an
  202. asynchronous list if
  203. .BR \(dq$!\(dq
  204. was not referenced before another asynchronous list was started. (This
  205. means that the shell only has to keep the status of the last
  206. asynchronous list started if the application did not reference
  207. .BR \(dq$!\(dq .
  208. If the implementation of the shell is smart enough to determine that a
  209. reference to
  210. .BR \(dq$!\(dq
  211. was not saved anywhere that the application can retrieve it later, it
  212. can use this information to trim the list of saved information. Note
  213. also that a successful call to
  214. .IR wait
  215. with no operands discards the exit status of all asynchronous lists.)
  216. .P
  217. If the exit status of
  218. .IR wait
  219. is greater than 128, there is no way for the application to know if the
  220. waited-for process exited with that value or was killed by a signal.
  221. Since most utilities exit with small values, there is seldom any
  222. ambiguity. Even in the ambiguous cases, most applications just need to
  223. know that the asynchronous job failed; it does not matter whether it
  224. detected an error and failed or was killed and did not complete its job
  225. normally.
  226. .SH EXAMPLES
  227. Although the exact value used when a process is terminated by a signal
  228. is unspecified, if it is known that a signal terminated a process, a
  229. script can still reliably determine which signal by using
  230. .IR kill
  231. as shown by the following script:
  232. .sp
  233. .RS 4
  234. .nf
  235. sleep 1000&
  236. pid=$!
  237. kill -kill $pid
  238. wait $pid
  239. echo $pid was terminated by a SIG$(kill -l $?) signal.
  240. .fi
  241. .P
  242. .RE
  243. .P
  244. If the following sequence of commands is run in less than 31 seconds:
  245. .sp
  246. .RS 4
  247. .nf
  248. sleep 257 | sleep 31 &
  249. jobs -l %%
  250. .fi
  251. .P
  252. .RE
  253. .P
  254. either of the following commands returns the exit status of the second
  255. .IR sleep
  256. in the pipeline:
  257. .sp
  258. .RS 4
  259. .nf
  260. wait \fI<pid of sleep 31>\fP
  261. wait %%
  262. .fi
  263. .P
  264. .RE
  265. .SH RATIONALE
  266. The description of
  267. .IR wait
  268. does not refer to the
  269. \fIwaitpid\fR()
  270. function from the System Interfaces volume of POSIX.1\(hy2017 because that would needlessly overspecify this
  271. interface. However, the wording means that
  272. .IR wait
  273. is required to wait for an explicit process when it is given an
  274. argument so that the status information of other processes is not
  275. consumed. Historical implementations use the
  276. \fIwait\fR()
  277. function defined in the System Interfaces volume of POSIX.1\(hy2017 until
  278. \fIwait\fR()
  279. returns the requested process ID or finds that the requested process
  280. does not exist. Because this means that a shell script could not
  281. reliably get the status of all background children if a second
  282. background job was ever started before the first job finished, it is
  283. recommended that the
  284. .IR wait
  285. utility use a method such as the functionality provided by the
  286. \fIwaitpid\fR()
  287. function.
  288. .P
  289. The ability to wait for multiple
  290. .IR pid
  291. operands was adopted from the KornShell.
  292. .P
  293. This new functionality was added because it is needed to determine the
  294. exit status of any asynchronous list accurately. The only
  295. compatibility problem that this change creates is for a script like
  296. .sp
  297. .RS 4
  298. .nf
  299. while sleep 60 do
  300. job& echo Job started $(date) as $! done
  301. .fi
  302. .P
  303. .RE
  304. .P
  305. which causes the shell to monitor all of the jobs started until the
  306. script terminates or runs out of memory. This would not be a problem
  307. if the loop did not reference
  308. .BR \(dq$!\(dq
  309. or if the script would occasionally
  310. .IR wait
  311. for jobs it started.
  312. .SH "FUTURE DIRECTIONS"
  313. None.
  314. .SH "SEE ALSO"
  315. .IR "Chapter 2" ", " "Shell Command Language",
  316. .IR "\fIkill\fR\^",
  317. .IR "\fIsh\fR\^"
  318. .P
  319. The Base Definitions volume of POSIX.1\(hy2017,
  320. .IR "Section 3.204" ", " "Job Control Job ID",
  321. .IR "Chapter 8" ", " "Environment Variables"
  322. .P
  323. The System Interfaces volume of POSIX.1\(hy2017,
  324. .IR "\fIwait\fR\^(\|)"
  325. .\"
  326. .SH COPYRIGHT
  327. Portions of this text are reprinted and reproduced in electronic form
  328. from IEEE Std 1003.1-2017, Standard for Information Technology
  329. -- Portable Operating System Interface (POSIX), The Open Group Base
  330. Specifications Issue 7, 2018 Edition,
  331. Copyright (C) 2018 by the Institute of
  332. Electrical and Electronics Engineers, Inc and The Open Group.
  333. In the event of any discrepancy between this version and the original IEEE and
  334. The Open Group Standard, the original IEEE and The Open Group Standard
  335. is the referee document. The original Standard can be obtained online at
  336. http://www.opengroup.org/unix/online.html .
  337. .PP
  338. Any typographical or formatting errors that appear
  339. in this page are most likely
  340. to have been introduced during the conversion of the source files to
  341. man page format. To report such errors, see
  342. https://www.kernel.org/doc/man-pages/reporting_bugs.html .