chiark - git - mdw - misc/blob - mtimeout.1

   1 .TH "mtimeout" 1 "5 June 2011" "Mark Wooding" "Toys"
   2 .SH NAME
   3 mtimeout \- run a program for at most a given amount of time
   4 .
   5 .SH SYNOPSIS
   6 .B mtimeout
   7 .RB [ \-s
   8 .IR signal ]
   9 .I seconds
  10 .I command
  11 .RI [ arguments ...]
  12 .
  13 .SH DESCRIPTION
  14 The
  15 .B mtimeout
  16 command runs a specified program for at most a given number of
  17 .IR seconds .
  18 .PP
  19 It works by running the given command as a separate process group.  It
  20 then waits either for the top-level process (only) to exit, or for the
  21 timeout to expire, whichever happens first.  If the process exits, then
  22 .B mtimeout
  23 exits too, setting its exit status to match.  Any other processes which
  24 may have been started are left unmolested.
  25 .PP
  26 On the other hand, if the timeout goes off, then
  27 .B mtimeout
  28 sends its child process group the specified signal, by default
  29 .BR SIGTERM ,
  30 though you can choose a different one with the
  31 .B \-s
  32 option.  It then waits an additional five seconds.  If the child still
  33 hasn't exited, it sends
  34 .B SIGKILL
  35 to the process group and waits a further five seconds.  If the child
  36 still hasn't exited in this time, then
  37 .B mtimeout
  38 gives up and exits.
  39 .PP
  40 The following command-line options are recognized.
  41 .TP
  42 .B \-h, \-\-help
  43 Prints a reasonably full help message describing the arguments and
  44 options to standard output, and exits successfully.
  45 .TP
  46 .B \-v, \-\-version
  47 Prints the program's version number to standard output, and exits
  48 successfully.
  49 .TP
  50 .B \-u, \-\-usage
  51 Prints a brief usage summary to standard output, and exits successfully.
  52 .TP
  53 .BI "\-s, \-\-signal=" signal
  54 Send
  55 .I signal
  56 to the child process if it takes too long.  The default is to send
  57 .BR SIGTERM .
  58 A signal may be given numerically (e.g., 9 for
  59 .BR SIGKILL )
  60 or by name (e.g.,
  61 .BR KILL ).
  62 .PP
  63 The
  64 .B mtimeout
  65 program sets its exit status as follows.
  66 .TP
  67 0\(em127
  68 The child process ran to completion within the given time:
  69 .BR mtimeout 's
  70 exit status is the same as that of the child process.
  71 .TP
  72 128
  73 The child process exited in a way which
  74 .B mtimeout
  75 could not interpret.
  76 .TP
  77 129\(em250
  78 The child process was killed by a signal: the exit status is 128 higher
  79 than the signal number.  If
  80 .B mtimeout
  81 had to kill the child because it took too long, then its exit status
  82 will be like this.
  83 .TP
  84 251
  85 The child took too long and couldn't be killed:
  86 .B mtimeout
  87 gave up waiting.
  88 .TP
  89 252
  90 The target program couldn't be started: an error message was written to
  91 standard error.
  92 .TP
  93 253
  94 The
  95 .B mtimeout
  96 program couldn't parse the arguments provided to it: an error message
  97 was written to standard error.
  98 .TP
  99 254
 100 A system call made by
 101 .B mtimeout
 102 failed unexpectedly: an error message was written to standard error.
 103 .TP
 104 255
 105 Not used.
 106 .
 107 .SH BUGS
 108 Because
 109 .B mtimeout
 110 works by running its child process in a separate process group, it
 111 interacts oddly with interactive shells.  If the child process group
 112 attempts to do terminal I/O (particularly reading from a terminal) then
 113 it may be sent signals to suspend it.  This may or may not make matters
 114 worse.
 115 .PP
 116 The
 117 .B mtimeout
 118 program makes an effort to propagate interesting signals to its child
 119 process group.  Currently, it propagates
 120 .BR SIGTSTP ,
 121 .BR SIGCONT ,
 122 .BR SIGINT ,
 123 .BR SIGHUP ,
 124 and
 125 .BR SIGQUIT .
 126 This list is subject to change: I don't think I'm likely to remove any
 127 of the current signals from it, but I might add some; or I might add an
 128 option to control this list.
 129 .PP
 130 If you suspend
 131 .B mtimeout
 132 and its child process group, the timer continues running anyway.  (I'm
 133 not quite sure whether this is the right behaviour.)
 134 .PP
 135 Nested timeouts don't work in a useful way if the outer timeout expires
 136 earlier than the inner one.  Since
 137 .B SIGTERM
 138 isn't propagated (currently, at least), the inner
 139 .B mtimeout
 140 is killed by the outer one, and loses control of its child process
 141 group.  You could possibly work around this by sending
 142 .B SIGQUIT
 143 instead.
 144 .PP
 145 Perhaps it would be useful to allow configuration of the `panic'
 146 timeouts after the initial timeout signal is sent.
 147 .
 148 .SH AUTHOR
 149 Mark Wooding, <mdw@distorted.org.uk>