PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

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

PROLOG         top

       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         top

       wait — await process completion

SYNOPSIS         top

       wait [pid...]

DESCRIPTION         top

       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         top

       None.

OPERANDS         top

       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         top

       Not used.

INPUT FILES         top

       None.

ENVIRONMENT VARIABLES         top

       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         top

       Default.

STDOUT         top

       Not used.

STDERR         top

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES         top

       None.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       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         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       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         top

       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         top

       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         top

       None.

SEE ALSO         top

       Chapter 2, Shell Command Language, kill(1p), sh(1p)

       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(3p)

COPYRIGHT         top

       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(1P)