A NOTE has been added to this issue. ====================================================================== https://austingroupbugs.net/view.php?id=1586 ====================================================================== Reported By: steffen Assigned To: ====================================================================== Project: 1003.1(2016/18)/Issue7+TC2 Issue ID: 1586 Category: Shell and Utilities Type: Enhancement Request Severity: Editorial Priority: normal Status: New Name: steffen Organization: User Reference: Section: Vol. 3: Shell and Utilities Page Number: Line Number: (Line or range of lines) Interp Status: --- Final Accepted Text: ====================================================================== Date Submitted: 2022-05-14 22:07 UTC Last Modified: 2022-07-29 11:03 UTC ====================================================================== Summary: timeout - new utility: run a command with a time limit ======================================================================
---------------------------------------------------------------------- (0005920) geoffclare (manager) - 2022-07-29 11:03 https://austingroupbugs.net/view.php?id=1586#c5920 ---------------------------------------------------------------------- Suggested changes... On page 3301 insert a new page for timeout: <b>NAME</b><blockquote>timeout - execute a utility with a time limit</blockquote> <b>SYNOPSIS</b> <blockquote><pre>timeout <b>[</b>-fp<b>]</b> <b>[</b>-k<b> <i>time</i>]</b> <b>[</b>-s<b> <i>signal_name</i>]</b> <i>duration</i> <i>utility</i> <b>[</b><i>argument</i>...<b>]</b></pre></blockquote> <b>DESCRIPTION</b><blockquote>The <i>timeout</i> utility shall execute the utility named by the <i>utility</i> operand, with arguments supplied as the <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 process has not terminated after the specified time period, <i>timeout</i> shall send the signal specified by the <b>-s</b> option, or the SIGTERM signal if <b>-s</b> is not given. If the <b>-f</b> option is specified, the signal shall be sent only to the child process. Otherwise, it is implementation defined which one of the following methods is used to signal additional processes: <ul> <li>The <i>timeout</i> utility ensures it is a process group leader before creating the child process which executes the utility, in which case it shall send the signal to its process group.</li> <li>The <i>timeout</i> utility arranges for any descendents of the child process that are orphaned to have their parent process changed to the <i>timeout</i> utility, in which case the signal shall be sent to the child process and all of its descendents.</li> </ul> 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 the same manner as the first signal; otherwise, a SIGCONT signal may be sent in the same manner. If the <b>-k</b> option is specified, and the child process created to execute the utility still has not terminated after the time period specified by the <i>time</i> option-argument has elapsed since the first signal was sent, <i>timeout</i> shall send a SIGKILL signal in the same manner as the first signal. If <i>timeout</i> receives a signal and propagates it to the child process (see ASYNCHRONOUS EVENTS below), this shall be treated as the first signal.</blockquote> <b>OPTIONS</b><blockquote>The <i>timeout</i> utility shall conform to [xref to XBD 12.2]. The following options shall be supported: <b>-f</b><blockquote>Only time out the utility itself, not its descendents.</blockquote><b>-k</b> <i>time</i><blockquote>Send a SIGKILL signal if the child process created to execute the utility has not terminated after the time period specified by <i>time</i> has elapsed since the first signal was sent. The value of <i>time</i> shall be interpreted as specified for the <i>duration</i> operand (see OPERANDS below).</blockquote><b>-p</b><blockquote>Always preserve (mimic) the wait status of the executed utility, even if the time limit was reached.</blockquote><b>-s</b> <i>signal_name</i><blockquote>Specify the signal to send when the time limit is reached, using one of the symbolic names defined in the <b><signal.h></b> header. Values of <i>signal_name</i> shall be recognized in a case-independent fashion, without the SIG prefix. By default, SIGTERM shall be sent.</blockquote></blockquote> <b>OPERANDS</b><blockquote><i>duration</i><blockquote>The maximum amount of time to allow the utility to run, specified as a decimal number with an optional decimal fraction and an optional suffix, which can be: <b>s</b> seconds <b>m</b> minutes <b>h</b> hours <b>d</b> days If a decimal fraction is present, the application shall ensure that it is separated from the units by a <period>. If no suffix is present, the value shall specify seconds. If the value is zero, <i>timeout</i> shall not enforce a time limit.</blockquote><i>utility</i><blockquote>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 [xref to 2.14], the results are undefined.</blockquote><i>argument</i><blockquote>Any string to be supplied as an argument when executing the utility named by the <i>utility</i> operand.</blockquote></blockquote> <b>STDIN</b><blockquote>Not used.</blockquote> <b>INPUT FILES</b><blockquote>None.</blockquote> <b>ENVIRONMENT VARIABLES</b><blockquote>The following environment variables shall affect the execution of <i>timeout</i>: LANG<blockquote>Provide a default value for the internationalization variables that are unset or null. (See [xref to XBD 8.2] for the precedence of internationalization variables used to determine the values of locale categories.)</blockquote>LC_ALL<blockquote>If set to a non-empty string value, override the values of all the other internationalization variables.</blockquote>LC_CTYPE<blockquote>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments).</blockquote>LC_MESSAGES<blockquote>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</blockquote>[XSI]NLSPATH<blockquote>Determine the location of messages objects and message catalogs.[/XSI]</blockquote>PATH<blockquote>Determine the search path that is used to locate the utility to be executed. See [xref to XBD 8.3].</blockquote></blockquote> <b>ASYNCHRONOUS EVENTS</b><blockquote>The default behavior specified in [xref to XCU 1.4] shall apply, except that:<ul> <li>The <i>timeout</i> utility shall ignore SIGTTIN and SIGTTOU signals.</li> <li>The <i>timeout</i> utility may alter the disposition of SIGALRM if the inherited disposition was for it to be ignored.</li> <li>If the signal specified with the <b>-s</b> option, or any signal whose default action is to terminate the process, is delivered to the <i>timeout</i> utility, then unless the signal is SIGKILL or SIGSTOP, the <i>timeout</i> utility shall immediately send the 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 SIGALRM, <i>timeout</i> may behave as if the time limit had been reached instead of sending SIGALRM. </li> <li>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 the disposition of that signal to ignored while it sends the signal, so that it does not receive the signal itself.</li> </ul> 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 dispositions inherited by the utility specified by the <i>utility</i> operand shall be the same as the disposition that <i>timeout</i> inherited.</blockquote> <b>STDOUT</b><blockquote>Not used.</blockquote> <b>STDERR</b><blockquote>The standard error shall be used only for diagnostic messages.</blockquote> <b>OUTPUT FILES</b><blockquote>None.</blockquote> <b>EXTENDED DESCRIPTION</b><blockquote>None.</blockquote> <b>EXIT STATUS</b><blockquote>If the <b>-p</b> option is not specified and the time limit was reached: <ul> <li>If the <b>-k</b> option was not specified or the utility terminated before the time period specified by the <i>time</i> option-argument elapsed since the first signal was sent, the exit status shall be 124.</li> <li>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 behavior is as if the <b>-p</b> option was specified.</li> </ul> Otherwise, if the executed utility terminated by exiting, the exit status of <i>timeout</i> shall be that of the utility; if the utility was terminated by a signal, <i>timeout</i> shall terminate itself with the same signal while ensuring that a core image is not created. If an error occurs, the following exit values shall be returned: 125 An error other than the two described below occurred. 126 The utility specified by <i>utility</i> was found but could not be executed. 127 The utility specified by <i>utility</i> could not be found.</blockquote> <b>CONSEQUENCES OF ERRORS</b><blockquote>Default.</blockquote> <b>APPLICATION USAGE</b><blockquote>Unlike the <i>kill</i> utility, the <b>-s</b> option of <i>timeout</i> is not required to accept the symbolic name 0 to represent signal value zero. When the value of <i>duration</i> is zero, <i>timeout</i> does not time out the utility, but it does still perform signal propagation (including to descendents of the utility if <i>-f</i> is not specified). Regardless of locale, the <period> character (the decimal-point character of the POSIX locale) is the decimal-point character recognized in the <i>duration</i> operand and the <i>time</i> option-argument. The <i>command</i>, <i>env</i>, <i>nice</i>, <i>nohup</i>, <i>time</i>, <i>timeout</i>, and <i>xargs</i> utilities have been specified to use exit code 127 if a utility to be invoked cannot be found so that applications can distinguish ``failure to find a utility'' from ``invoked utility exited with an error indication''. The value 127 was chosen because it is not commonly used for other meanings; most utilities use small values for ``normal error conditions'' and the values above 128 can be confused with termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit 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 uses 126 when any attempt to <i>exec</i> the utility fails for any other reason. The <i>timeout</i> utility extends these special 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 passing through the exit status of the executed utility.</blockquote> <b>EXAMPLES</b><blockquote>None.</blockquote> <b>RATIONALE</b><blockquote>Some <i>timeout</i> implementations make themselves a process group leader (when <b>-f</b> is not used) in order to be able to send signals to descendents of the child process. However, using this method means that any descendents which change their process group do not receive the signal. To ensure all descendents receive the signal, some implementations instead make use of a feature whereby descendents that are orphaned have their parent process changed to the <i>timeout</i> utility--that is, <i>timeout</i> becomes their ``reaper''--together with the ability of a reaper to send a signal to all of its descendents. Some historical <i>timeout</i> implementations exited with status 128+<i>signal_number</i> when the child process was terminated 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 a shell which sets $? to 128+<i>signal_number</i>, but not all shells do that. In particular, the Korn Shell sets $? to 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 avoid any possible ambiguity, this standard requires that <i>timeout</i> mimics the wait status of the child process by terminating itself with the same signal. When it does this it needs to ensure that it does not create a core image, otherwise it could overwrite one created by the invoked utility. The <i>timeout</i> utility ignores SIGTTIN and SIGTTOU so that if the utility it executes read from or writes to the controlling terminal and this generates a SIGTTIN or SIGTTOU for the process group, <i>timeout</i> will not be stopped by the signal and can still time out the utility. Some historical <i>timeout</i> implementations always set the disposition for SIGTTIN and SIGTTOU in the child process to default, even if these signals were inherited as ignored. This could result in processes being stopped unexpectedly. Likewise, they did not ensure that for signals they caught, the disposition inherited by the executed utility was the same as the disposition that was inherited by <i>timeout</i>. This meant that, for example, if <i>timeout</i> was used in a script that was run with <i>nohup</i>, the utility executed by <i>timeout</i> would unexpectedly not be protected from SIGHUP. This standard requires that all signal dispositions inherited by the utility specified by the <i>utility</i> operand are the same as the disposition that <i>timeout</i> inherited, with the single exception of the signal that <i>timeout</i> sends when the time limit is reached, which needs to be inherited as default in order for the timeout to take effect (without resorting to SIGKILL if <i>-k</i> is specified). Some historical <i>timeout</i> implementations only propagated a subset of the signals whose default action is to terminate the process to the child process if one was delivered to the <i>timeout</i> utility. Propagating these signals is beneficial, as otherwise termination of the <i>timeout</i> utility by a signal results in the utility it executed being left running indefinitely (unless it also received the signal, for example a terminal-generated SIGINT). There is no reason to select a subset of these signals to be propagated, therefore this standard requires them all to be propagated (except SIGKILL, which cannot). In the event that a user wants to prevent the utility being timed out, sending <i>timeout</i> a SIGKILL can be used for this purpose.</blockquote> <b>FUTURE DIRECTIONS</b><blockquote>None.</blockquote> <b>SEE ALSO</b><blockquote>kill XBD Chapter 8 (on page NNN), Section 12.2 (on page NNN), <signal.h></blockquote> <b>CHANGE HISTORY</b><blockquote>First released in Issue 8.</blockquote> On page 2598 line 84368 section command, and page 2694 line 87948 section env, and page 3028 line 100764 section nice, and page 3041 line 101203 section nohup, and page 3299 line 111054 section time, and page 3450 line 116526 section xargs, change:<blockquote>The <i>command</i>, <i>env</i>, <i>nice</i>, <i>nohup</i>, <i>time</i>, and <i>xargs</i> utilities</blockquote>to:<blockquote>The <i>command</i>, <i>env</i>, <i>nice</i>, <i>nohup</i>, <i>time</i>, <i>timeout</i>, and <i>xargs</i> utilities</blockquote> Issue History Date Modified Username Field Change ====================================================================== 2022-05-14 22:07 steffen New Issue 2022-05-14 22:07 steffen Name => steffen 2022-05-14 22:07 steffen Section => Vol. 3: Shell and Utilities 2022-05-14 22:07 steffen Line Number => (Line or range of lines) 2022-07-29 11:03 geoffclare Note Added: 0005920 ======================================================================
