File: timelimit.1

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