mdw@git.distorted.org.uk Git - sgt/utils/blob - after/after.but

   1 \cfg{man-identity}{after}{1}{2008-02-20}{Simon Tatham}{Simon Tatham}
   2
   3 \define{dash} \u2013{-}
   4
   5 \title Man page for \c{after}
   6
   7 \U NAME
   8
   9 \c{after} \dash wait until an unrelated process has terminated
  10
  11 \U SYNOPSIS
  12
  13 \c after [ -x | -z ] pid
  14 \e bbbbb   bb   bb   iii
  15
  16 \U DESCRIPTION
  17
  18 \c{after} lets you specify a process by its numeric PID, and then
  19 waits until that process has terminated. If possible, it returns the
  20 process's exit code as well.
  21
  22 You might use \c{after} if you had started a long-running process in
  23 one window and then realised that you should have told the shell to
  24 do something else after it finished. For example, after typing
  25 \cq{make} to begin a long build run, you suddenly realise you should
  26 have typed \cq{make && ./runtests.sh}, so that you wouldn't have to
  27 be physically present to kick off the test run after the build
  28 completed, and so that you could take one long coffee break instead
  29 of two short ones. In this situation you could use \c{after} to
  30 solve your problem: use \cw{ps}(\e{1}) to look up the process ID of
  31 the \cw{make} process, and then type a command such as \cq{after
  32 34530 && ./runtests.sh} in a second terminal window.
  33
  34 The operation of waiting for an arbitrary process is not an easy one
  35 on Unix, so the \c{after} command supports multiple methods of
  36 achieving it and will try them in order until one works. Some
  37 methods allow the exit code of the process to be retrieved, in which
  38 case \c{after} will return the same value; others do not.
  39
  40 \U OPTIONS
  41
  42 \dt \cw{-x}
  43
  44 \dd Restricts \c{after} to only attempting methods which retrieve
  45 the process's exit code. These methods typically require \c{after}
  46 and the target process to be running under the same user ID. If no
  47 available method works, \c{after} will fail.
  48
  49 \dt \cw{-z}
  50
  51 \dd Causes \c{after} to always return 0 (success) after detecting
  52 that the process has terminated, whether or not its exit code was
  53 available.
  54
  55 \U EXIT STATUS
  56
  57 If it settles on a method which provides the target process's exit
  58 code, \c{after} will return the same code itself (unless you disable
  59 this with the \cw{-z} option). Hence, you can use the shell \cw{&&}
  60 operator to run other commands which are conditional on the target
  61 process succeeding (as in the example above).
  62
  63 If it has to fall back to a method which does not provide the exit
  64 code, \c{after} will return 0 (success) when the process terminates.
  65
  66 If something goes so badly wrong that \c{after} was unable to
  67 reliably wait for the process at all, it will return 127.
  68
  69 \U BUGS
  70
  71 There are not enough methods supported.
  72
  73 The whole concept of \c{after} has an inherent bug in the form of a
  74 race condition: if you're not careful, the target process could
  75 terminate in between you looking up its PID and typing the \c{after}
  76 command. If your process looks as if it might terminate within the
  77 time it takes to type the command, it's probably better not to try
  78 using \c{after} at all.
  79
  80 \U LICENCE
  81
  82 \c{after} is free software, distributed under the MIT licence. Type
  83 \cq{after --licence} to see the full licence text.
  84
  85 \versionid $Id$