345 lines
13 KiB
HTML
345 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>wait</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="wait"></a> <a name="tag_04_168"></a><!-- wait -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_168_01"></a>NAME</h4>
|
|
|
|
<blockquote>wait - await process completion</blockquote>
|
|
|
|
<h4><a name="tag_04_168_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>wait</tt> <b>[</b><i>pid</i><tt>...</tt><b>]</b></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>When an asynchronous list (see <a href="xcu_chap02.html#tag_02_09_03_02"><i>Asynchronous Lists</i></a> ) is started by the
|
|
shell, the process ID of the last command in each element of the asynchronous list shall become known in the current shell
|
|
execution environment; see <a href="xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> .</p>
|
|
|
|
<p>If the <i>wait</i> utility is invoked with no operands, it shall wait until all process IDs known to the invoking shell have
|
|
terminated and exit with a zero exit status.</p>
|
|
|
|
<p>If one or more <i>pid</i> operands are specified that represent known process IDs, the <i>wait</i> utility shall wait until all
|
|
of them have terminated. If one or more <i>pid</i> operands are specified that represent unknown process IDs, <i>wait</i> shall
|
|
treat them as if they were known process IDs that exited with exit status 127. The exit status returned by the <i>wait</i> utility
|
|
shall be the exit status of the process requested by the last <i>pid</i> operand.</p>
|
|
|
|
<p>The known process IDs are applicable only for invocations of <i>wait</i> in the current shell execution environment.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operand shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>pid</i></dt>
|
|
|
|
<dd>One of the following:
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The unsigned decimal integer process ID of a command, for which the utility is to wait for the termination.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A job control job ID (see the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap03.html#tag_03_203">Section 3.203, Job Control Job ID</a>) that identifies a background process group to be
|
|
waited for. The job control job ID notation is applicable only for invocations of <i>wait</i> in the current shell execution
|
|
environment; see <a href="xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> . The exit status of <i>wait</i> shall
|
|
be determined by the last command in the pipeline. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>The job control job ID type of <i>pid</i> is only available on systems supporting the User Portability Utilities option.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3"></li>
|
|
</ol>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>wait</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used only for diagnostic messages.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>If one or more operands were specified, all of them have terminated or were not known by the invoking shell, and the status of
|
|
the last operand specified is known, then the exit status of <i>wait</i> shall be the exit status information of the command
|
|
indicated by the last operand specified. If the process terminated abnormally due to the receipt of a signal, the exit status shall
|
|
be greater than 128 and shall be distinct from the exit status generated by other signals, but the exact value is unspecified. (See
|
|
the <a href="../utilities/kill.html"><i>kill</i></a> <b>-l</b> option.) Otherwise, the <i>wait</i> utility shall exit with one of
|
|
the following values:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>The <i>wait</i> utility was invoked with no operands and all process IDs known by the invoking shell have terminated.</dd>
|
|
|
|
<dt>1-126</dt>
|
|
|
|
<dd>The <i>wait</i> utility detected an error.</dd>
|
|
|
|
<dt> 127</dt>
|
|
|
|
<dd>The command identified by the last <i>pid</i> operand specified is unknown.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_168_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>On most implementations, <i>wait</i> is a shell built-in. If it is called in a subshell or separate utility execution
|
|
environment, such as one of the following:</p>
|
|
|
|
<pre>
|
|
<tt>(wait)
|
|
nohup wait ...
|
|
find . -exec wait ... \;
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>it returns immediately because there are no known process IDs to wait for in those environments.</p>
|
|
|
|
<p>Historical implementations of interactive shells have discarded the exit status of terminated background processes before each
|
|
shell prompt. Therefore, the status of background processes was usually lost unless it terminated while <i>wait</i> was waiting for
|
|
it. This could be a serious problem when a job that was expected to run for a long time actually terminated quickly with a syntax
|
|
or initialization error because the exit status returned was usually zero if the requested process ID was not found. This volume of
|
|
IEEE Std 1003.1-2001 requires the implementation to keep the status of terminated jobs available until the status is
|
|
requested, so that scripts like:</p>
|
|
|
|
<pre>
|
|
<tt>j1&
|
|
p1=$!
|
|
j2&
|
|
wait $p1
|
|
echo Job 1 exited with status $?
|
|
wait $!
|
|
echo Job 2 exited with status $?
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>work without losing status on any of the jobs. The shell is allowed to discard the status of any process if it determines that
|
|
the application cannot get the process ID for that process from the shell. It is also required to remember only {CHILD_MAX} number
|
|
of processes in this way. Since the only way to get the process ID from the shell is by using the <tt>'!'</tt> shell parameter, the
|
|
shell is allowed to discard the status of an asynchronous list if <tt>"$!"</tt> was not referenced before another asynchronous list
|
|
was started. (This means that the shell only has to keep the status of the last asynchronous list started if the application did
|
|
not reference <tt>"$!"</tt> . If the implementation of the shell is smart enough to determine that a reference to <tt>"$!"</tt> was
|
|
not saved anywhere that the application can retrieve it later, it can use this information to trim the list of saved information.
|
|
Note also that a successful call to <i>wait</i> with no operands discards the exit status of all asynchronous lists.)</p>
|
|
|
|
<p>If the exit status of <i>wait</i> is greater than 128, there is no way for the application to know if the waited-for process
|
|
exited with that value or was killed by a signal. Since most utilities exit with small values, there is seldom any ambiguity. Even
|
|
in the ambiguous cases, most applications just need to know that the asynchronous job failed; it does not matter whether it
|
|
detected an error and failed or was killed and did not complete its job normally.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>Although the exact value used when a process is terminated by a signal is unspecified, if it is known that a signal terminated a
|
|
process, a script can still reliably determine which signal by using <a href="../utilities/kill.html"><i>kill</i></a> as shown by
|
|
the following script:</p>
|
|
|
|
<pre>
|
|
<tt>sleep 1000&
|
|
pid=$!
|
|
kill -kill $pid
|
|
wait $pid
|
|
echo $pid was terminated by a SIG$(kill -l $?) signal.
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>If the following sequence of commands is run in less than 31 seconds:</p>
|
|
|
|
<pre>
|
|
<tt>sleep 257 | sleep 31 &
|
|
jobs -l %%
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>either of the following commands returns the exit status of the second <a href="../utilities/sleep.html"><i>sleep</i></a> in the
|
|
pipeline:</p>
|
|
|
|
<pre>
|
|
<tt>wait</tt> <i><pid of sleep 31></i><tt>wait %%
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The description of <i>wait</i> does not refer to the <a href="../functions/waitpid.html"><i>waitpid</i>()</a> function from the
|
|
System Interfaces volume of IEEE Std 1003.1-2001 because that would needlessly overspecify this interface. However, the
|
|
wording means that <i>wait</i> is required to wait for an explicit process when it is given an argument so that the status
|
|
information of other processes is not consumed. Historical implementations use the <a href=
|
|
"../functions/wait.html"><i>wait</i>()</a> function defined in the System Interfaces volume of IEEE Std 1003.1-2001 until
|
|
<a href="../functions/wait.html"><i>wait</i>()</a> returns the requested process ID or finds that the requested process does not
|
|
exist. Because this means that a shell script could not reliably get the status of all background children if a second background
|
|
job was ever started before the first job finished, it is recommended that the <i>wait</i> utility use a method such as the
|
|
functionality provided by the <a href="../functions/waitpid.html"><i>waitpid</i>()</a> function.</p>
|
|
|
|
<p>The ability to wait for multiple <i>pid</i> operands was adopted from the KornShell.</p>
|
|
|
|
<p>This new functionality was added because it is needed to determine the exit status of any asynchronous list accurately. The only
|
|
compatibility problem that this change creates is for a script like</p>
|
|
|
|
<pre>
|
|
<tt>while sleep 60 do
|
|
job& echo Job started $(date) as $! done
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>which causes the shell to monitor all of the jobs started until the script terminates or runs out of memory. This would not be a
|
|
problem if the loop did not reference <tt>"$!"</tt> or if the script would occasionally <i>wait</i> for jobs it started.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xcu_chap02.html#tag_02"><i>Shell Command Language</i></a> , <a href="kill.html"><i>kill</i>()</a> , <a href=
|
|
"sh.html"><i>sh</i></a> , the System Interfaces volume of IEEE Std 1003.1-2001, <a href=
|
|
"../functions/wait.html"><i>wait</i>()</a>, <a href="../functions/waitpid.html"><i>waitpid</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_168_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 2.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|