--- /dev/null
+.TH "mtimeout" 1 "5 June 2011" "Mark Wooding" "Toys"
+.SH NAME
+mtimeout \- run a program for at most a given amount of time
+.
+.SH SYNOPSIS
+.B mtimeout
+.RB [ \-s
+.IR signal ]
+.I seconds
+.I command
+.RI [ arguments ...]
+.
+.SH DESCRIPTION
+The
+.B mtimeout
+command runs a specified program for at most a given number of
+.IR seconds .
+.PP
+It works by running the given command as a separate process group. It
+then waits either for the top-level process (only) to exit, or for the
+timeout to expire, whichever happens first. If the process exits, then
+.B mtimeout
+exits too, setting its exit status to match. Any other processes which
+may have been started are left unmolested.
+.PP
+On the other hand, if the timeout goes off, then
+.B mtimeout
+sends its child process group the specified signal, by default
+.BR SIGTERM ,
+though you can choose a different one with the
+.B \-s
+option. It then waits an additional five seconds. If the child still
+hasn't exited, it sends
+.B SIGKILL
+to the process group and waits a further five seconds. If the child
+still hasn't exited in this time, then
+.B mtimeout
+gives up and exits.
+.PP
+The following command-line options are recognized.
+.TP
+.B \-h, \-\-help
+Prints a reasonably full help message describing the arguments and
+options to standard output, and exits successfully.
+.TP
+.B \-v, \-\-version
+Prints the program's version number to standard output, and exits
+successfully.
+.TP
+.B \-u, \-\-usage
+Prints a brief usage summary to standard output, and exits successfully.
+.TP
+.BI "\-s, \-\-signal=" signal
+Send
+.I signal
+to the child process if it takes too long. The default is to send
+.BR SIGTERM .
+A signal may be given numerically (e.g., 9 for
+.BR SIGKILL )
+or by name (e.g.,
+.BR KILL ).
+.PP
+The
+.B mtimeout
+program sets its exit status as follows.
+.TP
+0\(em127
+The child process ran to completion within the given time:
+.BR mtimeout 's
+exit status is the same as that of the child process.
+.TP
+128
+The child process exited in a way which
+.B mtimeout
+could not interpret.
+.TP
+129\(em250
+The child process was killed by a signal: the exit status is 128 higher
+than the signal number. If
+.B mtimeout
+had to kill the child because it took too long, then its exit status
+will be like this.
+.TP
+251
+The child took too long and couldn't be killed:
+.B mtimeout
+gave up waiting.
+.TP
+252
+The target program couldn't be started: an error message was written to
+standard error.
+.TP
+253
+The
+.B mtimeout
+program couldn't parse the arguments provided to it: an error message
+was written to standard error.
+.TP
+254
+A system call made by
+.B mtimeout
+failed unexpectedly: an error message was written to standard error.
+.TP
+255
+Not used.
+.
+.SH BUGS
+Because
+.B mtimeout
+works by running its child process in a separate process group, it
+interacts oddly with interactive shells. If the child process group
+attempts to do terminal I/O (particularly reading from a terminal) then
+it may be sent signals to suspend it. This may or may not make matters
+worse.
+.PP
+The
+.B mtimeout
+program makes an effort to propagate interesting signals to its child
+process group. Currently, it propagates
+.BR SIGTSTP ,
+.BR SIGCONT ,
+.BR SIGINT ,
+.BR SIGHUP ,
+and
+.BR SIGQUIT .
+This list is subject to change: I don't think I'm likely to remove any
+of the current signals from it, but I might add some; or I might add an
+option to control this list.
+.PP
+If you suspend
+.B mtimeout
+and its child process group, the timer continues running anyway. (I'm
+not quite sure whether this is the right behaviour.)
+.PP
+Nested timeouts don't work in a useful way if the outer timeout expires
+earlier than the inner one. Since
+.B SIGTERM
+isn't propagated (currently, at least), the inner
+.B mtimeout
+is killed by the outer one, and loses control of its child process
+group. You could possibly work around this by sending
+.B SIGQUIT
+instead.
+.PP
+Perhaps it would be useful to allow configuration of the `panic'
+timeouts after the initial timeout signal is sent.
+.
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / misc / blobdiff