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