1 .TH "mtimeout" 1 "5 June 2011" "Mark Wooding" "Toys"
3 mtimeout \- run a program for at most a given amount of time
23 command runs a specified program for at most a given amount of
27 may be fractional (with a decimal point), and may be followed by a unit
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
42 exits too, setting its exit status to match. Any other processes which
43 may have been started are left unmolested.
45 On the other hand, if the timeout goes off, then
47 sends its child process group the specified signal, by default
49 though you can choose a different one with the
51 option. It then waits an additional five seconds (configurable with
54 option). If the child still hasn't exited, it sends
56 to the process group and waits a further five seconds (configurable
59 option). If the child still hasn't exited in this time, then
63 The following command-line options are recognized.
66 Prints a reasonably full help message describing the arguments and
67 options to standard output, and exits successfully.
70 Prints the program's version number to standard output, and exits
74 Prints a brief usage summary to standard output, and exits successfully.
76 .BI "\-b, \-\-bored-after=" time
84 before giving up and declaring the child process undead. The default
85 wait is five seconds. The
87 may have a unit suffix.
92 to the process: just wait for a while (see the
94 option) after sending the original signal to see whether it actually
97 .BI "\-k, \-\-kill-after=" time
98 After sending a signal, wait for
102 The default wait is five seconds. The
104 may have a unit suffix.
105 This option has no effect if
109 .BI "\-s, \-\-signal=" signal
112 to the child process if it takes too long. The default is to send
114 A signal may be given numerically (e.g., 9 for
121 program sets its exit status as follows.
124 The child process ran to completion within the given time:
126 exit status is the same as that of the child process.
129 The child process exited in a way which
132 (Whatever status the child exits with will be propagated;
133 but if it exits with some status other than these then
134 there is a risk that it will be conflict
135 with a status used by
137 and be misinterpreted.)
140 The child process was killed by a signal: the exit status is 128 higher
141 than the signal number. If
143 had to kill the child because it took too long, then its exit status
147 The child took too long and couldn't be killed:
152 The target program couldn't be started: an error message was written to
158 program couldn't parse the arguments provided to it: an error message
159 was written to standard error.
162 A system call made by
164 failed unexpectedly: an error message was written to standard error.
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
177 program makes an effort to propagate interesting signals to its child
178 process group. Currently, it propagates
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.
191 and its child process group, the timer continues running anyway. (I'm
192 not quite sure whether this is the right behaviour.)
194 Nested timeouts don't work in a useful way if the outer timeout expires
195 earlier than the inner one. Since
197 isn't propagated (currently, at least), the inner
199 is killed by the outer one, and loses control of its child process
200 group. You could possibly work around this by sending
204 Perhaps it would be useful to allow configuration of the `panic'
205 timeouts after the initial timeout signal is sent.
208 Mark Wooding, <mdw@distorted.org.uk>