bug#41634: 'timeout' returning 124 and 133

[Bernhard Voelker]

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

0001-doc-add-timeout-examples.patch
Description: Text Data