Commit | Line | Data |
---|---|---|
58b43082 | 1 | .TH "mtimeout" 1 "5 June 2011" "Mark Wooding" "Toys" |
e825e5a9 | 2 | .SH NAME |
58b43082 | 3 | mtimeout \- run a program for at most a given amount of time |
e825e5a9 MW |
4 | . |
5 | .SH SYNOPSIS | |
58b43082 | 6 | .B mtimeout |
0db9a123 MW |
7 | .RB [ \-K ] |
8 | .RB [ \-k | |
9 | .IR time ] | |
10 | .RB [ \-b | |
11 | .IR time ] | |
e825e5a9 MW |
12 | .RB [ \-s |
13 | .IR signal ] | |
0db9a123 MW |
14 | .br |
15 | \c | |
753f86de | 16 | .I time |
e825e5a9 MW |
17 | .I command |
18 | .RI [ arguments ...] | |
19 | . | |
20 | .SH DESCRIPTION | |
21 | The | |
58b43082 | 22 | .B mtimeout |
753f86de MW |
23 | command runs a specified program for at most a given amount of |
24 | .IR time . | |
25 | The | |
26 | .I time | |
27 | may be fractional (with a decimal point), and may be followed by a unit | |
28 | suffix: | |
29 | .RB ` s ' | |
30 | for seconds, | |
31 | .RB ` m ' | |
32 | for minutes, | |
33 | .RB ` h ' | |
34 | for hours, and | |
35 | .RB ` d ' | |
36 | for days. | |
e825e5a9 MW |
37 | .PP |
38 | It works by running the given command as a separate process group. It | |
39 | then waits either for the top-level process (only) to exit, or for the | |
40 | timeout to expire, whichever happens first. If the process exits, then | |
58b43082 | 41 | .B mtimeout |
e825e5a9 MW |
42 | exits too, setting its exit status to match. Any other processes which |
43 | may have been started are left unmolested. | |
44 | .PP | |
45 | On the other hand, if the timeout goes off, then | |
58b43082 | 46 | .B mtimeout |
e825e5a9 MW |
47 | sends its child process group the specified signal, by default |
48 | .BR SIGTERM , | |
49 | though you can choose a different one with the | |
50 | .B \-s | |
0db9a123 MW |
51 | option. It then waits an additional five seconds (configurable with |
52 | the | |
53 | .B \-k | |
54 | option). If the child still hasn't exited, it sends | |
e825e5a9 | 55 | .B SIGKILL |
0db9a123 MW |
56 | to the process group and waits a further five seconds (configurable |
57 | with the | |
58 | .B \-b | |
59 | option). If the child still hasn't exited in this time, then | |
58b43082 | 60 | .B mtimeout |
e825e5a9 MW |
61 | gives up and exits. |
62 | .PP | |
63 | The following command-line options are recognized. | |
64 | .TP | |
65 | .B \-h, \-\-help | |
66 | Prints a reasonably full help message describing the arguments and | |
67 | options to standard output, and exits successfully. | |
68 | .TP | |
69 | .B \-v, \-\-version | |
70 | Prints the program's version number to standard output, and exits | |
71 | successfully. | |
72 | .TP | |
73 | .B \-u, \-\-usage | |
74 | Prints a brief usage summary to standard output, and exits successfully. | |
75 | .TP | |
0db9a123 MW |
76 | .BI "\-b, \-\-bored-after=" time |
77 | After sending | |
78 | .B SIGKILL | |
79 | (or, with | |
80 | .BR \-K , | |
81 | the original signal) | |
82 | wait for | |
83 | .I time | |
84 | before giving up and declaring the child process undead. The default | |
85 | wait is five seconds. The | |
86 | .I time | |
87 | may have a unit suffix. | |
88 | .TP | |
89 | .B "\-K, \-\-no-kill" | |
90 | Don't send a | |
91 | .B SIGKILL | |
92 | to the process: just wait for a while (see the | |
93 | .B \-b | |
94 | option) after sending the original signal to see whether it actually | |
95 | dies. | |
96 | .TP | |
8b3d57aa | 97 | .BI "\-k, \-\-kill-after=" time |
0db9a123 MW |
98 | After sending a signal, wait for |
99 | .I time | |
100 | before sending | |
101 | .BR SIGKILL . | |
102 | The default wait is five seconds. The | |
103 | .I time | |
104 | may have a unit suffix. | |
105 | This option has no effect if | |
106 | .BR \-K | |
107 | is set. | |
108 | .TP | |
e825e5a9 MW |
109 | .BI "\-s, \-\-signal=" signal |
110 | Send | |
111 | .I signal | |
112 | to the child process if it takes too long. The default is to send | |
113 | .BR SIGTERM . | |
114 | A signal may be given numerically (e.g., 9 for | |
115 | .BR SIGKILL ) | |
116 | or by name (e.g., | |
117 | .BR KILL ). | |
25ae65a8 MW |
118 | .PP |
119 | The | |
58b43082 | 120 | .B mtimeout |
25ae65a8 MW |
121 | program sets its exit status as follows. |
122 | .TP | |
f54e279c | 123 | 0\(em127, 255 |
25ae65a8 | 124 | The child process ran to completion within the given time: |
58b43082 | 125 | .BR mtimeout 's |
25ae65a8 | 126 | exit status is the same as that of the child process. |
f54e279c MW |
127 | (Whatever status the child exits with will be propagated; |
128 | but if it exits with some status other than these then | |
129 | there is a risk that it will be conflict | |
130 | with a status used by | |
131 | .B mtimeout | |
132 | and be misinterpreted.) | |
25ae65a8 | 133 | .TP |
f658787d MW |
134 | 128 |
135 | The child process exited in a way which | |
136 | .B mtimeout | |
137 | could not interpret. | |
138 | .TP | |
25ae65a8 MW |
139 | 129\(em250 |
140 | The child process was killed by a signal: the exit status is 128 higher | |
141 | than the signal number. If | |
58b43082 | 142 | .B mtimeout |
25ae65a8 MW |
143 | had to kill the child because it took too long, then its exit status |
144 | will be like this. | |
145 | .TP | |
146 | 251 | |
147 | The child took too long and couldn't be killed: | |
58b43082 | 148 | .B mtimeout |
25ae65a8 MW |
149 | gave up waiting. |
150 | .TP | |
151 | 252 | |
152 | The target program couldn't be started: an error message was written to | |
153 | standard error. | |
154 | .TP | |
155 | 253 | |
156 | The | |
58b43082 | 157 | .B mtimeout |
25ae65a8 MW |
158 | program couldn't parse the arguments provided to it: an error message |
159 | was written to standard error. | |
160 | .TP | |
161 | 254 | |
162 | A system call made by | |
58b43082 | 163 | .B mtimeout |
25ae65a8 | 164 | failed unexpectedly: an error message was written to standard error. |
e825e5a9 MW |
165 | . |
166 | .SH BUGS | |
167 | Because | |
58b43082 | 168 | .B mtimeout |
e825e5a9 MW |
169 | works by running its child process in a separate process group, it |
170 | interacts oddly with interactive shells. If the child process group | |
171 | attempts to do terminal I/O (particularly reading from a terminal) then | |
172 | it may be sent signals to suspend it. This may or may not make matters | |
173 | worse. | |
174 | .PP | |
175 | The | |
58b43082 | 176 | .B mtimeout |
e825e5a9 MW |
177 | program makes an effort to propagate interesting signals to its child |
178 | process group. Currently, it propagates | |
179 | .BR SIGTSTP , | |
180 | .BR SIGCONT , | |
181 | .BR SIGINT , | |
182 | .BR SIGHUP , | |
183 | and | |
184 | .BR SIGQUIT . | |
185 | This list is subject to change: I don't think I'm likely to remove any | |
186 | of the current signals from it, but I might add some; or I might add an | |
187 | option to control this list. | |
188 | .PP | |
189 | If you suspend | |
58b43082 | 190 | .B mtimeout |
e825e5a9 MW |
191 | and its child process group, the timer continues running anyway. (I'm |
192 | not quite sure whether this is the right behaviour.) | |
193 | .PP | |
194 | Nested timeouts don't work in a useful way if the outer timeout expires | |
195 | earlier than the inner one. Since | |
196 | .B SIGTERM | |
197 | isn't propagated (currently, at least), the inner | |
58b43082 | 198 | .B mtimeout |
e825e5a9 MW |
199 | is killed by the outer one, and loses control of its child process |
200 | group. You could possibly work around this by sending | |
201 | .B SIGQUIT | |
202 | instead. | |
203 | .PP | |
204 | Perhaps it would be useful to allow configuration of the `panic' | |
205 | timeouts after the initial timeout signal is sent. | |
206 | . | |
207 | .SH AUTHOR | |
208 | Mark Wooding, <mdw@distorted.org.uk> |