git.sur5r.net Git - bacula/bacula/blob - bacula/src/tools/timelimit.1

   1 .\" Copyright (c) 2001, 2007 - 2010  Peter Pentchev
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Ringlet$
  26 .\"
  27 .Dd September 29, 2010
  28 .Dt TIMELIMIT 1
  29 .Os
  30 .Sh NAME
  31 .Nm timelimit
  32 .Nd effectively limit the absolute execution time of a process
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl pq
  36 .Op Fl S Ar killsig
  37 .Op Fl s Ar warnsig
  38 .Op Fl T Ar killtime
  39 .Op Fl t Ar warntime
  40 .Ar command
  41 .Op Ar arguments ...
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 utility executes a given
  46 .Ar command
  47 with the supplied
  48 .Ar arguments
  49 and terminates the spawned process after a given time with a given signal.
  50 If the process exits before the time limit has elapsed,
  51 .Nm
  52 will silently exit, too.
  53 .Pp
  54 Options:
  55 .Bl -tag -width indent
  56 .It Fl p
  57 If the child process is terminated by a signal,
  58 .Nm
  59 propagates this condition, i.e. sends the same signal to itself.
  60 This allows the program executing
  61 .Nm
  62 to determine whether the child process was terminated by a signal or
  63 actually exited with an exit code larger than 128.
  64 .It Fl q
  65 Quiet operation -
  66 .Nm
  67 does not output diagnostic messages about signals sent to the child process.
  68 .It Fl S Ar killsig
  69 Specify the number of the signal to be sent to the process
  70 .Ar killtime
  71 seconds after
  72 .Ar warntime
  73 has expired.
  74 Defaults to 9 (SIGKILL).
  75 .It Fl s Ar warnsig
  76 Specify the number of the signal to be sent to the process
  77 .Ar warntime
  78 seconds after it has been started.
  79 Defaults to 15 (SIGTERM).
  80 .It Fl T Ar killtime
  81 Specify the maximum execution time of the process before sending
  82 .Ar killsig
  83 after
  84 .Ar warnsig
  85 has been sent.
  86 Defaults to 120 seconds.
  87 .It Fl t Ar warntime
  88 Specify the maximum execution time of the process in seconds before sending
  89 .Ar warnsig .
  90 Defaults to 3600 seconds.
  91 .El
  92 .Pp
  93 On systems that support the
  94 .Xr setitimer 2
  95 system call, the
  96 .Ar warntime
  97 and
  98 .Ar killtime
  99 values may be specified in fractional seconds with microsecond precision.
 100 .Sh ENVIRONMENT
 101 .Bl -tag -width indent
 102 .It Ev KILLSIG
 103 The
 104 .Ar killsig
 105 to use if the
 106 .Fl S
 107 option was not specified.
 108 .It Ev KILLTIME
 109 The
 110 .Ar killtime
 111 to use if the
 112 .Fl T
 113 option was not specified.
 114 .It Ev WARNSIG
 115 The
 116 .Ar warnsig
 117 to use if the
 118 .Fl s
 119 option was not specified.
 120 .It Ev WARNTIME
 121 The
 122 .Ar warntime
 123 to use if the
 124 .Fl t
 125 option was not specified.
 126 .El
 127 .Sh EXIT STATUS
 128 If the child process exits normally, the
 129 .Nm
 130 utility will pass its exit code on up.
 131 If the child process is terminated by a signal and the
 132 .Fl p
 133 flag was not specified, the
 134 .Nm
 135 utility's exit status is 128 plus the signal number, similar to
 136 .Xr sh 1 .
 137 If the
 138 .Fl p
 139 flag was specified, the
 140 .Nm
 141 utility will raise the signal itself so that its own parent process
 142 may in turn reliably distinguish between a signal and a larger than 128
 143 exit code.
 144 .Pp
 145 In rare cases, the
 146 .Nm
 147 utility may encounter a system or user error; then, its exit status is one
 148 of the standard
 149 .Xr sysexits 3
 150 values:
 151 .Bl -tag -width indent
 152 .It Dv EX_USAGE
 153 The command-line parameters and options were incorrectly specified.
 154 .It Dv EX_SOFTWARE
 155 The
 156 .Nm
 157 utility itself received an unexpected signal while waiting for the child
 158 process to terminate.
 159 .It Dv EX_OSERR
 160 The
 161 .Nm
 162 utility was unable to execute the child process, wait for it to terminate,
 163 or examine its exit status.
 164 .El
 165 .Sh EXAMPLES
 166 .Pp
 167 The following examples are shown as given to the shell:
 168 .Pp
 169 .Dl timelimit -p /usr/local/bin/rsync rsync://some.host/dir /opt/mirror
 170 .Pp
 171 Run the rsync program to mirror a WWW or FTP site and kill it if it
 172 runs longer than 1 hour (that is 3600 seconds) with SIGTERM.
 173 If the rsync process does not exit after receiving the SIGTERM,
 174 .Nm
 175 issues a SIGKILL 120 seconds after the SIGTERM.
 176 If the rsync process is terminated by a signal,
 177 .Nm
 178 will itself raise this signal.
 179 .Pp
 180 .Dl tcpserver 0 8888 timelimit -t600 -T300 /opt/services/chat/stats
 181 .Pp
 182 Start a
 183 .Xr tcpserver n
 184 process listening on tcp port 8888; each client connection shall invoke
 185 an instance of an IRC statistics tool under
 186 .Pa /opt/services/chat
 187 and kill it after 600 seconds have elapsed.
 188 If the stats process is still running after the SIGTERM, it will be
 189 killed by a SIGKILL sent 300 seconds later.
 190 .Pp
 191 .Dl env WARNTIME=4.99 WARNSIG=1 KILLTIME=1.000001 timelimit sh stats.sh
 192 .Pp
 193 Start a shell script and kill it with a SIGHUP in a little under 5 seconds.
 194 If the shell gets stuck and does not respond to the SIGHUP, kill it
 195 with the default SIGKILL just a bit over a second afterwards.
 196 .Sh SEE ALSO
 197 .Xr kill 1 ,
 198 .Xr rsync 1 ,
 199 .Xr signal 3 ,
 200 .Xr tcpserver n
 201 .Sh STANDARDS
 202 No standards documentation was harmed in the process of creating
 203 .Nm .
 204 .Sh BUGS
 205 Please report any bugs in
 206 .Nm
 207 to the author.
 208 .Sh AUTHOR
 209 The
 210 .Nm
 211 utility was conceived and written by
 212 .An Peter Pentchev Aq roam@ringlet.net
 213 with contributions and suggestions by
 214 .An Karsten W Rohrbach Aq karsten@rohrbach.de ,
 215 .An Teddy Hogeborn Aq teddy@fukt.bsnet.se ,
 216 and
 217 .An Tomasz Nowak Aq nowak2000@poczta.onet.pl .