Release 1.4.2.

[misc] / mtimeout.1

diff --git a/mtimeout.1 b/mtimeout.1
index c696f93..703c235 100644 (file)
--- a/mtimeout.1
+++ b/mtimeout.1
@@ -4,17 +4,36 @@ mtimeout \- run a program for at most a given amount of time
 .
 .SH SYNOPSIS
 .B mtimeout
+.RB [ \-K ]
+.RB [ \-k
+.IR time ]
+.RB [ \-b
+.IR time ]
 .RB [ \-s
 .IR signal ]
-.I seconds
+.br
+       \c
+.I time
 .I command
 .RI [ arguments ...]
 .
 .SH DESCRIPTION
 The
 .B mtimeout
-command runs a specified program for at most a given number of
-.IR seconds .
+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
@@ -29,11 +48,15 @@ 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
+option.  It then waits an additional five seconds (configurable with
+the
+.B \-k
+option).  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
+to the process group and waits a further five seconds (configurable
+with the
+.B \-b
+option).  If the child still hasn't exited in this time, then
 .B mtimeout
 gives up and exits.
 .PP
@@ -50,6 +73,39 @@ successfully.
 .B \-u, \-\-usage
 Prints a brief usage summary to standard output, and exits successfully.
 .TP
+.BI "\-b, \-\-bored-after=" time
+After sending
+.B SIGKILL
+(or, with
+.BR \-K ,
+the original signal)
+wait for
+.I time
+before giving up and declaring the child process undead.  The default
+wait is five seconds.  The
+.I time
+may have a unit suffix.
+.TP
+.B "\-K, \-\-no-kill"
+Don't send a
+.B SIGKILL
+to the process: just wait for a while (see the
+.B \-b
+option) after sending the original signal to see whether it actually
+dies.
+.TP
+.BI "\-k, \-\-kill-after=" time
+After sending a signal, wait for
+.I time
+before sending
+.BR SIGKILL .
+The default wait is five seconds.  The
+.I time
+may have a unit suffix.
+This option has no effect if
+.BR \-K
+is set.
+.TP
 .BI "\-s, \-\-signal=" signal
 Send
 .I signal
@@ -64,10 +120,16 @@ The
 .B mtimeout
 program sets its exit status as follows.
 .TP
-0\(em127
+0\(em127, 255
 The child process ran to completion within the given time:
 .BR mtimeout 's
 exit status is the same as that of the child process.
+(Whatever status the child exits with will be propagated;
+but if it exits with some status other than these then
+there is a risk that it will be conflict
+with a status used by
+.B mtimeout
+and be misinterpreted.)
 .TP
 128
 The child process exited in a way which
@@ -100,9 +162,6 @@ was written to standard error.
 A system call made by
 .B mtimeout
 failed unexpectedly: an error message was written to standard error.
-.TP
-255
-Not used.
 .
 .SH BUGS
 Because