Man Pages

wait(1p) - phpMan wait(1p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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 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 ter-
                  mination.


               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  exam-
              ple, 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 writ-
              ten 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 ter-
              minated.

       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 pro-
       cesses before each shell prompt. Therefore, the status of background processes was usually lost unless it  ter-
       minated  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 imple-
       mentation  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 recom-
       mended 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
       Shell Command Language, kill(), sh, the System Interfaces volume of IEEE Std 1003.1-2001, wait(), waitpid()

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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(1P)