Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
timeout.html (19754B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>timeout</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/time.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/touch.html" accesskey="N">Next
19 >>></a></td>
20 </tr>
21 </table>
22 <hr align="left" width="100%"></div>
23 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
24 <center><font size="2">The Open Group Base Specifications Issue 8<br>
25 IEEE Std 1003.1-2024<br>
26 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
27 <hr size="2" noshade>
28 <a name="top" id="top"></a> <a name="timeout" id="timeout"></a> <a name="tag_20_123" id="tag_20_123"></a><!-- timeout -->
29 <h4 class="mansect"><a name="tag_20_123_01" id="tag_20_123_01"></a>NAME</h4>
30 <blockquote>timeout — execute a utility with a time limit</blockquote>
31 <h4 class="mansect"><a name="tag_20_123_02" id="tag_20_123_02"></a>SYNOPSIS</h4>
32 <blockquote class="synopsis">
33 <p><code><tt>timeout</tt> <b>[</b><tt>-fp</tt><b>] [</b><tt>-k</tt> <i>time</i><b>] [</b><tt>-s</tt> <i>signal_name</i><b>]</b>
34 <i>duration utility</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b></code></p>
35 </blockquote>
36 <h4 class="mansect"><a name="tag_20_123_03" id="tag_20_123_03"></a>DESCRIPTION</h4>
37 <blockquote>
38 <p>The <i>timeout</i> utility shall execute the utility named by the <i>utility</i> operand, with arguments supplied as the
39 <i>argument</i> operands (if any), in a child process. If the value of the <i>duration</i> operand is non-zero and the child
40 process has not terminated after the specified time period, <i>timeout</i> shall send the signal specified by the <b>-s</b> option,
41 or the SIGTERM signal if <b>-s</b> is not given.</p>
42 <p>If the <b>-f</b> option is specified, the signal shall be sent only to the child process. Otherwise, it is implementation
43 defined which one of the following methods is used to signal additional processes:</p>
44 <ul>
45 <li>
46 <p>The <i>timeout</i> utility ensures it is a process group leader before creating the child process which executes the utility, in
47 which case it shall send the signal to its process group.</p>
48 </li>
49 <li>
50 <p>The <i>timeout</i> utility arranges for any descendants of the child process that are orphaned to have their parent process
51 changed to the <i>timeout</i> utility, in which case the signal shall be sent to the child process and all of its descendants.</p>
52 </li>
53 </ul>
54 <p>If the subsequent wait status of the child process shows that it was stopped by a signal, a SIGCONT signal shall also be sent in
55 the same manner as the first signal; otherwise, a SIGCONT signal may be sent in the same manner.</p>
56 <p>If the <b>-k</b> option is specified, and the child process created to execute the utility still has not terminated after the
57 time period specified by the <i>time</i> option-argument has elapsed since the first signal was sent, <i>timeout</i> shall send a
58 SIGKILL signal in the same manner as the first signal. If <i>timeout</i> receives a signal and propagates it to the child process
59 (see ASYNCHRONOUS EVENTS below), this shall be treated as the first signal.</p>
60 </blockquote>
61 <h4 class="mansect"><a name="tag_20_123_04" id="tag_20_123_04"></a>OPTIONS</h4>
62 <blockquote>
63 <p>The <i>timeout</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
64 Guidelines</i></a> .</p>
65 <p>The following options shall be supported:</p>
66 <dl compact>
67 <dd></dd>
68 <dt><b>-f</b></dt>
69 <dd>Only time out the utility itself, not its descendants.</dd>
70 <dt><b>-k </b><i>time</i></dt>
71 <dd>Send a SIGKILL signal if the child process created to execute the utility has not terminated after the time period specified by
72 <i>time</i> has elapsed since the first signal was sent. The value of <i>time</i> shall be interpreted as specified for the
73 <i>duration</i> operand (see OPERANDS below).</dd>
74 <dt><b>-p</b></dt>
75 <dd>Always preserve (mimic) the wait status of the executed utility, even if the time limit was reached.</dd>
76 <dt><b>-s </b><i>signal_name</i></dt>
77 <dd><br>
78 Specify the signal to send when the time limit is reached, using one of the symbolic names defined in the <a href=
79 "../basedefs/signal.h.html"><i><signal.h></i></a> header. Values of <i>signal_name</i> shall be recognized in a
80 case-independent fashion, without the SIG prefix. By default, SIGTERM shall be sent.</dd>
81 </dl>
82 </blockquote>
83 <h4 class="mansect"><a name="tag_20_123_05" id="tag_20_123_05"></a>OPERANDS</h4>
84 <blockquote>
85 <p>The following operands shall be supported:</p>
86 <dl compact>
87 <dd></dd>
88 <dt><i>duration</i></dt>
89 <dd>The maximum amount of time to allow the utility to run, specified as a decimal number with an optional decimal fraction and an
90 optional suffix, which can be:<br>
91 <dl compact>
92 <dd></dd>
93 <dt><b>s</b></dt>
94 <dd>seconds</dd>
95 <dt><b>m</b></dt>
96 <dd>minutes</dd>
97 <dt><b>h</b></dt>
98 <dd>hours</dd>
99 <dt><b>d</b></dt>
100 <dd>days</dd>
101 </dl>
102 <p>If a decimal fraction is present, the application shall ensure that it is separated from the units by a <period>. If no
103 suffix is present, the value shall specify seconds.</p>
104 <p>If the value is zero, <i>timeout</i> shall not enforce a time limit.</p>
105 </dd>
106 <dt><i>utility</i></dt>
107 <dd>The name of a utility that is to be executed. If the <i>utility</i> operand names any of the special built-in utilities in
108 <a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , the results are undefined.</dd>
109 <dt><i>argument</i></dt>
110 <dd>Any string to be supplied as an argument when executing the utility named by the <i>utility</i> operand.</dd>
111 </dl>
112 </blockquote>
113 <h4 class="mansect"><a name="tag_20_123_06" id="tag_20_123_06"></a>STDIN</h4>
114 <blockquote>
115 <p>Not used.</p>
116 </blockquote>
117 <h4 class="mansect"><a name="tag_20_123_07" id="tag_20_123_07"></a>INPUT FILES</h4>
118 <blockquote>
119 <p>None.</p>
120 </blockquote>
121 <h4 class="mansect"><a name="tag_20_123_08" id="tag_20_123_08"></a>ENVIRONMENT VARIABLES</h4>
122 <blockquote>
123 <p>The following environment variables shall affect the execution of <i>timeout</i>:</p>
124 <dl compact>
125 <dd></dd>
126 <dt><i>LANG</i></dt>
127 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
128 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
129 variables used to determine the values of locale categories.)</dd>
130 <dt><i>LC_ALL</i></dt>
131 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
132 <dt><i>LC_CTYPE</i></dt>
133 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
134 opposed to multi-byte characters in arguments and input files).</dd>
135 <dt><i>LC_MESSAGES</i></dt>
136 <dd><br>
137 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
138 <dt><i>NLSPATH</i></dt>
139 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
140 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
141 "0"></dd>
142 <dt><i>PATH</i></dt>
143 <dd>Determine the search path that is used to locate the utility to be executed. See XBD <a href=
144 "../basedefs/V1_chap08.html#tag_08_03"><i>8.3 Other Environment Variables</i></a> .</dd>
145 </dl>
146 </blockquote>
147 <h4 class="mansect"><a name="tag_20_123_09" id="tag_20_123_09"></a>ASYNCHRONOUS EVENTS</h4>
148 <blockquote>
149 <p>The default behavior specified in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a>
150 shall apply, except that:</p>
151 <ul>
152 <li>
153 <p>The <i>timeout</i> utility shall ignore SIGTTIN and SIGTTOU signals.</p>
154 </li>
155 <li>
156 <p>The <i>timeout</i> utility may alter the disposition of SIGALRM if the inherited disposition was for it to be ignored.</p>
157 </li>
158 <li>
159 <p>If the signal specified with the <b>-s</b> option, or any signal whose default action is to terminate the process, is delivered
160 to the <i>timeout</i> utility, then unless the signal is SIGKILL or SIGSTOP, the <i>timeout</i> utility shall immediately send the
161 same signal to the process or processes to which it would send a signal when the time limit is reached. If the delivered signal is
162 SIGALRM, <i>timeout</i> may behave as if the time limit had been reached instead of sending SIGALRM.</p>
163 </li>
164 <li>
165 <p>If the <b>-f</b> option is not specified, then if <i>timeout</i> sends a signal to its process group, it shall briefly change
166 the disposition of that signal to ignored while it sends the signal, so that it does not receive the signal itself.</p>
167 </li>
168 </ul>
169 <p>With the single exception of the signal specified with the <b>-s</b> option, or SIGTERM if <b>-s</b> is not used, all signal
170 dispositions inherited by the utility specified by the <i>utility</i> operand shall be the same as the disposition that
171 <i>timeout</i> inherited.</p>
172 </blockquote>
173 <h4 class="mansect"><a name="tag_20_123_10" id="tag_20_123_10"></a>STDOUT</h4>
174 <blockquote>
175 <p>Not used.</p>
176 </blockquote>
177 <h4 class="mansect"><a name="tag_20_123_11" id="tag_20_123_11"></a>STDERR</h4>
178 <blockquote>
179 <p>The standard error shall be used only for diagnostic messages.</p>
180 </blockquote>
181 <h4 class="mansect"><a name="tag_20_123_12" id="tag_20_123_12"></a>OUTPUT FILES</h4>
182 <blockquote>
183 <p>None.</p>
184 </blockquote>
185 <h4 class="mansect"><a name="tag_20_123_13" id="tag_20_123_13"></a>EXTENDED DESCRIPTION</h4>
186 <blockquote>
187 <p>None.</p>
188 </blockquote>
189 <h4 class="mansect"><a name="tag_20_123_14" id="tag_20_123_14"></a>EXIT STATUS</h4>
190 <blockquote>
191 <p>If the <b>-p</b> option is not specified and the time limit was reached:</p>
192 <ul>
193 <li>
194 <p>If the <b>-k</b> option was not specified or the utility terminated before the time period specified by the <i>time</i>
195 option-argument elapsed since the first signal was sent, the exit status shall be 124.</p>
196 </li>
197 <li>
198 <p>If the <b>-k</b> option was specified and the SIGKILL signal was sent, it is unspecified whether the exit status is 124 or the
199 behavior is as if the <b>-p</b> option was specified.</p>
200 </li>
201 </ul>
202 <p>Otherwise, if the executed utility terminated by exiting, the exit status of <i>timeout</i> shall be that of the utility; if the
203 utility was terminated by a signal, <i>timeout</i> shall terminate itself with the same signal while ensuring that a core image is
204 not created.</p>
205 <p>If an error occurs, the following exit values shall be returned:</p>
206 <dl compact>
207 <dd></dd>
208 <dt>125</dt>
209 <dd>An error other than the two described below occurred.</dd>
210 <dt>126</dt>
211 <dd>The utility specified by <i>utility</i> was found but could not be executed.</dd>
212 <dt>127</dt>
213 <dd>The utility specified by <i>utility</i> could not be found.</dd>
214 </dl>
215 </blockquote>
216 <h4 class="mansect"><a name="tag_20_123_15" id="tag_20_123_15"></a>CONSEQUENCES OF ERRORS</h4>
217 <blockquote>
218 <p>Default.</p>
219 </blockquote>
220 <hr>
221 <div class="box"><em>The following sections are informative.</em></div>
222 <h4 class="mansect"><a name="tag_20_123_16" id="tag_20_123_16"></a>APPLICATION USAGE</h4>
223 <blockquote>
224 <p>Unlike the <a href="../utilities/kill.html"><i>kill</i></a> utility, the <b>-s</b> option of <i>timeout</i> is not required to
225 accept the symbolic name 0 to represent signal value zero.</p>
226 <p>When the value of <i>duration</i> is zero, <i>timeout</i> does not time out the utility, but it does still perform signal
227 propagation (including to descendants of the utility if <b>-f</b> is not specified).</p>
228 <p>Regardless of locale, the <period> character (the decimal-point character of the POSIX locale) is the decimal-point
229 character recognized in the <i>duration</i> operand and the <i>time</i> option-argument.</p>
230 <p>The <a href="../utilities/command.html"><i>command</i></a>, <a href="../utilities/env.html"><i>env</i></a>, <a href=
231 "../utilities/nice.html"><i>nice</i></a>, <a href="../utilities/nohup.html"><i>nohup</i></a>, <a href=
232 "../utilities/time.html"><i>time</i></a>, <i>timeout</i>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have
233 been specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to
234 find a utility" from "invoked utility exited with an error indication". The value 127 was chosen because it is not commonly used
235 for other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be confused with
236 termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found,
237 but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit
238 codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and
239 uses 126 when any attempt to <i>exec</i> the utility fails for any other reason. The <i>timeout</i> utility extends these special
240 exit codes to 125 and 124, with the meanings described in EXIT STATUS. A <i>timeout</i> exit status below 124 can only result from
241 passing through the exit status of the executed utility.</p>
242 </blockquote>
243 <h4 class="mansect"><a name="tag_20_123_17" id="tag_20_123_17"></a>EXAMPLES</h4>
244 <blockquote>
245 <p>None.</p>
246 </blockquote>
247 <h4 class="mansect"><a name="tag_20_123_18" id="tag_20_123_18"></a>RATIONALE</h4>
248 <blockquote>
249 <p>Some <i>timeout</i> implementations make themselves a process group leader (when <b>-f</b> is not used) in order to be able to
250 send signals to descendants of the child process. However, using this method means that any descendants which change their process
251 group do not receive the signal. To ensure all descendants receive the signal, some implementations instead make use of a feature
252 whereby descendants that are orphaned have their parent process changed to the <i>timeout</i> utility—that is, <i>timeout</i>
253 becomes their "reaper"—together with the ability of a reaper to send a signal to all of its descendants.</p>
254 <p>Some historical <i>timeout</i> implementations exited with status 128+<i>signal_number</i> when the child process was terminated
255 by a signal before the time limit was reached (or when <b>-p</b> was used). This is reasonable when <i>timeout</i> is invoked from
256 a shell which sets $? to 128+<i>signal_number</i>, but not all shells do that. In particular, the KornShell sets $? to
257 256+<i>signal_number</i> and so an exit status of 128+<i>signal_number</i> from <i>timeout</i> would be misleading. In order to
258 avoid any possible ambiguity, this standard requires that <i>timeout</i> mimics the wait status of the child process by terminating
259 itself with the same signal. When it does this it needs to ensure that it does not create a core image, otherwise it could
260 overwrite one created by the invoked utility.</p>
261 <p>The <i>timeout</i> utility ignores SIGTTIN and SIGTTOU so that if the utility it executes reads from or writes to the
262 controlling terminal and this generates a SIGTTIN or SIGTTOU for the process group, <i>timeout</i> will not be stopped by the
263 signal and can still time out the utility.</p>
264 <p>Some historical <i>timeout</i> implementations always set the disposition for SIGTTIN and SIGTTOU in the child process to
265 default, even if these signals were inherited as ignored. This could result in processes being stopped unexpectedly. Likewise, they
266 did not ensure that for signals they caught, the disposition inherited by the executed utility was the same as the disposition that
267 was inherited by <i>timeout</i>. This meant that, for example, if <i>timeout</i> was used in a script that was run with <a href=
268 "../utilities/nohup.html"><i>nohup</i></a>, the utility executed by <i>timeout</i> would unexpectedly not be protected from SIGHUP.
269 This standard requires that all signal dispositions inherited by the utility specified by the <i>utility</i> operand are the same
270 as the disposition that <i>timeout</i> inherited, with the single exception of the signal that <i>timeout</i> sends when the time
271 limit is reached, which needs to be inherited as default in order for the timeout to take effect (without resorting to SIGKILL if
272 <b>-k</b> is specified).</p>
273 <p>Some historical <i>timeout</i> implementations only propagated a subset of the signals whose default action is to terminate the
274 process to the child process if one was delivered to the <i>timeout</i> utility. Propagating these signals is beneficial, as
275 otherwise termination of the <i>timeout</i> utility by a signal results in the utility it executed being left running indefinitely
276 (unless it also received the signal, for example a terminal-generated SIGINT). There is no reason to select a subset of these
277 signals to be propagated, therefore this standard requires them all to be propagated (except SIGKILL, which cannot). In the event
278 that a user wants to prevent the utility being timed out, sending <i>timeout</i> a SIGKILL can be used for this purpose.</p>
279 </blockquote>
280 <h4 class="mansect"><a name="tag_20_123_19" id="tag_20_123_19"></a>FUTURE DIRECTIONS</h4>
281 <blockquote>
282 <p>None.</p>
283 </blockquote>
284 <h4 class="mansect"><a name="tag_20_123_20" id="tag_20_123_20"></a>SEE ALSO</h4>
285 <blockquote>
286 <p><a href="../utilities/kill.html#tag_20_64"><i>kill</i></a></p>
287 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
288 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href=
289 "../basedefs/signal.h.html"><i><signal.h></i></a></p>
290 </blockquote>
291 <h4 class="mansect"><a name="tag_20_123_21" id="tag_20_123_21"></a>CHANGE HISTORY</h4>
292 <blockquote>
293 <p>First released in Issue 8.</p>
294 </blockquote>
295 <div class="box"><em>End of informative text.</em></div>
296 <hr>
297 <p> </p>
298 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
299 <hr size="2" noshade>
300 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
301 POSIX™ is a Trademark of The IEEE.<br>
302 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
303 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
304 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
305 ]</font></center>
306 <hr size="2" noshade>
307 <div class="NAVHEADER">
308 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
309 <tr class="nav">
310 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/time.html" accesskey="P"><<<
311 Previous</a></td>
312 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
313 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/touch.html" accesskey="N">Next
314 >>></a></td>
315 </tr>
316 </table>
317 <hr align="left" width="100%"></div>
318 </body>
319 </html>