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