hatimerun(1) hatools hatimerun(1)
NAME
hatimerun - Run command with a timeout.
SYNOPSIS
hatimerun [-av] [-e exitcode] [-k sig] -t [[hh:]mm:]secs command [args]
hatimerun [-l|-h|-?]
DESCRIPTION
Executes command args with a timeout of [[hh:]mm:]secs seconds. If
command does not terminate before the timeout exceeds hatimerun sends a
signal to command.
Command is started in its own process group; the signal is sent to the
process group.
hatimerun itself will not terminate while command is running--not even
if the timeout occurred. hatimerun terminates when command terminates.
hatimerun can be configured to send a sequence of different singals to
command to allow graceful termiation but allow a hard timeout with the
KILL signal in the end. See EXAMPLES below.
hatimerun itself ignores the following signals to avoid premature ter-
miantion: TERM, HUP, INT, PIPE, QUIT, USR1 and USR2.
-t [[hh:]mm:]secs
Timeout. Specifies the time when the signal is sent, if command
did not terminate before.
Multiple occurrences of -t are supported. Every time a specified
timeout happens a new signal is sent to the child. See EXAMPLES.
-k sig Specifies the signal that will be sent on timeout.
Multiple occurrences of -k are supported to configure different
signals for differnt timeouts. That is, the second -k signal
will be sent on the second timeout, and so on. In case there
are less -k arguments than timeouts (-t), hatimerun sends
SIGKILL at the additional timeouts. See EXAMPLES below.
Symbolic as well as numeric signal specifications are accepted.
The "magic" signal name NONE will not send a signal, useful in
combination with -v.
Default: SIGKILL
-e exitcode
Changes the exitcode returned by hatimerun on timeout. This code
is used as soon as the first timeout has passed, irrespective of
the exit status of command.
Multiple occurrences of -e are supported in connection with mul-
tiple occurrences of -t.
Default: 99
-a Starts hatimerun in the background. hatimerun itself exits
immediately. The exit code of command is lost.
-l Prints list of available symbolic signal names on this platform
and exits.
-v Verbose mode. Will print a message, containing the runtime, if
the first timeout has passed before command terminated. Useful
in cron to have an e-mail sent if a timeout has passed by.
This option can be paired with the -k NONE switch to just print
an error message on timeout, but don't kill command.
-vv More verbose mode--almost debug mode. Will write a status mes-
sage on every timeout.
-h | -?
Prints a help screen and exits.
RETURN VALUE
If the command terminates normally before the first timeout happened,
On success hatimerun returns the return value of the given command
After the first timeout happened hatimerun returns the value specified
by the respective -e option or 99 per default. hatimerun will always
wait for the program to terminate, even if the program terminates nor-
mally after the first signal was sent, hatimerun will return the
respective error code as return value and the exit code of the command
is lost.
EXAMPLES
hatimerun -t 5 sleep 10
Will kill the sleep command after 5 seconds
hatimerun -k TERM -t 5 sleep 10
Will send the TERM signal after 5 seconds
hatimerun -k TERM -t 5 -e 100 -e 101 -t 1 sleep 10
Will send the TERM signal after 5 seconds, and (if the command
didn't finish till then) send the KILL signal one second later
(about 6 seconds after program start). Will return 100 if the pro-
gram was terminated by the TERM signal or 101 if it was terminated
by the KILL signal.
hatimerun -k HUP -t 1 nohup sleep 1000
Will send a HUP signal after one second and then wait (potentially
forever) until the child terminates.
hatimerun -k TERM -t 1:30 sleep 120
Will send the TERM signal after one minute and 30 seconds (90 sec-
onds).
AUTHOR
Copyright (c) 2001,2003,2005-2010 by Markus Winand <mws@fatalmind.com>
SEE ALSO
halockrun(1)
V2.14 2010-03-16 hatimerun(1)
hatools 2.14 - Generated Tue Mar 16 09:16:22 CDT 2010