mdw@git.distorted.org.uk Git - 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 [ \-K ]
   8 .RB [ \-k
   9 .IR time ]
  10 .RB [ \-b
  11 .IR time ]
  12 .RB [ \-s
  13 .IR signal ]
  14 .br
  15         \c
  16 .I time
  17 .I command
  18 .RI [ arguments ...]
  19 .
  20 .SH DESCRIPTION
  21 The
  22 .B mtimeout
  23 command runs a specified program for at most a given amount of
  24 .IR time .
  25 The
  26 .I time
  27 may be fractional (with a decimal point), and may be followed by a unit
  28 suffix:
  29 .RB ` s '
  30 for seconds,
  31 .RB ` m '
  32 for minutes,
  33 .RB ` h '
  34 for hours, and
  35 .RB ` d '
  36 for days.
  37 .PP
  38 It works by running the given command as a separate process group.  It
  39 then waits either for the top-level process (only) to exit, or for the
  40 timeout to expire, whichever happens first.  If the process exits, then
  41 .B mtimeout
  42 exits too, setting its exit status to match.  Any other processes which
  43 may have been started are left unmolested.
  44 .PP
  45 On the other hand, if the timeout goes off, then
  46 .B mtimeout
  47 sends its child process group the specified signal, by default
  48 .BR SIGTERM ,
  49 though you can choose a different one with the
  50 .B \-s
  51 option.  It then waits an additional five seconds (configurable with
  52 the
  53 .B \-k
  54 option).  If the child still hasn't exited, it sends
  55 .B SIGKILL
  56 to the process group and waits a further five seconds (configurable
  57 with the
  58 .B \-b
  59 option).  If the child still hasn't exited in this time, then
  60 .B mtimeout
  61 gives up and exits.
  62 .PP
  63 The following command-line options are recognized.
  64 .TP
  65 .B \-h, \-\-help
  66 Prints a reasonably full help message describing the arguments and
  67 options to standard output, and exits successfully.
  68 .TP
  69 .B \-v, \-\-version
  70 Prints the program's version number to standard output, and exits
  71 successfully.
  72 .TP
  73 .B \-u, \-\-usage
  74 Prints a brief usage summary to standard output, and exits successfully.
  75 .TP
  76 .BI "\-b, \-\-bored-after=" time
  77 After sending
  78 .B SIGKILL
  79 (or, with
  80 .BR \-K ,
  81 the original signal)
  82 wait for
  83 .I time
  84 before giving up and declaring the child process undead.  The default
  85 wait is five seconds.  The
  86 .I time
  87 may have a unit suffix.
  88 .TP
  89 .B "\-K, \-\-no-kill"
  90 Don't send a
  91 .B SIGKILL
  92 to the process: just wait for a while (see the
  93 .B \-b
  94 option) after sending the original signal to see whether it actually
  95 dies.
  96 .TP
  97 .BI "\-k, \-\-kill-after=" time
  98 After sending a signal, wait for
  99 .I time
 100 before sending
 101 .BR SIGKILL .
 102 The default wait is five seconds.  The
 103 .I time
 104 may have a unit suffix.
 105 This option has no effect if
 106 .BR \-K
 107 is set.
 108 .TP
 109 .BI "\-s, \-\-signal=" signal
 110 Send
 111 .I signal
 112 to the child process if it takes too long.  The default is to send
 113 .BR SIGTERM .
 114 A signal may be given numerically (e.g., 9 for
 115 .BR SIGKILL )
 116 or by name (e.g.,
 117 .BR KILL ).
 118 .PP
 119 The
 120 .B mtimeout
 121 program sets its exit status as follows.
 122 .TP
 123 0\(en127, 255
 124 The child process ran to completion within the given time:
 125 .BR mtimeout 's
 126 exit status is the same as that of the child process.
 127 (Whatever status the child exits with will be propagated;
 128 but if it exits with some status other than these then
 129 there is a risk that it will be conflict
 130 with a status used by
 131 .B mtimeout
 132 and be misinterpreted.)
 133 .TP
 134 128
 135 The child process exited in a way which
 136 .B mtimeout
 137 could not interpret.
 138 .TP
 139 129\(em250
 140 The child process was killed by a signal: the exit status is 128 higher
 141 than the signal number.  If
 142 .B mtimeout
 143 had to kill the child because it took too long, then its exit status
 144 will be like this.
 145 .TP
 146 251
 147 The child took too long and couldn't be killed:
 148 .B mtimeout
 149 gave up waiting.
 150 .TP
 151 252
 152 The target program couldn't be started: an error message was written to
 153 standard error.
 154 .TP
 155 253
 156 The
 157 .B mtimeout
 158 program couldn't parse the arguments provided to it: an error message
 159 was written to standard error.
 160 .TP
 161 254
 162 A system call made by
 163 .B mtimeout
 164 failed unexpectedly: an error message was written to standard error.
 165 .
 166 .SH BUGS
 167 Because
 168 .B mtimeout
 169 works by running its child process in a separate process group, it
 170 interacts oddly with interactive shells.  If the child process group
 171 attempts to do terminal I/O (particularly reading from a terminal) then
 172 it may be sent signals to suspend it.  This may or may not make matters
 173 worse.
 174 .PP
 175 The
 176 .B mtimeout
 177 program makes an effort to propagate interesting signals to its child
 178 process group.  Currently, it propagates
 179 .BR SIGTSTP ,
 180 .BR SIGCONT ,
 181 .BR SIGINT ,
 182 .BR SIGHUP ,
 183 and
 184 .BR SIGQUIT .
 185 This list is subject to change: I don't think I'm likely to remove any
 186 of the current signals from it, but I might add some; or I might add an
 187 option to control this list.
 188 .PP
 189 If you suspend
 190 .B mtimeout
 191 and its child process group, the timer continues running anyway.  (I'm
 192 not quite sure whether this is the right behaviour.)
 193 .PP
 194 Nested timeouts don't work in a useful way if the outer timeout expires
 195 earlier than the inner one.  Since
 196 .B SIGTERM
 197 isn't propagated (currently, at least), the inner
 198 .B mtimeout
 199 is killed by the outer one, and loses control of its child process
 200 group.  You could possibly work around this by sending
 201 .B SIGQUIT
 202 instead.
 203 .PP
 204 Perhaps it would be useful to allow configuration of the `panic'
 205 timeouts after the initial timeout signal is sent.
 206 .
 207 .SH AUTHOR
 208 Mark Wooding, <mdw@distorted.org.uk>