mtimeout.c: Restructure timeout handling to use explicit machine.

[misc] / mtimeout.1

.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 time
.I command
.RI [ arguments ...]
.
.SH DESCRIPTION
The
.B mtimeout
command runs a specified program for at most a given amount of
.IR time .
The
.I time
may be fractional (with a decimal point), and may be followed by a unit
suffix:
.RB ` s '
for seconds,
.RB ` m '
for minutes,
.RB ` h '
for hours, and
.RB ` d '
for days.
.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>