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