Provided by: manpages-posix_2017a-2_all bug

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‐2017,
                     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‐2017,  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‐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  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‐2017  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‐2017 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‐2017, Section 3.204, Job Control Job ID, Chapter 8,
       Environment Variables

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

COPYRIGHT

       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 .