hatimerun

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 termiantion: 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 multiple 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 message 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 normally 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 program 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 seconds).

 

AUTHOR

Copyright (c) 2001,2003,2005-2010 by Markus Winand <>  

SEE ALSO

halockrun(1)