| 1 | .TH "timeout" 1 "5 June 2011" "Mark Wooding" "Toys" |
| 2 | .SH NAME |
| 3 | timeout \- run a program for at most a given amount of time |
| 4 | . |
| 5 | .SH SYNOPSIS |
| 6 | .B timeout |
| 7 | .RB [ \-s |
| 8 | .IR signal ] |
| 9 | .I seconds |
| 10 | .I command |
| 11 | .RI [ arguments ...] |
| 12 | . |
| 13 | .SH DESCRIPTION |
| 14 | The |
| 15 | .B timeout |
| 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 |
| 22 | .B timeout |
| 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 |
| 27 | .B timeout |
| 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 |
| 37 | .B timeout |
| 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 ). |
| 62 | .PP |
| 63 | The |
| 64 | .B timeout |
| 65 | program sets its exit status as follows. |
| 66 | .TP |
| 67 | 0\(em127 |
| 68 | The child process ran to completion within the given time: |
| 69 | .BR timeout 's |
| 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 |
| 74 | .B timeout |
| 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 |
| 80 | .B timeout |
| 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: |
| 86 | .B timeout |
| 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 |
| 95 | .B timeout |
| 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 |
| 101 | .B timeout |
| 102 | failed unexpectedly: an error message was written to standard error. |
| 103 | .TP |
| 104 | 255 |
| 105 | Not used. |
| 106 | . |
| 107 | .SH BUGS |
| 108 | Because |
| 109 | .B timeout |
| 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 |
| 117 | .B timeout |
| 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 |
| 131 | .B timeout |
| 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 |
| 139 | .B timeout |
| 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> |