wait

WAIT(1POSIX)                POSIX Programmer's Manual               WAIT(1POSIX)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the corresponding
       Linux manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.


NAME
       wait — await process completion

SYNOPSIS
       wait [pid...]

DESCRIPTION
       When an asynchronous list (see Section 2.9.3.1, Examples) 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 Section 2.12, 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
                     POSIX.1‐2008, Section 3.204, 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 Section 2.12, 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
                 POSIX.1‐2008, 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 POSIX.1‐2008 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 POSIX.1‐2008 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 POSIX.1‐2008 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.

SEE ALSO
       Chapter 2, Shell Command Language, kill, sh

       The Base Definitions volume of POSIX.1‐2008, Section 3.204, Job Control
       Job ID, Chapter 8, Environment Variables

       The System Interfaces volume of POSIX.1‐2008, wait()

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical
       and Electronics Engineers, Inc and The Open Group.  (This is POSIX.1-2008
       with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most
       likely to have been introduced during the conversion of the source files
       to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                   2013                          WAIT(1POSIX)