Ubuntu Manpage: wait - await process completion

NAME

       wait - await process completion

SYNOPSIS

       wait [pid...]

DESCRIPTION

       When  an  asynchronous list (see Asynchronous Lists ) 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 Shell Execution Environment .

       If  the  wait  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.

       If one or more pid operands are specified that represent known process IDs, the wait utility  shall  wait
       until  all  of  them  have  terminated.  If one or more pid operands are specified that represent unknown
       process IDs, wait shall treat them as if they were known process IDs that exited with  exit  status  127.
       The  exit  status  returned  by the wait utility shall be the exit status of the process requested by the
       last pid operand.

       The known process IDs are applicable only  for  invocations  of  wait  in  the  current  shell  execution
       environment.

OPTIONS

       None.

OPERANDS

       The following operand shall be supported:

       pid    One of the following:

               1. The unsigned decimal integer process ID of a command, for which the utility is to wait for the
                  termination.

               2. A  job control job ID (see the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.203,
                  Job Control Job ID) that identifies a background process group  to  be  waited  for.  The  job
                  control  job  ID  notation  is  applicable  only  for invocations of wait in the current shell
                  execution environment; see Shell Execution Environment . The exit  status  of  wait  shall  be
                  determined by the last command in the pipeline.

              Note:
                     The  job  control  job  ID  type  of  pid  is only available on systems supporting the User
                     Portability Utilities option.

STDIN

       Not used.

INPUT FILES

       None.

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of wait:

       LANG   Provide a default value for the internationalization variables that are unset or  null.  (See  the
              Base  Definitions  volume of IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for
              the  precedence  of  internationalization  variables  used  to  determine  the  values  of  locale
              categories.)

       LC_ALL If  set  to  a  non-empty  string value, override the values of all the other internationalization
              variables.

       LC_CTYPE
              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).

       LC_MESSAGES
              Determine  the locale that should be used to affect the format and contents of diagnostic messages
              written to standard error.

       NLSPATH
              Determine the location of message catalogs for the processing of LC_MESSAGES .

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       Not used.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       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 wait 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
       kill -l option.) Otherwise, the wait utility shall exit with one of the following values:

           0  The wait utility was invoked with no operands and all process IDs known by the invoking shell have
              terminated.

       1-126  The wait utility detected an error.

         127  The command identified by the last pid operand specified is unknown.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

On most implementations, wait is a shell built-in. If it is called in a subshell or separate utility
execution environment, such as one of the following:

(wait)
nohup wait ...
find . -exec wait ... \;

it returns immediately because there are no known process IDs to wait for in those environments.

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 wait 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:

j1&
p1=$!
j2&
wait $p1
echo Job 1 exited with status $?
wait $!
echo Job 2 exited with status $?

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 '!' shell parameter, the shell is allowed to discard the status
of an asynchronous list if "$!" 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 "$!" . If the implementation of the shell is smart enough to determine that a reference
to "$!" 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 wait with no operands discards
the exit status of all asynchronous lists.)

If the exit status of wait 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.

EXAMPLES

       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  kill  as
       shown by the following script:

              sleep 1000&
              pid=$!
              kill -kill $pid
              wait $pid
              echo $pid was terminated by a SIG$(kill -l $?) signal.

       If the following sequence of commands is run in less than 31 seconds:

              sleep 257 | sleep 31 &
              jobs -l %%

       either of the following commands returns the exit status of the second sleep in the pipeline:

              wait <pid of sleep 31>wait %%

RATIONALE

The description of wait does not refer to the waitpid() function from the System Interfaces volume of
IEEE Std 1003.1-2001 because that would needlessly overspecify this interface. However, the wording means
that wait 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 wait() function
defined in the System Interfaces volume of IEEE Std 1003.1-2001 until wait() 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 wait utility use a method such as the
functionality provided by the waitpid() function.

The ability to wait for multiple pid operands was adopted from the KornShell.

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

while sleep 60 do
job& echo Job started $(date) as $! done

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 "$!" or if the script would
occasionally wait for jobs it started.

FUTURE DIRECTIONS

       None.

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                                   2003                                               WAIT(P)