[misc] / timeout.1

.TH "timeout" 1 "5 June 2011" "Mark Wooding" "Toys"
.SH NAME
timeout \- run a program for at most a given amount of time
.
.SH SYNOPSIS
.B timeout
.RB [ \-s
.IR signal ]
.I seconds
.I command
.RI [ arguments ...]
.
.SH DESCRIPTION
The
.B timeout
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 timeout
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 timeout
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 timeout
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 ).
.
.SH BUGS
Because
.B timeout
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 timeout
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 timeout
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 timeout
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>
Commit	Line	Data
e825e5a9 MW	1	.TH "timeout" 1 "5 June 2011" "Mark Wooding" "Toys"
	2	.SH NAME
	3	timeout \- run a program for at most a given amount of time
	4	.
	5	.SH SYNOPSIS
	6	.B timeout
	7	.RB [ \-s
	8	.IR signal ]
	9	.I seconds
	10	.I command
	11	.RI [ arguments ...]
	12	.
	13	.SH DESCRIPTION
	14	The
	15	.B timeout
	16	command runs a specified program for at most a given number of
	17	.IR seconds .
	18	.PP
	19	It works by running the given command as a separate process group. It
	20	then waits either for the top-level process (only) to exit, or for the
	21	timeout to expire, whichever happens first. If the process exits, then
	22	.B timeout
	23	exits too, setting its exit status to match. Any other processes which
	24	may have been started are left unmolested.
	25	.PP
	26	On the other hand, if the timeout goes off, then
	27	.B timeout
	28	sends its child process group the specified signal, by default
	29	.BR SIGTERM ,
	30	though you can choose a different one with the
	31	.B \-s
	32	option. It then waits an additional five seconds. If the child still
	33	hasn't exited, it sends
	34	.B SIGKILL
	35	to the process group and waits a further five seconds. If the child
	36	still hasn't exited in this time, then
	37	.B timeout
	38	gives up and exits.
	39	.PP
	40	The following command-line options are recognized.
	41	.TP
	42	.B \-h, \-\-help
	43	Prints a reasonably full help message describing the arguments and
	44	options to standard output, and exits successfully.
	45	.TP
	46	.B \-v, \-\-version
	47	Prints the program's version number to standard output, and exits
	48	successfully.
	49	.TP
	50	.B \-u, \-\-usage
	51	Prints a brief usage summary to standard output, and exits successfully.
	52	.TP
	53	.BI "\-s, \-\-signal=" signal
	54	Send
	55	.I signal
	56	to the child process if it takes too long. The default is to send
	57	.BR SIGTERM .
	58	A signal may be given numerically (e.g., 9 for
	59	.BR SIGKILL )
	60	or by name (e.g.,
	61	.BR KILL ).
	62	.
	63	.SH BUGS
	64	Because
65	.B timeout
66	works by running its child process in a separate process group, it
67	interacts oddly with interactive shells. If the child process group
68	attempts to do terminal I/O (particularly reading from a terminal) then
69	it may be sent signals to suspend it. This may or may not make matters
70	worse.
71	.PP
72	The
73	.B timeout
74	program makes an effort to propagate interesting signals to its child
75	process group. Currently, it propagates
76	.BR SIGTSTP ,
77	.BR SIGCONT ,
78	.BR SIGINT ,
79	.BR SIGHUP ,
80	and
81	.BR SIGQUIT .
82	This list is subject to change: I don't think I'm likely to remove any
83	of the current signals from it, but I might add some; or I might add an
84	option to control this list.
85	.PP
86	If you suspend
87	.B timeout
88	and its child process group, the timer continues running anyway. (I'm
89	not quite sure whether this is the right behaviour.)
90	.PP
91	Nested timeouts don't work in a useful way if the outer timeout expires
92	earlier than the inner one. Since
93	.B SIGTERM
94	isn't propagated (currently, at least), the inner
95	.B timeout
96	is killed by the outer one, and loses control of its child process
97	group. You could possibly work around this by sending
98	.B SIGQUIT
99	instead.
100	.PP
101	Perhaps it would be useful to allow configuration of the `panic'
102	timeouts after the initial timeout signal is sent.
103	.
104	.SH AUTHOR
105	Mark Wooding, <mdw@distorted.org.uk>