1hatimerun(1)                        hatools                       hatimerun(1)
2
3
4

NAME

6       hatimerun - Run command with a timeout.
7

SYNOPSIS

9       hatimerun [-av] [-e exitcode] [-k sig] -t [[hh:]mm:]secs command [args]
10       hatimerun [-l|-h|-?]
11

DESCRIPTION

13       Executes  command  args  with  a timeout of [[hh:]mm:]secs seconds.  If
14       command does not terminate before the timeout exceeds hatimerun sends a
15       signal to command.
16
17       Command  is started in its own process group; the signal is sent to the
18       process group.
19
20       hatimerun itself will not terminate while command is running--not  even
21       if the timeout occurred.  hatimerun terminates when command terminates.
22       hatimerun can be configured to send a sequence of different singals  to
23       command  to allow graceful termiation but allow a hard timeout with the
24       KILL signal in the end. See EXAMPLES below.
25
26       hatimerun itself ignores the following signals to avoid premature  ter‐
27       miantion: TERM, HUP, INT, PIPE, QUIT, USR1 and USR2.
28
29       -t [[hh:]mm:]secs
30              Timeout.  Specifies the time when the signal is sent, if command
31              did not terminate before.
32              Multiple occurrences of -t are supported. Every time a specified
33              timeout happens a new signal is sent to the child. See EXAMPLES.
34
35       -k sig Specifies the signal that will be sent on timeout.
36              Multiple  occurrences of -k are supported to configure different
37              signals for differnt timeouts. That is,  the  second  -k  signal
38              will  be  sent  on the second timeout, and so on.  In case there
39              are less  -k  arguments  than  timeouts  (-t),  hatimerun  sends
40              SIGKILL at the additional timeouts. See EXAMPLES below.
41              Symbolic  as well as numeric signal specifications are accepted.
42              The "magic" signal name NONE will not send a signal,  useful  in
43              combination with -v.
44
45              Default: SIGKILL
46
47       -e exitcode
48              Changes the exitcode returned by hatimerun on timeout. This code
49              is used as soon as the first timeout has passed, irrespective of
50              the exit status of command.
51              Multiple occurrences of -e are supported in connection with mul‐
52              tiple occurrences of -t.
53
54              Default: 99
55
56       -a     Starts hatimerun in  the  background.   hatimerun  itself  exits
57              immediately. The exit code of command is lost.
58
59       -l     Prints  list of available symbolic signal names on this platform
60              and exits.
61
62       -v     Verbose mode. Will print a message, containing the  runtime,  if
63              the  first  timeout has passed before command terminated. Useful
64              in cron to have an e-mail sent if a timeout has passed by.
65              This option can be paired with the -k NONE switch to just  print
66              an error message on timeout, but don't kill command.
67
68       -vv    More  verbose  mode--almost debug mode. Will write a status mes‐
69              sage on every timeout.
70
71       -h | -?
72              Prints a help screen and exits.
73

RETURN VALUE

75       If the command terminates normally before the first  timeout  happened,
76       On success hatimerun returns the return value of the given command
77
78       After  the first timeout happened hatimerun returns the value specified
79       by the respective -e option or 99 per default.  hatimerun  will  always
80       wait  for the program to terminate, even if the program terminates nor‐
81       mally after the first  signal  was  sent,  hatimerun  will  return  the
82       respective  error code as return value and the exit code of the command
83       is lost.
84

EXAMPLES

86       hatimerun -t 5 sleep 10
87          Will kill the sleep command after 5 seconds
88
89       hatimerun -k TERM -t 5 sleep 10
90          Will send the TERM signal after 5 seconds
91
92       hatimerun -k TERM -t 5 -e 100 -e 101 -t 1 sleep 10
93          Will send the TERM signal after  5  seconds,  and  (if  the  command
94          didn't  finish  till  then)  send  the  KILL signal one second later
95          (about 6 seconds after program start). Will return 100 if  the  pro‐
96          gram  was  terminated by the TERM signal or 101 if it was terminated
97          by the KILL signal.
98
99       hatimerun -k HUP -t 1 nohup sleep 1000
100          Will send a HUP signal after one second and then  wait  (potentially
101          forever) until the child terminates.
102
103       hatimerun -k TERM -t 1:30 sleep 120
104          Will  send  the TERM signal after one minute and 30 seconds (90 sec‐
105          onds).
106
107

AUTHOR

109       Copyright (c) 2001,2003,2005-2010 by Markus Winand <mws@fatalmind.com>
110

SEE ALSO

112       halockrun(1)
113
114
115
116V2.14                             2010-03-16                      hatimerun(1)
Impressum