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