[PATCH] Clarify documentation of signal numbers

[PATCH] Clarify documentation of signal numbers

[Tom Tromey]

A user was confused by the meaning of signal numbers in the gdb CLI.
For instance, when using "signal 3", exactly which signal is
delivered?  Is it always 3, or is it always SIGQUIT?

This patch attempts to clarify the documentation here.

Let me know what you think.  I'm not sure this is phrased in the
clearest way possible.
---
 gdb/doc/gdb.texinfo | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7b6000abbea..28a29edbd7c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6882,6 +6882,17 @@ fatal so it can carry out the purpose of the interrupt: to kill the program.
 program.  You can tell @value{GDBN} in advance what to do for each kind of
 signal.
 
+When specifying a signal by number, @value{GDBN} translates the number
+to the target platform according to the corresponding signal name.
+For example, @value{GDBN} always treats signal 1 as @code{SIGHUP}.
+So, when specifying @samp{1} as a signal, @value{GDBN} will translate
+this to the target's @code{SIGHUP}, whatever that might be.
+
+Numbers may only be used for signals 1 through 15.  Where POSIX
+specifies a signal's number, @value{GDBN} uses the same value.
+Additionally, @value{GDBN} uses 7 for @code{SIGEMT}, 10 for
+@code{SIGBUS}, and 12 for @code{SIGSYS}.
+
 @cindex handling signals
 Normally, @value{GDBN} is set up to let the non-erroneous signals like
 @code{SIGALRM} be silently passed to your program
-- 
2.47.0

Re: [PATCH] Clarify documentation of signal numbers

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Fri, 20 Dec 2024 13:19:40 -0700
> 
> A user was confused by the meaning of signal numbers in the gdb CLI.
> For instance, when using "signal 3", exactly which signal is
> delivered?  Is it always 3, or is it always SIGQUIT?
> 
> This patch attempts to clarify the documentation here.
> 
> Let me know what you think.  I'm not sure this is phrased in the
> clearest way possible.

It's clear enough, IMO.  But I wonder whether we should simply have a
table of POSIX signal numbers 1-15 and the corresponding names, as GDB
converts them.  Then the examples you show (which describe just some
of those conversions) will be unnecessary, and we only need to say
that signals 1-15 are interpreted as POSIX says and as shown in the
table.  A table is IMO better because if someone uses GDB on a
non-POSIX platform, they don't necessarily have easy access to header
files on a POSIX platform to find out which signal is, say, signal 11.
So the only way for them to know is to type

  (gdb) handle 11 stop

and see what GDB shows in response, which is not always
possible/convenient.

Thanks.

Re: [PATCH] Clarify documentation of signal numbers

[Maciej W. Rozycki]

On Sat, 21 Dec 2024, Eli Zaretskii wrote:

> It's clear enough, IMO.  But I wonder whether we should simply have a
> table of POSIX signal numbers 1-15 and the corresponding names, as GDB
> converts them.  Then the examples you show (which describe just some
> of those conversions) will be unnecessary, and we only need to say
> that signals 1-15 are interpreted as POSIX says and as shown in the
> table.  A table is IMO better because if someone uses GDB on a
> non-POSIX platform, they don't necessarily have easy access to header
> files on a POSIX platform to find out which signal is, say, signal 11.
> So the only way for them to know is to type
> 
>   (gdb) handle 11 stop
> 
> and see what GDB shows in response, which is not always
> possible/convenient.

 FWIW I think it would make sense to show signal number information along 
with output from `info signal'.  I wasn't aware even you could use numbers 
rather than names here.

  Maciej

Re: [PATCH] Clarify documentation of signal numbers

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> It's clear enough, IMO.  But I wonder whether we should simply have a
Eli> table of POSIX signal numbers 1-15 and the corresponding names, as GDB
Eli> converts them.

Yeah, that makes sense.  I think I thought making a nice-looking table
would be harder than it is.

Here's v2, let me know what you think.

Tom

commit a21d3cb9b0588ee324ba3b59b462aefa216c2e32
Author: Tom Tromey <tromey@adacore.com>
Date:   Fri Dec 20 13:16:17 2024 -0700

    Clarify documentation of signal numbers
    
    A user was confused by the meaning of signal numbers in the gdb CLI.
    For instance, when using "signal 3", exactly which signal is
    delivered?  Is it always 3, or is it always SIGQUIT?
    
    This patch attempts to clarify the documentation here.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c77ac7f30c2..5c16361610c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6884,6 +6884,34 @@ fatal so it can carry out the purpose of the interrupt: to kill the program.
 program.  You can tell @value{GDBN} in advance what to do for each kind of
 signal.
 
+When specifying a signal by number, @value{GDBN} translates the number
+to the target platform according to the corresponding signal name.
+For example, @value{GDBN} always treats signal 1 as @code{SIGHUP}.
+So, when specifying @samp{1} as a signal, @value{GDBN} will translate
+this to the target's @code{SIGHUP}, whatever that might be.
+
+Numbers may only be used for signals 1 through 15.  @value{GDBN} uses
+this mapping:
+
+@multitable {Number} {SIGTERM}
+@headitem Number @tab Name
+@item 1 @tab SIGHUP
+@item 2 @tab SIGINT
+@item 3 @tab SIGQUIT
+@item 4 @tab SIGILL
+@item 5 @tab SIGTRAP
+@item 6 @tab SIGABRT
+@item 7 @tab SIGEMT
+@item 8 @tab SIGFPE
+@item 9 @tab SIGKILL
+@item 10 @tab SIGBUS
+@item 11 @tab SIGSEGV
+@item 12 @tab SIGSYS
+@item 13 @tab SIGPIPE
+@item 14 @tab SIGALRM
+@item 15 @tab SIGTERM
+@end multitable
+
 @cindex handling signals
 Normally, @value{GDBN} is set up to let the non-erroneous signals like
 @code{SIGALRM} be silently passed to your program

Re: [PATCH] Clarify documentation of signal numbers

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>,  gdb-patches@sourceware.org
> Date: Mon, 06 Jan 2025 10:51:02 -0700
> 
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> Eli> It's clear enough, IMO.  But I wonder whether we should simply have a
> Eli> table of POSIX signal numbers 1-15 and the corresponding names, as GDB
> Eli> converts them.
> 
> Yeah, that makes sense.  I think I thought making a nice-looking table
> would be harder than it is.
> 
> Here's v2, let me know what you think.

LGTM, thanks.