manpagez: man pages & more
man hatimerun(1)
Home | html | info | man
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
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.