Hi Jonny, On 2020-06-07 18:04, Jonny Grant wrote: > Hi Berny > > Sorry I was meaning to give an example of a shell command to send KILL, but > maybe it's not necessary. > > BTW, I saw the patch was applied. Great it's improved > > > I saw this new line is clearer: > "Upon timeout, send the TERM signal to COMMAND, if no other SIGNAL specified." > > However, I thought even clearer is this variation :- > "Upon timeout, if no SIGNAL specified by --signal, send the TERM signal to > COMMAND."
IMO this is not really correct, as it states that a signal - TERM - is (only?) sent in the case when --signal was not used, i.e., what happens in "else"? It's hard to write short and precise man documentation. > May I ask, do these texinfo changes also go into the man page? No, at GNU coreutils (and lots of other GNU projects in general), we intend to have small man pages, and leave the more detailed information in the Texinfo manual: https://www.gnu.org/prep/standards/html_node/Man-Pages.html Actually, the coreutils man pages are generated by running the tools with --help, with some tiny information augmented where useful. > This is the man page 8.32, and it doesn't match the html manual > https://www.man7.org/linux/man-pages/man1/timeout.1.html The man page project collects the latest version after a release. > I'm looking at the generated html manual: > https://www.gnu.org/software/coreutils/manual/coreutils.html#timeout-invocation This belongs to the GNU coreutils project and will be updated with the next release. > I don't know if these html pages can be updated to show the coreutil version > on them at all at the top oand bottom? Hmm, in the HTML format, this is the first sentence after the table of contents: "This manual documents version 8.32 of the GNU core utilities, ..." In the info reader (`info coreutils`), this is even the first sentence. It's also on the title page of the generated PDF documentation. > Could an example be given on the man page and manual? As said, we wouldn't add such examples to the man page, I'm afraid ... > ======= > EXAMPLE > > The command below gives an example to demonstrate the use of this, sending > HUP signal after 5 seconds, and sending the > KILL signal after 10 seconds if 'ls' has not finished. > $ timeout -k 10s -s HUP 5s ls > ======= ... but for sure in the Texinfo manual. The attached is an attempt to add some useful examples. > My last question > > There is -k, it would be clearer if it was possible to specify -t or > --timeout, > "$ timeout -k 11s 6s ls" This always looks ambiguous to me, but the 11s is > the KILL, and the 6s is the regular TERM > signal. > > Would you consider supporting a -t ? > So then we could write > "$ timeout -t 6s -k 11s ls" > > or even > "$ timeout --timeout=6s --kill-after=11s ls" While that would be possible, I'm not so excited about it. The timeout value is a mandatory value similar to the perms for chmod(1), and I've not seen any requests to support "chmod --mode=MODE FILE". Have a nice day, Berny
>From 33870a01ef65145ccc0cc7f0bf0b76cafec9d95d Mon Sep 17 00:00:00 2001 From: Bernhard Voelker <m...@bernhard-voelker.de> Date: Mon, 15 Jun 2020 22:47:15 +0200 Subject: [PATCH] doc: add timeout examples * doc/coreutils.texi (timeout invocation): Add examples. Suggested by Jonny Grant <j...@jguk.org> in https://lists.gnu.org/r/bug-coreutils/2020-06/msg00018.html --- doc/coreutils.texi | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 3432fb294..4f6c6129b 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -18153,6 +18153,28 @@ or to @command{timeout} itself, i.e., these cases cannot be distinguished. In the latter case, the @var{command} process may still be alive after @command{timeout} has forcefully been terminated. +Examples: + +@example +# Send the default TERM signal after 20s to a shorter-living 'sleep' command. +# As that terminates with exit status 0 after 1s, 'timeout' returns the same. +timeout 20 sleep 1 + +# Send a INT signal after 5s to the 'sleep' command. Returns after 5 seconds +# with exit status 124 to indicate the sending of the signal. +timeout -s INT 5 sleep 20 + +# Likewise, but ignoring the signal via 'env --ignore-signal'. +# Thus, 'sleep' terminates regularly after the full 20 seconds, +# still 'timeout' returns with exit status 124. +timeout -s INT 5s env --ignore-signal=INT sleep 20 + +# Likewise, but sending another KILL signal 3 seconds after the initial INT. +# Here, 'sleep' is forcefully terminated after about 8 seconds (5+3), +# and 'timeout' returns with an exit status of 137. +timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20 +@end example + @node Process control @chapter Process control -- 2.27.0
