Execute a command or pipe only for a given duration.
# $Header: /CVSROOT/timeout/DESCRIPTION,v 1.3 2010-10-20 23:12:30 tino Exp $
#
# $Log: DESCRIPTION,v $
# Revision 1.3  2010-10-20 23:12:30  tino
# fork problem returns 210, child exec fail returns 127 (like bash)
#
# Revision 1.2  2008-11-02 00:13:56  tino
# First version
#

Timeout is a complete rewrite of a program which I had before.  It is
used to restrict the time duration a program runs.  Note that the
"timeout" command which comes with Debian Etch is seriously broken,
therefor I had to create this one here.

Just call it as

timeout [-v] [-signal[@seconds]...] seconds [-|program [args...]]

<UL>

<LI> If -v is present, verbose information is printed.

<LI> If -v is doubled, the current timeout is shown.

<LI> Returns the exit status of the program, 127 if child exec fails, 210 on error from timeout (like usage).

<LI> If execution takes longer than the given number of seconds,
timeout terminates the program and returns 255.

<LI> If signals are given, the signals are sent to the program with
the given delay between.  The default is -1 -15 -9 and a one second
delay.

<LI> If program is missing it works like /bin/cat.  In this case, it
just terminates after the given duration with exit status 211.

<LI> If program is given as '-' the timeout occurs after a silence
phase of the given duration.  Silence is either reading or writing
starves.

</UL>

Future (not yet implemented) plans:

<UL>

<LI> Seconds can hava a fraction.  This is no real floating point
number.

<LI> On HUP or TERM, the timeout cycle for signals is started.

<LI> If program is given as '-number' then the process is attached to
and the signal is sent to the process after this time if the process
still exists (is like a delayed kill).  This is free from race
conditions like "sleep $timeout; kill -9 $pid".

<LI> Allow '-[n]:program' to check stdin, stdout or stderr for silence
(pipe)

<LI> Implement gerneric extended socket processing, this is, program
can be given as connect:host:port or connect:/unixsocket etc.  If
prefixed with - it, again, monitors for silence.  This shall work for
"exec:"- and "pty:"-URLs, too, which open a socket to a process.

</UL>

Examples:

<UL>
<LI> timeout 5<BR>

same as 'sleep 5'

<LI> timeout 5 < /var/log/messages<BR>

same as 'sleep 5 & tail -+0 --pid=$! -f /var/log/messages'

<LI> timeout 5 - < /var/log/messages<BR>

nearly the same as

'cat /var/log/messages | while read -t5 data; do echo "$data"; done'

<LI> timeout 5 ls<BR>

nearly same as

'ls & PID=$!; { sleep 5; kill $PID; } & PID2=$!; wait $PID; kill
$PID2'

(Please note that 'ls & PID=$!; sleep 5; kill $PID' would always delay
5 seconds.)

</UL>