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



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

NNAAMMEE
       wait -- await process completion

SSYYNNOOPPSSIISS
       wait [[_p_i_d...]]

DDEESSCCRRIIPPTTIIOONN
       When an asynchronous list (see _S_e_c_t_i_o_n _2_._9_._3_._1, _E_x_a_m_p_l_e_s) 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 _S_e_c_t_i_o_n _2_._1_2, _S_h_e_l_l _E_x_e_c_u_t_i_o_n _E_n_v_i_r_o_n_m_e_n_t.

       If the _w_a_i_t 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 _p_i_d operands are specified that represent known process
       IDs, the _w_a_i_t utility shall wait until all of them have terminated. If
       one or more _p_i_d operands are specified that represent unknown process
       IDs, _w_a_i_t shall treat them as if they were known process IDs that
       exited with exit status 127. The exit status returned by the _w_a_i_t
       utility shall be the exit status of the process requested by the last
       _p_i_d operand.

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

OOPPTTIIOONNSS
       None.

OOPPEERRAANNDDSS
       The following operand shall be supported:

       _p_i_d       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-2017, _S_e_c_t_i_o_n _3_._2_0_4, _J_o_b _C_o_n_t_r_o_l _J_o_b _I_D) that
                     identifies a background process group to be waited for.
                     The job control job ID notation is applicable only for
                     invocations of _w_a_i_t in the current shell execution
                     environment; see _S_e_c_t_i_o_n _2_._1_2, _S_h_e_l_l _E_x_e_c_u_t_i_o_n
                     _E_n_v_i_r_o_n_m_e_n_t.  The exit status of _w_a_i_t shall be determined
                     by the last command in the pipeline.

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

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _w_a_i_t:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

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

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

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       Not used.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       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 _w_a_i_t 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 _k_i_l_l --ll option.) Otherwise, the _w_a_i_t utility
       shall exit with one of the following values:

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

       1-126   The _w_a_i_t utility detected an error.

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

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       On most implementations, _w_a_i_t 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 _w_a_i_t 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-2017 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 _w_a_i_t with no operands discards the exit status of
       all asynchronous lists.)

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

EEXXAAMMPPLLEESS
       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 _k_i_l_l 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
       _s_l_e_e_p in the pipeline:


           wait _<_p_i_d _o_f _s_l_e_e_p _3_1_>
           wait %%

RRAATTIIOONNAALLEE
       The description of _w_a_i_t does not refer to the _w_a_i_t_p_i_d() function from
       the System Interfaces volume of POSIX.1-2017 because that would
       needlessly overspecify this interface. However, the wording means that
       _w_a_i_t 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 _w_a_i_t() function defined in
       the System Interfaces volume of POSIX.1-2017 until _w_a_i_t() 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
       _w_a_i_t utility use a method such as the functionality provided by the
       _w_a_i_t_p_i_d() function.

       The ability to wait for multiple _p_i_d 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
       _w_a_i_t for jobs it started.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _C_h_a_p_t_e_r _2, _S_h_e_l_l _C_o_m_m_a_n_d _L_a_n_g_u_a_g_e, _k_i_l_l, _s_h

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _3_._2_0_4, _J_o_b _C_o_n_t_r_o_l
       _J_o_b _I_D, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s

       The System Interfaces volume of POSIX.1-2017, _w_a_i_t()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       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                  2017                              WAIT(1)
