bug#41634: 'timeout' returning 124 and 133

2020-07-29 Thread Jonny Grant



On 28/07/2020 23:41, Bernhard Voelker wrote:
> On 2020-07-28 23:53, Pádraig Brady wrote:
>> +1 thanks
> 
> Thanks, pushed.
> 

Great!





bug#41634: 'timeout' returning 124 and 133

2020-07-28 Thread Bernhard Voelker
On 2020-07-28 23:53, Pádraig Brady wrote:
> +1 thanks

Thanks, pushed.





bug#41634: 'timeout' returning 124 and 133

2020-07-28 Thread Pádraig Brady

On 28/07/2020 22:38, Bernhard Voelker wrote:

On 2020-07-16 00:59, Jonny Grant wrote:

On 15/06/2020 21:57, Bernhard Voelker wrote:

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, ..."


Hi Berny
Just to reply on this item.

Ah ok, on the HTML page that is still 12 pages after the first page. It would 
be nice to see it below the title? Before the TOC.
https://www.gnu.org/software/coreutils/manual/coreutils.html

I didn't search through for the version number, I missed it, as it wasn't at 
the top, or at the end.


The attached adds the version to the title of the HTML manual.
E.g. grep also has it:
   https://www.gnu.org/software/grep/manual/html_node/index.html

@Padraig: okay to push?


+1 thanks





bug#41634: 'timeout' returning 124 and 133

2020-07-28 Thread Bernhard Voelker
On 2020-07-16 00:59, Jonny Grant wrote:
> On 15/06/2020 21:57, Bernhard Voelker wrote:
>> 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, ..."
> 
> Hi Berny
> Just to reply on this item.
> 
> Ah ok, on the HTML page that is still 12 pages after the first page. It would 
> be nice to see it below the title? Before the TOC.
> https://www.gnu.org/software/coreutils/manual/coreutils.html
> 
> I didn't search through for the version number, I missed it, as it wasn't at 
> the top, or at the end.

The attached adds the version to the title of the HTML manual.
E.g. grep also has it:
  https://www.gnu.org/software/grep/manual/html_node/index.html

@Padraig: okay to push?

Have a nice day,
Berny
>From 881c3f20ec435a9c57390853483942fa1101c32b Mon Sep 17 00:00:00 2001
From: Bernhard Voelker 
Date: Tue, 28 Jul 2020 23:28:45 +0200
Subject: [PATCH] doc: show version in title of HTML manual

* doc/coreutils.texi (@include version.texi): Move before ...
(@settitle): ... this.  Add the version after the package name.

Suggested by Jonny Grant  in
https://lists.gnu.org/r/bug-coreutils/2020-07/msg00021.html
---
 doc/coreutils.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index bebccbcb6..52d4cfcbe 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -1,13 +1,13 @@
 \input texinfo
 @c %**start of header
 @setfilename coreutils.info
-@settitle GNU Coreutils
+@include version.texi
+@settitle GNU Coreutils @value{VERSION}
 @documentencoding UTF-8
 @allowcodebreaks false
 
 @c %**end of header
 
-@include version.texi
 @include constants.texi
 
 @c Define new indices.
-- 
2.27.0



bug#41634: 'timeout' returning 124 and 133

2020-07-21 Thread Jonny Grant



On 20/07/2020 21:04, Bernhard Voelker wrote:
> On 2020-07-05 12:53, Jonny Grant wrote:
>> Your patch looks great.
> 
> Thanks, pushed (with the minor tweak mentioned below) at:
>   https://git.sv.gnu.org/cgit/coreutils.git/commit/?id=49bd08aea
> 
>> Is it worth clarifying that --kill-after=0s would send the KILL signal 
>> immediately after TERM?
>> $ timeout --kill-after=0s 2s du -h
> 
> As the signal handler for the regular signal (TERM) does probably not have
> enough time to do anything before being KILLed, this use case would better
> be written as:
> 
>   $ timeout -s KILL 2s du -h
> 
> Not sure this is worth an extra explanation.
> 
>> Is it worth rejecting this? At the moment the -k is just ignored.
>> $ timeout -k 2s 0s du -h
> 
> Hmm, rejecting is a bit harsh.  The question is if this is really
> a problem for the users?  I mean once a user knows there is a -k
> option, I would expect that she has read the documentation about
> how to use it.
> It is mentioned both in the Texinfo manual and in the --help output:
> 
>   A duration of 0 disables the associated timeout.
> 
> I squashed in the following little change:
> 
>   -This option has no effect if @command{timeout}'s duration is 0 and 
> therefore
>   +This option has no effect if @command{timeout}'s duration is 0 which
>disables the associated timeout.
> 
> Have a nice day,
> Berny

Looks great!
Jonny





bug#41634: 'timeout' returning 124 and 133

2020-07-20 Thread Bernhard Voelker
On 2020-07-05 12:53, Jonny Grant wrote:
> Your patch looks great.

Thanks, pushed (with the minor tweak mentioned below) at:
  https://git.sv.gnu.org/cgit/coreutils.git/commit/?id=49bd08aea

> Is it worth clarifying that --kill-after=0s would send the KILL signal 
> immediately after TERM?
> $ timeout --kill-after=0s 2s du -h

As the signal handler for the regular signal (TERM) does probably not have
enough time to do anything before being KILLed, this use case would better
be written as:

  $ timeout -s KILL 2s du -h

Not sure this is worth an extra explanation.

> Is it worth rejecting this? At the moment the -k is just ignored.
> $ timeout -k 2s 0s du -h

Hmm, rejecting is a bit harsh.  The question is if this is really
a problem for the users?  I mean once a user knows there is a -k
option, I would expect that she has read the documentation about
how to use it.
It is mentioned both in the Texinfo manual and in the --help output:

  A duration of 0 disables the associated timeout.

I squashed in the following little change:

  -This option has no effect if @command{timeout}'s duration is 0 and therefore
  +This option has no effect if @command{timeout}'s duration is 0 which
   disables the associated timeout.

Have a nice day,
Berny





bug#41634: 'timeout' returning 124 and 133

2020-07-15 Thread Jonny Grant



On 15/06/2020 21:57, Bernhard Voelker wrote:
> 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, ..."

Hi Berny
Just to reply on this item.

Ah ok, on the HTML page that is still 12 pages after the first page. It would 
be nice to see it below the title? Before the TOC.
https://www.gnu.org/software/coreutils/manual/coreutils.html

I didn't search through for the version number, I missed it, as it wasn't at 
the top, or at the end.

Cheers, Jonny





bug#41634: 'timeout' returning 124 and 133

2020-07-05 Thread Jonny Grant



On 05/07/2020 00:25, Bernhard Voelker wrote:
> On 2020-07-04 00:57, Jonny Grant wrote:
>> May I ask if that exit status 137 could be clarified as 128+9, where 9 is
>> the KILL signal number in this example please. I've pasted a patch below.
> 
> Thanks for the patch - this is always a great basis for discussions.
> 
> Well, this 128+9 arithmetic is explained just a couple of lines above,
> i.e., where all the value for the exit status are described.
> So adding it here again looks like repetition to me.

Fair enough.

>> Another question, for me it wasn't clear that the "-k 3s" was cumulative
>> with the duration 5, so the total being 8. I thought both durations
>> both counted from when the command was invoked.
>>
>> https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html#timeout-invocation
>> ‘-k duration’
>> ‘--kill-after=duration’
>> Ensure the monitored command is killed by also sending a ‘KILL’ signal,
>> after the specified duration. Without this option, if the selected signal
>> proves not to be fatal, timeout does not kill the command.
>>
>> Could this be clarified as "after the existing duration is added to
>> this specified duration, cumulatively from when the command is invoked."?
>> I can make another patch if this would be fine, and my understanding is 
>> correct.
> 
> Good catch, this is only documented in --help output (and therefore in 
> timeout.1):
> 
>   -k, --kill-after=DURATION
>  also send a KILL signal if COMMAND is still running
>this long after the initial signal was sent
> 
> What about the attached?
> 
> Thanks & have a nice day,
> Berny
> 

Hi Berny

Your patch looks great.

Is it worth clarifying that --kill-after=0s would send the KILL signal 
immediately after TERM?
$ timeout --kill-after=0s 2s du -h

Is it worth rejecting this? At the moment the -k is just ignored.
$ timeout -k 2s 0s du -h

Cheers
Jonny





bug#41634: 'timeout' returning 124 and 133

2020-07-04 Thread Bernhard Voelker
On 2020-07-04 00:57, Jonny Grant wrote:
> May I ask if that exit status 137 could be clarified as 128+9, where 9 is
> the KILL signal number in this example please. I've pasted a patch below.

Thanks for the patch - this is always a great basis for discussions.

Well, this 128+9 arithmetic is explained just a couple of lines above,
i.e., where all the value for the exit status are described.
So adding it here again looks like repetition to me.

> Another question, for me it wasn't clear that the "-k 3s" was cumulative
> with the duration 5, so the total being 8. I thought both durations
> both counted from when the command was invoked.
> 
> https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html#timeout-invocation
> ‘-k duration’
> ‘--kill-after=duration’
> Ensure the monitored command is killed by also sending a ‘KILL’ signal,
> after the specified duration. Without this option, if the selected signal
> proves not to be fatal, timeout does not kill the command.
> 
> Could this be clarified as "after the existing duration is added to
> this specified duration, cumulatively from when the command is invoked."?
> I can make another patch if this would be fine, and my understanding is 
> correct.

Good catch, this is only documented in --help output (and therefore in 
timeout.1):

  -k, --kill-after=DURATION
 also send a KILL signal if COMMAND is still running
   this long after the initial signal was sent

What about the attached?

Thanks & have a nice day,
Berny
>From 56e4aa9d0c083b9e49747d51866e80acec1142a2 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker 
Date: Sun, 5 Jul 2020 01:20:10 +0200
Subject: [PATCH] doc: clarify 'timeout -k' behavior

* doc/coreutils.texi (timeout invocation): Document that the the
duration of --kill-after=DURATION begins when sending the initial
signal.  Also mention that -k does not have any effect if timeout's
duration is 0.

Suggested by Jonny Grant .
---
 doc/coreutils.texi | 16 +---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c072b1575..80ca2858c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18108,9 +18108,19 @@ themselves (like GDB for example).
 @opindex -k
 @opindex --kill-after
 Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
-signal, after the specified @var{duration}.  Without this option, if the
-selected signal proves not to be fatal, @command{timeout} does not kill
-the @var{command}.
+signal.
+
+The specified @var{duration} starts from the point in time when
+@command{timeout} sends the initial signal to @var{command}, i.e.,
+not from the beginning when the @var{command} is started.
+
+This option has no effect if @command{timeout}'s duration is 0 and therefore
+disables the associated timeout.
+
+This option may be useful if the selected signal did not kill the @var{command},
+either because the signal was blocked or ignored, or if the @var{command} takes
+too long (e.g. for cleanup work) to terminate itself within a certain amount
+of time.
 
 @item -s @var{signal}
 @itemx --signal=@var{signal}
-- 
2.27.0



bug#41634: 'timeout' returning 124 and 133

2020-07-03 Thread Jonny Grant



On 03/07/2020 23:23, Bernhard Voelker wrote:
> On 2020-06-15 22:57, Bernhard Voelker wrote:
>> The attached is an attempt to add some useful examples.
> 
> There were no comments, so I pushed with a few tweaks:
>   https://git.sv.gnu.org/cgit/coreutils.git/commit/?id=b1c6ef230c
> 
> Marking this as done.
> 
> Have a nice day,
> Berny
> 

Hello Berny

Great you committed this.

May I ask if that exit status 137 could be clarified as 128+9, where 9 is the 
KILL signal number in this example please. I've pasted a patch below.

Another question, for me it wasn't clear that the "-k 3s" was cumulative with 
the duration 5, so the total being 8. I thought both durations both counted 
from when the command was invoked.

https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html#timeout-invocation
‘-k duration’
‘--kill-after=duration’
Ensure the monitored command is killed by also sending a ‘KILL’ signal, after 
the specified duration. Without this option, if the selected signal proves not 
to be fatal, timeout does not kill the command.


Could this be clarified as "after the existing duration is added to this 
specified duration, cumulatively from when the command is invoked."? I can make 
another patch if this would be fine, and my understanding is correct.





>From b029a83e4bb6f0d51a8f9eef90b5d46905f7ffc2 Mon Sep 17 00:00:00 2001
From: Jonny Grant 
Date: Fri, 3 Jul 2020 23:51:15 +0100
Subject: [PATCH] Add an explanation of 137 to timeout example

Signed-off-by: Jonny Grant 
---
 doc/coreutils.texi | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c072b1575..e89ce4d42 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18178,6 +18178,7 @@ timeout -s INT 5s env --ignore-signal=INT sleep 20
 # Likewise, but sending the KILL signal 3 seconds after the initial
 # INT signal.  Hence, 'sleep' is forcefully terminated after about
 # 8 seconds (5+3), and 'timeout' returns with an exit status of 137.
+# The KILL signal number is 9, and 128+9 is 137
 timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20
 @end example
 
-- 
2.25.1





bug#41634: 'timeout' returning 124 and 133

2020-07-03 Thread Bernhard Voelker
On 2020-06-15 22:57, Bernhard Voelker wrote:
> The attached is an attempt to add some useful examples.

There were no comments, so I pushed with a few tweaks:
  https://git.sv.gnu.org/cgit/coreutils.git/commit/?id=b1c6ef230c

Marking this as done.

Have a nice day,
Berny





bug#41634: 'timeout' returning 124 and 133

2020-06-15 Thread 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
>From 33870a01ef65145ccc0cc7f0bf0b76cafec9d95d Mon Sep 17 00:00:00 2001
From: Bernhard Voelker 
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  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



bug#41634: 'timeout' returning 124 and 133

2020-06-07 Thread Jonny Grant




On 07/06/2020 13:39, Bernhard Voelker wrote:

On 2020-06-06 23:49, Jonny Grant wrote:

Great patch.


thanks, Padraig meanwhile further improved it.


How about writing signal 9 by the name, ie $ kill -s KILL
likewise $ kill -s TERM


Where do you mean?

Have a nice day,
Berny



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."

May I ask, do these texinfo changes also go into the man page?

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

I'm looking at the generated html manual:
https://www.gnu.org/software/coreutils/manual/coreutils.html#timeout-invocation

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?

Could an example be given on the man page and manual?

===
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
===


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"


Cheers
Jonny






bug#41634: 'timeout' returning 124 and 133

2020-06-07 Thread Bernhard Voelker
On 2020-06-07 15:34, Pádraig Brady wrote:
> [...] it is better to add the comma there [...]

thanks, pushed with that change:
https://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=189776ff3b

Marking this as done.

Have a nice day,
Berny





bug#41634: 'timeout' returning 124 and 133

2020-06-07 Thread Pádraig Brady

On 07/06/2020 13:38, Bernhard Voelker wrote:

Minor, grammar-related question:


+Upon timeout send the TERM signal to COMMAND, if no other SIGNAL specified.\n\

___^
s/timeout/&,/ ?

I stumbled upon this sentence a couple of times - shouldn't there be a comma?
The word 'timeout' could be a regular noun, a verb, or in this special case
the name of the tool, so I had to read the first half several times.
But maybe it's only me as a non-native English speaker - commas are much
cheaper over here. ;-)


When writing --help we tend to be space limited,
so I tend to write with punctuation mainly as disambiguation.
But indeed it is better to add the comma there, and we have space.

cheers,
Pádraig





bug#41634: 'timeout' returning 124 and 133

2020-06-07 Thread Bernhard Voelker
Hi Padraig,

On 2020-06-07 14:13, Pádraig Brady wrote:
> How about we add the exit code table to the man page also?
> I've adjusted your patch to do that (along with some other tweaks) in the 
> attached.

nice, especially also:

> -124 if @var{command} times out
> +124 if @var{command} times out, and @option{--preserve-status} is not 
> specified

Minor, grammar-related question:

> +Upon timeout send the TERM signal to COMMAND, if no other SIGNAL 
> specified.\n\
___^
s/timeout/&,/ ?

I stumbled upon this sentence a couple of times - shouldn't there be a comma?
The word 'timeout' could be a regular noun, a verb, or in this special case
the name of the tool, so I had to read the first half several times.
But maybe it's only me as a non-native English speaker - commas are much
cheaper over here. ;-)

Thanks & have a nice day,
Berny





bug#41634: 'timeout' returning 124 and 133

2020-06-07 Thread Bernhard Voelker
On 2020-06-06 23:49, Jonny Grant wrote:
> Great patch.

thanks, Padraig meanwhile further improved it.

> How about writing signal 9 by the name, ie $ kill -s KILL
> likewise $ kill -s TERM

Where do you mean?

Have a nice day,
Berny





bug#41634: 'timeout' returning 124 and 133

2020-06-07 Thread Pádraig Brady

On 06/06/2020 00:37, Bernhard Voelker wrote:

On 2020-06-01 10:01, Jonny Grant wrote:

My mistake missing that. But could the 137 be listed explicitly?
ie.
"It may be  necessary  to  use the KILL (9) signal, since this signal cannot be 
caught, in which case the exit status is
137 (128+9) rather than 124."


thanks for the suggestion.

I think this could still be improved:
there is still the open question what happens when the KILL signal
is sent either to timeout(1) or to COMMAND.
The attached patch tries to clarify.


Thanks for improving that Bernhard.

It's generally easier to scan tables of values, than blocks of text.
How about we add the exit code table to the man page also?
I've adjusted your patch to do that (along with some other tweaks) in the 
attached.

cheers,
Pádraig
>From 267e0ce456dda4d468da4a2d002eaf226b35c5d8 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker 
Date: Sun, 7 Jun 2020 12:58:14 +0100
Subject: [PATCH] doc: timeout: improve documentation of the exit status

* doc/coreutils.texi (timeout invocation): Document that the exit
status is 137 when the KILL signal is used, regardless of whether that
signal is sent to COMMAND or timeout.
* src/timeout.c (usage): Likewise. Also split out and expand
on the possible exit status values to a separate table.

Discussed at https://bugs.gnu.org/41634
---
 doc/coreutils.texi |  9 +++--
 src/timeout.c  | 21 +++--
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f0684b1c5..3432fb294 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18139,14 +18139,19 @@ which should be especially considered when specifying sub-second timeouts.
 Exit status:
 
 @display
-124 if @var{command} times out
+124 if @var{command} times out, and @option{--preserve-status} is not specified
 125 if @command{timeout} itself fails
 126 if @var{command} is found but cannot be invoked
 127 if @var{command} cannot be found
-137 if @var{command} is sent the KILL(9) signal (128+9)
+137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9)
 the exit status of @var{command} otherwise
 @end display
 
+In case of the @samp{KILL(9)} signal, @command{timeout} returns with
+exit status 137, regardless of whether that signal is sent to @var{command}
+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.
 
 @node Process control
 @chapter Process control
diff --git a/src/timeout.c b/src/timeout.c
index 14ae88da5..abe00c729 100644
--- a/src/timeout.c
+++ b/src/timeout.c
@@ -269,12 +269,21 @@ DURATION is a floating point number with an optional suffix:\n\
 'd' for days.\nA duration of 0 disables the associated timeout.\n"), stdout);
 
   fputs (_("\n\
-If the command times out, and --preserve-status is not set, then exit with\n\
-status 124.  Otherwise, exit with the status of COMMAND.  If no signal\n\
-is specified, send the TERM signal upon timeout.  The TERM signal kills\n\
-any process that does not block or catch that signal.  It may be necessary\n\
-to use the KILL (9) signal, since this signal cannot be caught, in which\n\
-case the exit status is 128+9 rather than 124.\n"), stdout);
+Upon timeout send the TERM signal to COMMAND, if no other SIGNAL specified.\n\
+The TERM signal kills any process that does not block or catch that signal.\n\
+It may be necessary to use the KILL signal, since this signal can't be caught.\
+\n"), stdout);
+
+  fputs (_("\n\
+EXIT status:\n\
+  124  if COMMAND times out, and --preserve-status is not specified\n\
+  125  if the timeout command itself fails\n\
+  126  if COMMAND is found but cannot be invoked\n\
+  127  if COMMAND cannot be found\n\
+  137  if COMMAND (or timeout itself) is sent the KILL (9) signal (128+9)\n\
+  -the exit status of COMMAND otherwise\n\
+"), stdout);
+
   emit_ancillary_info (PROGRAM_NAME);
 }
   exit (status);
-- 
2.26.2



bug#41634: 'timeout' returning 124 and 133

2020-06-06 Thread Jonny Grant




On 06/06/2020 00:37, Bernhard Voelker wrote:

On 2020-06-01 10:01, Jonny Grant wrote:

My mistake missing that. But could the 137 be listed explicitly?
ie.
"It may be  necessary  to  use the KILL (9) signal, since this signal cannot be 
caught, in which case the exit status is
137 (128+9) rather than 124."


thanks for the suggestion.

I think this could still be improved:
there is still the open question what happens when the KILL signal
is sent either to timeout(1) or to COMMAND.
The attached patch tries to clarify.

Have a nice day,
Berny



Hello Berny

Great patch.

How about writing signal 9 by the name, ie $ kill -s KILL
likewise $ kill -s TERM

Cheers, Jonny





bug#41634: 'timeout' returning 124 and 133

2020-06-05 Thread Bernhard Voelker
On 2020-06-01 10:01, Jonny Grant wrote:
> My mistake missing that. But could the 137 be listed explicitly?
> ie.
> "It may be  necessary  to  use the KILL (9) signal, since this signal cannot 
> be caught, in which case the exit status is 
> 137 (128+9) rather than 124."

thanks for the suggestion.

I think this could still be improved:
there is still the open question what happens when the KILL signal
is sent either to timeout(1) or to COMMAND.
The attached patch tries to clarify.

Have a nice day,
Berny
>From d4ee1f8ace585124e80a3d6e11c6902e37e9e71f Mon Sep 17 00:00:00 2001
From: Bernhard Voelker 
Date: Sat, 6 Jun 2020 01:22:00 +0200
Subject: [PATCH] doc: timeout: further clarify exit status after KILL signal

* doc/coreutils.texi (timeout invocation): Document that the exit
status is 137 when the KILL signal is used, regardless of wether that
signal is sent to COMMAND or timeout.
* src/timeout.c (usage): Likewise.

Discussed at https://bugs.gnu.org/41634
---
 doc/coreutils.texi | 8 +++-
 src/timeout.c  | 6 +++---
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f0684b1c5..07494ab0f 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18143,10 +18143,16 @@ Exit status:
 125 if @command{timeout} itself fails
 126 if @var{command} is found but cannot be invoked
 127 if @var{command} cannot be found
-137 if @var{command} is sent the KILL(9) signal (128+9)
+137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9)
 the exit status of @var{command} otherwise
 @end display
 
+In case of the @samp{KILL(9)} signal, @command{timeout} returns with
+exit status 137, regardless of whether that signal is sent to @var{command}
+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.
+
 
 @node Process control
 @chapter Process control
diff --git a/src/timeout.c b/src/timeout.c
index 14ae88da5..9e7cef8f9 100644
--- a/src/timeout.c
+++ b/src/timeout.c
@@ -272,9 +272,9 @@ DURATION is a floating point number with an optional suffix:\n\
 If the command times out, and --preserve-status is not set, then exit with\n\
 status 124.  Otherwise, exit with the status of COMMAND.  If no signal\n\
 is specified, send the TERM signal upon timeout.  The TERM signal kills\n\
-any process that does not block or catch that signal.  It may be necessary\n\
-to use the KILL (9) signal, since this signal cannot be caught, in which\n\
-case the exit status is 128+9 rather than 124.\n"), stdout);
+any process that does not block or catch that signal.\n\
+If the KILL (9) signal - which cannot be caught - is sent to COMMAND or\n\
+timeout, then the exit status is 137 (128+9) rather than 124.\n"), stdout);
   emit_ancillary_info (PROGRAM_NAME);
 }
   exit (status);
-- 
2.26.2



bug#41634: 'timeout' returning 124 and 133

2020-06-01 Thread Jonny Grant




On 01/06/2020 07:53, Andreas Schwab wrote:

On Mai 31 2020, Jonny Grant wrote:


Could the 124 and 137 be documented on the man page?


What's wrong with the last paragraph in the DESCRIPTION section?

Andreas.



My mistake missing that. But could the 137 be listed explicitly?
ie.
"It may be  necessary  to  use the KILL (9) signal, since this signal cannot be caught, in which case the exit status is 
137 (128+9) rather than 124."


This other man page of timeout has a clearer list of the exit codes
https://ss64.com/bash/timeout.html

Jonny





bug#41634: 'timeout' returning 124 and 133

2020-06-01 Thread Andreas Schwab
On Mai 31 2020, Jonny Grant wrote:

> Could the 124 and 137 be documented on the man page?

What's wrong with the last paragraph in the DESCRIPTION section?

Andreas.

-- 
Andreas Schwab, sch...@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."





bug#41634: 'timeout' returning 124 and 133

2020-05-31 Thread Jonny Grant

Hello

I'm using timeout with another program that doesn't have a timeout mechanism. 
Saw surprisingly timeout often returns 124

I was a bit surprised the return code as a signal was not 143 (128+ 15) for 
SIGTERM. I must be missing something.

This article says 124 for SIGTERM, and as expected 137 for SIGKILL (128+9)
https://www.howtogeek.com/423286/how-to-use-the-timeout-command-on-linux/

The man page says "Start COMMAND, and kill it if still running after 
DURATION.", it sounds like it's doing 'kill -s
SIGTERM' after DURATION. Then if -k argument it is doing 'kill -s SIGKILL'


Could the 124 and 137 be documented on the man page?

Regards, Jonny