[PATCH] gdb: improve usage strings

[PATCH] gdb: improve usage strings

[Mike Frysinger]

This adds Usage strings to a bunch of commands, tweaks the grammar in a
few, and improves the help text for the handle command.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>

2012-08-11  Mike Frysinger  <vapier@gentoo.org>

	* infcmd.c (_initialize_infcmd): Update help text for the signal,
	stepi, nexti, finish, next, step, jump, and continue commands.
	* infrun.c (_initialize_infrun): Update help text for the handle
	command.
---
 gdb/infcmd.c |   20 ++++++++++++++------
 gdb/infrun.c |    6 ++++++
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index d56503c..1c00ea1 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3017,32 +3017,37 @@ The target will wait for another debugger to connect.  Not available for\n\
 all targets."));
 
   c = add_com ("signal", class_run, signal_command, _("\
-Continue program giving it signal specified by the argument.\n\
-An argument of \"0\" means continue program without giving it a signal."));
+Continue program by sending it the specified signal.\n\
+Usage: signal SIGNAL\n\
+An argument of \"0\" means continue the program without sending it a signal."));
   set_cmd_completer (c, signal_completer);
 
   add_com ("stepi", class_run, stepi_command, _("\
 Step one instruction exactly.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: stepi [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("si", "stepi", class_alias, 0);
 
   add_com ("nexti", class_run, nexti_command, _("\
 Step one instruction, but proceed through subroutine calls.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: nexti [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("ni", "nexti", class_alias, 0);
 
   add_com ("finish", class_run, finish_command, _("\
 Execute until selected stack frame returns.\n\
+Usage: finish\n\
 Upon return, the value returned is printed and put in the value history."));
   add_com_alias ("fin", "finish", class_run, 1);
 
   add_com ("next", class_run, next_command, _("\
 Step program, proceeding through subroutine calls.\n\
+Usage: next [N]\n\
 Like the \"step\" command as long as subroutine calls do not happen;\n\
 when they do, the call is treated as one instruction.\n\
-Argument N means do this N times (or till program stops for another \
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("n", "next", class_run, 1);
   if (xdb_commands)
@@ -3050,7 +3055,8 @@ reason)."));
 
   add_com ("step", class_run, step_command, _("\
 Step program until it reaches a different source line.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: step [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("s", "step", class_run, 1);
 
@@ -3069,6 +3075,7 @@ Execution will also stop upon exit from the current stack frame."));
 
   c = add_com ("jump", class_run, jump_command, _("\
 Continue program being debugged at specified line or address.\n\
+Usage: jump <location>\n\
 Give as argument either LINENUM or *ADDR, where ADDR is an expression\n\
 for an address to start at."));
   set_cmd_completer (c, location_completer);
@@ -3090,6 +3097,7 @@ This command is a combination of tbreak and jump."));
 
   add_com ("continue", class_run, continue_command, _("\
 Continue program being debugged, after signal or breakpoint.\n\
+Usage: continue [N]\n\
 If proceeding from breakpoint, a number N may be used as an argument,\n\
 which means to set the ignore count of that breakpoint to N - 1 (so that\n\
 the breakpoint won't break until the Nth time it is reached).\n\
diff --git a/gdb/infrun.c b/gdb/infrun.c
index 4f59a92..6663086 100644
--- a/gdb/infrun.c
+++ b/gdb/infrun.c
@@ -7099,12 +7099,17 @@ Specify a signal as argument to print info on that signal only."));
 
   c = add_com ("handle", class_run, handle_command, _("\
 Specify how to handle a signal.\n\
+Usage: handle SIGNAL [ACTIONS]\n\
 Args are signals and actions to apply to those signals.\n\
+If no actions are specified, the current settings for the specified signal\n\
+will be displayed instead.\n\
+\n\
 Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals\n\
 from 1-15 are allowed for compatibility with old versions of GDB.\n\
 Numeric ranges may be specified with the form LOW-HIGH (e.g. 1-5).\n\
 The special arg \"all\" is recognized to mean all signals except those\n\
 used by the debugger, typically SIGTRAP and SIGINT.\n\
+\n\
 Recognized actions include \"stop\", \"nostop\", \"print\", \"noprint\",\n\
 \"pass\", \"nopass\", \"ignore\", or \"noignore\".\n\
 Stop means reenter debugger if this signal happens (implies print).\n\
@@ -7113,6 +7118,7 @@ Pass means let program see this signal; otherwise program doesn't know.\n\
 Ignore is a synonym for nopass and noignore is a synonym for pass.\n\
 Pass and Stop may be combined."));
   set_cmd_completer (c, handle_completer);
+
   if (xdb_commands)
     {
       add_com ("lz", class_info, signals_info, _("\
-- 
1.7.9.7

Re: [PATCH] gdb: improve usage strings

[Eli Zaretskii]

> From: Mike Frysinger <vapier@gentoo.org>
> Date: Sat, 11 Aug 2012 12:54:40 -0400
> 
> This adds Usage strings to a bunch of commands, tweaks the grammar in a
> few, and improves the help text for the handle command.

Thanks.

>    c = add_com ("signal", class_run, signal_command, _("\
> -Continue program giving it signal specified by the argument.\n\
> -An argument of \"0\" means continue program without giving it a signal."));
> +Continue program by sending it the specified signal.\n\

This "by sending it" is AFAIU inaccurate: we don't continue program
_by_ sending it the signal, we continue the program _and_ send it the
signal.  I actually don't see anything wrong with the original
wording.

>    add_com ("finish", class_run, finish_command, _("\
>  Execute until selected stack frame returns.\n\
> +Usage: finish\n\
>  Upon return, the value returned is printed and put in the value history."));

Does this "usage" really add any information?

>    add_com ("next", class_run, next_command, _("\
>  Step program, proceeding through subroutine calls.\n\
> +Usage: next [N]\n\
>  Like the \"step\" command as long as subroutine calls do not happen;\n\
>  when they do, the call is treated as one instruction.\n\
> -Argument N means do this N times (or till program stops for another \
> +Argument N means step N times (or till program stops for another \

Isn't it better to say "N source lines"?

Btw, I find this entire doc string completely obfuscated.  How about
this instead:

  Step program until it reaches a different source line.
  Usage: next [N]
  Unlike "step", if the current source line calls a subroutine,
  this command does not enter the subroutine, but instead steps over
  the call, in effect treating it as a single source line.

Re: [PATCH] gdb: improve usage strings

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 3802 bytes --]

On Saturday 11 August 2012 13:16:18 Eli Zaretskii wrote:
> > From: Mike Frysinger <vapier@gentoo.org>
> > Date: Sat, 11 Aug 2012 12:54:40 -0400
> >    c = add_com ("signal", class_run, signal_command, _("\
> > 
> > -Continue program giving it signal specified by the argument.\n\
> > -An argument of \"0\" means continue program without giving it a
> > signal."));
> > +Continue program by sending it the specified signal.\n\
> 
> This "by sending it" is AFAIU inaccurate: we don't continue program
> _by_ sending it the signal, we continue the program _and_ send it the
> signal.  I actually don't see anything wrong with the original
> wording.

ok, but your response shows what i was trying to fix:
	- adding "the" before "program"
	- changing "giving" to "sending"
the "by" change was incidental

so i'll change it to:
	Continue program and send it the specified signal.

> >    add_com ("finish", class_run, finish_command, _("\
> >  Execute until selected stack frame returns.\n\
> > +Usage: finish\n\
> >  Upon return, the value returned is printed and put in the value
> >  history."));
> 
> Does this "usage" really add any information?

not really, but i added it for two reasons:
 - consistency: the current *lack* of help text consistency is extremely 
confusing especially
 - many commands take arguments even though the help text implies otherwise 
leaving the user to wonder "does this actually take an option?".  so even a 
usage string showing it takes no arguments is useful.

although it's funny you highlight this command because, when i was updating 
this text, i checked the command to see if it actually secretly took 
arguments.  this is what i found:

static void
finish_command (char *arg, int from_tty) 
{
  ...

  /* Find out whether we must run in the background.  */
  if (arg != NULL)
    async_exec = strip_bg_char (&arg);

  /* If we must run in the background, but the target can't do it,
     error out.  */
  if (async_exec && !target_can_async_p ())
    error (_("Asynchronous execution not supported on this target."));

  /* If we are not asked to run in the bg, then prepare to run in the
     foreground, synchronously.  */
  if (!async_exec && target_can_async_p ())
    {
      /* Simulate synchronous execution.  */
      async_disable_stdin ();
    }

  if (arg)
    error (_("The \"finish\" command does not take any arguments."));
 ...

so it seems like finish *does* secretly accept options, but in this case it's 
trying to be secret about it rather than someone just didn't fully document 
it.  or i read the "arg" parsing logic above incorrectly.

> >    add_com ("next", class_run, next_command, _("\
> >  Step program, proceeding through subroutine calls.\n\
> > +Usage: next [N]\n\
> >  Like the \"step\" command as long as subroutine calls do not happen;\n\
> >  when they do, the call is treated as one instruction.\n\
> > -Argument N means do this N times (or till program stops for another \
> > +Argument N means step N times (or till program stops for another \
> 
> Isn't it better to say "N source lines"?

hmm, probably.  it can be a little confusing when the source debug information 
isn't available for functions, so the "next" ends up skipping too much.  but 
maybe that topic is too large to cover here, so wrapping it up into "source 
lines" should work.

> Btw, I find this entire doc string completely obfuscated.  How about
> this instead:
> 
>   Step program until it reaches a different source line.
>   Usage: next [N]
>   Unlike "step", if the current source line calls a subroutine,
>   this command does not enter the subroutine, but instead steps over
>   the call, in effect treating it as a single source line.

SGTM
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH] gdb: improve usage strings

[Eli Zaretskii]

> From: Mike Frysinger <vapier@gentoo.org>
> Date: Sat, 11 Aug 2012 13:36:40 -0400
> Cc: gdb-patches@sourceware.org
> 
> static void
> finish_command (char *arg, int from_tty) 
> {
>   ...
> 
>   /* Find out whether we must run in the background.  */
>   if (arg != NULL)
>     async_exec = strip_bg_char (&arg);
> 
>   /* If we must run in the background, but the target can't do it,
>      error out.  */
>   if (async_exec && !target_can_async_p ())
>     error (_("Asynchronous execution not supported on this target."));
> 
>   /* If we are not asked to run in the bg, then prepare to run in the
>      foreground, synchronously.  */
>   if (!async_exec && target_can_async_p ())
>     {
>       /* Simulate synchronous execution.  */
>       async_disable_stdin ();
>     }
> 
>   if (arg)
>     error (_("The \"finish\" command does not take any arguments."));
>  ...
> 
> so it seems like finish *does* secretly accept options, but in this case it's 
> trying to be secret about it rather than someone just didn't fully document 
> it.  or i read the "arg" parsing logic above incorrectly.

Isn't that the case of "finish &" ?

Re: [PATCH] gdb: improve usage strings

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 663 bytes --]

On Saturday 11 August 2012 13:52:24 Eli Zaretskii wrote:
> From: Mike Frysinger <vapier@gentoo.org>
> > so it seems like finish *does* secretly accept options, but in this case
> > it's trying to be secret about it rather than someone just didn't fully
> > document it.  or i read the "arg" parsing logic above incorrectly.
> 
> Isn't that the case of "finish &" ?

i'm not familiar with async behavior in gdb.  is it something that applies to 
all commands, or just to a select few ?  if the latter, should we still 
document it in the usage string ?
	Usage: finish [&]
if the former, seems weird that every command would parse it itself ...
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH] gdb: improve usage strings

[Tom Tromey]

>>>>> "Mike" == Mike Frysinger <vapier@gentoo.org> writes:

>> Isn't that the case of "finish &" ?

Mike> i'm not familiar with async behavior in gdb.  is it something that
Mike> applies to all commands, or just to a select few ?

Just a few.  From (info "(gdb) Background Execution") they are: run,
attach, step, stepi, next, nexti, continue, finish, until.

Mike> if the latter, should we still document it in the usage string ?

I think that would be the most informative.

Tom

Re: [PATCH] gdb: improve usage strings

[Doug Evans]

On Sat, Aug 11, 2012 at 10:36 AM, Mike Frysinger <vapier@gentoo.org> wrote:
> On Saturday 11 August 2012 13:16:18 Eli Zaretskii wrote:
>> > From: Mike Frysinger <vapier@gentoo.org>
>> > Date: Sat, 11 Aug 2012 12:54:40 -0400
>> >    c = add_com ("signal", class_run, signal_command, _("\
>> >
>> > -Continue program giving it signal specified by the argument.\n\
>> > -An argument of \"0\" means continue program without giving it a
>> > signal."));
>> > +Continue program by sending it the specified signal.\n\
>>
>> This "by sending it" is AFAIU inaccurate: we don't continue program
>> _by_ sending it the signal, we continue the program _and_ send it the
>> signal.  I actually don't see anything wrong with the original
>> wording.
>
> ok, but your response shows what i was trying to fix:
>         - adding "the" before "program"
>         - changing "giving" to "sending"
> the "by" change was incidental
>
> so i'll change it to:
>         Continue program and send it the specified signal.

fwiw, I'm not comfortable with that wording.
To the naive user it's not clear (IMO) that the program is resumed
with the specified signal, i.e., I can imagine the user wondering if
there's a gap between when the target is resumed and when the signal
is delivered.

Do we have a target where there can be a delay? (e.g, the figurative
equivalent of "continue &; kill SIGNAL)?

Given that, I like something along the lines of "Continue program by
sending it the specified signal."

Re: [PATCH] gdb: improve usage strings

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1987 bytes --]

On Sunday 12 August 2012 01:06:16 Doug Evans wrote:
> On Sat, Aug 11, 2012 at 10:36 AM, Mike Frysinger <vapier@gentoo.org> wrote:
> > On Saturday 11 August 2012 13:16:18 Eli Zaretskii wrote:
> >> > From: Mike Frysinger <vapier@gentoo.org>
> >> > Date: Sat, 11 Aug 2012 12:54:40 -0400
> >> > 
> >> >    c = add_com ("signal", class_run, signal_command, _("\
> >> > 
> >> > -Continue program giving it signal specified by the argument.\n\
> >> > -An argument of \"0\" means continue program without giving it a
> >> > signal."));
> >> > +Continue program by sending it the specified signal.\n\
> >> 
> >> This "by sending it" is AFAIU inaccurate: we don't continue program
> >> _by_ sending it the signal, we continue the program _and_ send it the
> >> signal.  I actually don't see anything wrong with the original
> >> wording.
> > 
> > ok, but your response shows what i was trying to fix:
> >         - adding "the" before "program"
> >         - changing "giving" to "sending"
> > 
> > the "by" change was incidental
> > 
> > so i'll change it to:
> >         Continue program and send it the specified signal.
> 
> fwiw, I'm not comfortable with that wording.
> To the naive user it's not clear (IMO) that the program is resumed
> with the specified signal, i.e., I can imagine the user wondering if
> there's a gap between when the target is resumed and when the signal
> is delivered.

fwiw, i wondered the same thing when pondering the wording :)

> Do we have a target where there can be a delay? (e.g, the figurative
> equivalent of "continue &; kill SIGNAL)?

thinking about it a bit more (in my head vs reading code), i assume (on linux 
at least) we use PTRACE_CONT which allows for simultaneous resumption and 
signal delivery.  at least, as simultaneous as possible.

> Given that, I like something along the lines of "Continue program by
> sending it the specified signal."

what if i added the word "simultaneously" ?
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH] gdb: improve usage strings

[Eli Zaretskii]

> Date: Sat, 11 Aug 2012 22:06:16 -0700
> From: Doug Evans <dje@google.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> 
> Given that, I like something along the lines of "Continue program by
> sending it the specified signal."

But that sounds like the signal is what causes the program to be
resumed, which AFAIK is inaccurate, and prompted my comment in the
first place.

[PATCH v2] gdb: improve usage strings

[Mike Frysinger]

This adds Usage strings to a bunch of commands, tweaks the grammar in a
few, and improves the help text for the handle command.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>

2012-08-11  Mike Frysinger  <vapier@gentoo.org>

	* infcmd.c (_initialize_infcmd): Update help text for the signal,
	stepi, nexti, finish, next, step, jump, and continue commands.
	* infrun.c (_initialize_infrun): Update help text for the handle
	command.
---
v2
	- improve "signal" and "next" phrasing

 gdb/infcmd.c |   25 ++++++++++++++++---------
 gdb/infrun.c |    6 ++++++
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index d56503c..78bfc04 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3017,40 +3017,45 @@ The target will wait for another debugger to connect.  Not available for\n\
 all targets."));
 
   c = add_com ("signal", class_run, signal_command, _("\
-Continue program giving it signal specified by the argument.\n\
-An argument of \"0\" means continue program without giving it a signal."));
+Continue program and simultaneously send it the specified signal.\n\
+Usage: signal SIGNAL\n\
+An argument of \"0\" means continue the program without sending it a signal."));
   set_cmd_completer (c, signal_completer);
 
   add_com ("stepi", class_run, stepi_command, _("\
 Step one instruction exactly.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: stepi [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("si", "stepi", class_alias, 0);
 
   add_com ("nexti", class_run, nexti_command, _("\
 Step one instruction, but proceed through subroutine calls.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: nexti [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("ni", "nexti", class_alias, 0);
 
   add_com ("finish", class_run, finish_command, _("\
 Execute until selected stack frame returns.\n\
+Usage: finish\n\
 Upon return, the value returned is printed and put in the value history."));
   add_com_alias ("fin", "finish", class_run, 1);
 
   add_com ("next", class_run, next_command, _("\
 Step program, proceeding through subroutine calls.\n\
-Like the \"step\" command as long as subroutine calls do not happen;\n\
-when they do, the call is treated as one instruction.\n\
-Argument N means do this N times (or till program stops for another \
-reason)."));
+Usage: next [N]\n\
+Unlike "step", if the current source line calls a subroutine,\n\
+this command does not enter the subroutine, but instead steps over\n\
+the call, in effect treating it as a single source line.)"));
   add_com_alias ("n", "next", class_run, 1);
   if (xdb_commands)
     add_com_alias ("S", "next", class_run, 1);
 
   add_com ("step", class_run, step_command, _("\
 Step program until it reaches a different source line.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: step [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("s", "step", class_run, 1);
 
@@ -3069,6 +3074,7 @@ Execution will also stop upon exit from the current stack frame."));
 
   c = add_com ("jump", class_run, jump_command, _("\
 Continue program being debugged at specified line or address.\n\
+Usage: jump <location>\n\
 Give as argument either LINENUM or *ADDR, where ADDR is an expression\n\
 for an address to start at."));
   set_cmd_completer (c, location_completer);
@@ -3090,6 +3096,7 @@ This command is a combination of tbreak and jump."));
 
   add_com ("continue", class_run, continue_command, _("\
 Continue program being debugged, after signal or breakpoint.\n\
+Usage: continue [N]\n\
 If proceeding from breakpoint, a number N may be used as an argument,\n\
 which means to set the ignore count of that breakpoint to N - 1 (so that\n\
 the breakpoint won't break until the Nth time it is reached).\n\
diff --git a/gdb/infrun.c b/gdb/infrun.c
index 4f59a92..6663086 100644
--- a/gdb/infrun.c
+++ b/gdb/infrun.c
@@ -7099,12 +7099,17 @@ Specify a signal as argument to print info on that signal only."));
 
   c = add_com ("handle", class_run, handle_command, _("\
 Specify how to handle a signal.\n\
+Usage: handle SIGNAL [ACTIONS]\n\
 Args are signals and actions to apply to those signals.\n\
+If no actions are specified, the current settings for the specified signal\n\
+will be displayed instead.\n\
+\n\
 Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals\n\
 from 1-15 are allowed for compatibility with old versions of GDB.\n\
 Numeric ranges may be specified with the form LOW-HIGH (e.g. 1-5).\n\
 The special arg \"all\" is recognized to mean all signals except those\n\
 used by the debugger, typically SIGTRAP and SIGINT.\n\
+\n\
 Recognized actions include \"stop\", \"nostop\", \"print\", \"noprint\",\n\
 \"pass\", \"nopass\", \"ignore\", or \"noignore\".\n\
 Stop means reenter debugger if this signal happens (implies print).\n\
@@ -7113,6 +7118,7 @@ Pass means let program see this signal; otherwise program doesn't know.\n\
 Ignore is a synonym for nopass and noignore is a synonym for pass.\n\
 Pass and Stop may be combined."));
   set_cmd_completer (c, handle_completer);
+
   if (xdb_commands)
     {
       add_com ("lz", class_info, signals_info, _("\
-- 
1.7.9.7

Re: [PATCH v2] gdb: improve usage strings

[Doug Evans]

On Sun, Aug 12, 2012 at 7:05 PM, Mike Frysinger <vapier@gentoo.org> wrote:
> [...]
> diff --git a/gdb/infcmd.c b/gdb/infcmd.c
> index d56503c..78bfc04 100644
> --- a/gdb/infcmd.c
> +++ b/gdb/infcmd.c
> @@ -3017,40 +3017,45 @@ The target will wait for another debugger to connect.  Not available for\n\
>  all targets."));
>
>    c = add_com ("signal", class_run, signal_command, _("\
> -Continue program giving it signal specified by the argument.\n\
> -An argument of \"0\" means continue program without giving it a signal."));
> +Continue program and simultaneously send it the specified signal.\n\
> +Usage: signal SIGNAL\n\
> +An argument of \"0\" means continue the program without sending it a signal."));
>    set_cmd_completer (c, signal_completer);

That's ok I guess.  How about "Continue program with the specified signal." ?

Also, it would be good to augment the docs for "sig 0" to denote it
can be used to resume a program and discard the signal that is pending
for it, and would otherwise receive if you did a "continue".  It's
kinda implicit in the existing wording, but I've seen a few cases
where more clarity would have helped.

How about:

An argument of "0" means continue the program without sending it a signal.
This is useful in cases where the program stopped because of a signal,
and you want to resume the program and discard the signal.

Or some such.

E.g. [I'm just using SIGINT as an example here.]

(gdb) handle SIGINT stop print pass
SIGINT is used by the debugger.
Are you sure you want to change it? (y or n) y

Signal        Stop      Print   Pass to program Description
SIGINT        Yes       Yes     Yes             Interrupt
(gdb) r
Starting program: /home/dje/forever.x64
  C-c C-c
Program received signal SIGINT, Interrupt.
0x00007ffff7b04680 in __nanosleep_nocancel ()
    at ../sysdeps/unix/syscall-template.S:82
82      ../sysdeps/unix/syscall-template.S: No such file or directory.
(gdb) sig 0
Continuing with no signal.
  C-c C-c
Program received signal SIGINT, Interrupt.
0x00007ffff7b04680 in __nanosleep_nocancel ()
    at ../sysdeps/unix/syscall-template.S:82
82      in ../sysdeps/unix/syscall-template.S
(gdb) c
Continuing.

Program terminated with signal SIGINT, Interrupt.
The program no longer exists.
(gdb)

Re: [PATCH v2] gdb: improve usage strings

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1072 bytes --]

On Monday 13 August 2012 16:28:42 Doug Evans wrote:
> On Sun, Aug 12, 2012 at 7:05 PM, Mike Frysinger <vapier@gentoo.org> wrote:
> > [...]
> > --- a/gdb/infcmd.c
> > +++ b/gdb/infcmd.c
> >  
> >    c = add_com ("signal", class_run, signal_command, _("\
> > -Continue program giving it signal specified by the argument.\n\
> > -An argument of \"0\" means continue program without giving it a
> > signal."));
> > +Continue program and simultaneously send it the specified signal.\n\
> > +Usage: signal SIGNAL\n\
> > +An argument of \"0\" means continue the program without sending it a
> > signal."));
> > 
> >    set_cmd_completer (c, signal_completer);
> 
> That's ok I guess.  How about "Continue program with the specified signal."

i can live with that

> An argument of "0" means continue the program without sending it a signal.
> This is useful in cases where the program stopped because of a signal,
> and you want to resume the program and discard the signal.

s/discard/ignore/ ?  although people might confuse that with SIG_IGN.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2] gdb: improve usage strings

[Pedro Alves]

On 08/13/2012 09:28 PM, Doug Evans wrote:
> On Sun, Aug 12, 2012 at 7:05 PM, Mike Frysinger <vapier@gentoo.org> wrote:
>>    c = add_com ("signal", class_run, signal_command, _("\
>> -Continue program giving it signal specified by the argument.\n\
>> -An argument of \"0\" means continue program without giving it a signal."));
>> +Continue program and simultaneously send it the specified signal.\n\
>> +Usage: signal SIGNAL\n\
>> +An argument of \"0\" means continue the program without sending it a signal."));
>>    set_cmd_completer (c, signal_completer);
> 
> That's ok I guess.  How about "Continue program with the specified signal." ?

Agreed.  I was catching on up the thread, and thought of suggest this.  I could
swear that's terminology we already use.  Ah, at least here:

...
@item C @var{sig}@r{[};@var{addr}@r{]}
@cindex @samp{C} packet
Continue with signal @var{sig} (hex signal number).  If
^^^^^^^^^^^^^^^^^^^^
@samp{;@var{addr}} is omitted, resume at same address.
...
You can also use the @code{signal} command to prevent your program from
seeing a signal, or cause it to see a signal it normally would not see,
or to give it any signal at any time.  For example, if your program stopped
due to some sort of memory reference error, you might store correct
values into the erroneous variables and continue, hoping to see more
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal.  To prevent this,
you can continue with @samp{signal 0}.  @xref{Signaling, ,Giving your
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Program a Signal}.
...

Consistency between help and manual is good.

> 
> Also, it would be good to augment the docs for "sig 0" to denote it
> can be used to resume a program and discard the signal that is pending
> for it, and would otherwise receive if you did a "continue".  It's
> kinda implicit in the existing wording, but I've seen a few cases
> where more clarity would have helped.
> 
> How about:
> 
> An argument of "0" means continue the program without sending it a signal.
> This is useful in cases where the program stopped because of a signal,
> and you want to resume the program and discard the signal.

-- 
Pedro Alves

[PATCH v3] gdb: improve usage strings

[Mike Frysinger]

This adds Usage strings to a bunch of commands, tweaks the grammar in a
few, and improves the help text for the handle command.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>

2012-08-11  Mike Frysinger  <vapier@gentoo.org>

	* infcmd.c (_initialize_infcmd): Update help text for the signal,
	stepi, nexti, finish, next, step, jump, and continue commands.
	* infrun.c (_initialize_infrun): Update help text for the handle
	command.
---
v3
	- tweak "signal" documentation more with feedback from Doug

 gdb/infcmd.c |   29 ++++++++++++++++++++---------
 gdb/infrun.c |    6 ++++++
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index d56503c..cbd8a0a 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3017,40 +3017,49 @@ The target will wait for another debugger to connect.  Not available for\n\
 all targets."));
 
   c = add_com ("signal", class_run, signal_command, _("\
-Continue program giving it signal specified by the argument.\n\
-An argument of \"0\" means continue program without giving it a signal."));
+Continue program with the specified signal.\n\
+Usage: signal SIGNAL\n\
+The SIGNAL arugment is processed the same as the handle command.\n\
+\n\
+An argument of \"0\" means continue the program without sending it a signal.\n\
+This is useful in cases where the program stopped because of a signal,\n\
+and you want to resume the program while discarding the signal."));
   set_cmd_completer (c, signal_completer);
 
   add_com ("stepi", class_run, stepi_command, _("\
 Step one instruction exactly.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: stepi [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("si", "stepi", class_alias, 0);
 
   add_com ("nexti", class_run, nexti_command, _("\
 Step one instruction, but proceed through subroutine calls.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: nexti [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("ni", "nexti", class_alias, 0);
 
   add_com ("finish", class_run, finish_command, _("\
 Execute until selected stack frame returns.\n\
+Usage: finish\n\
 Upon return, the value returned is printed and put in the value history."));
   add_com_alias ("fin", "finish", class_run, 1);
 
   add_com ("next", class_run, next_command, _("\
 Step program, proceeding through subroutine calls.\n\
-Like the \"step\" command as long as subroutine calls do not happen;\n\
-when they do, the call is treated as one instruction.\n\
-Argument N means do this N times (or till program stops for another \
-reason)."));
+Usage: next [N]\n\
+Unlike \"step\", if the current source line calls a subroutine,\n\
+this command does not enter the subroutine, but instead steps over\n\
+the call, in effect treating it as a single source line.)"));
   add_com_alias ("n", "next", class_run, 1);
   if (xdb_commands)
     add_com_alias ("S", "next", class_run, 1);
 
   add_com ("step", class_run, step_command, _("\
 Step program until it reaches a different source line.\n\
-Argument N means do this N times (or till program stops for another \
+Usage: step [N]\n\
+Argument N means step N times (or till program stops for another \
 reason)."));
   add_com_alias ("s", "step", class_run, 1);
 
@@ -3069,6 +3078,7 @@ Execution will also stop upon exit from the current stack frame."));
 
   c = add_com ("jump", class_run, jump_command, _("\
 Continue program being debugged at specified line or address.\n\
+Usage: jump <location>\n\
 Give as argument either LINENUM or *ADDR, where ADDR is an expression\n\
 for an address to start at."));
   set_cmd_completer (c, location_completer);
@@ -3090,6 +3100,7 @@ This command is a combination of tbreak and jump."));
 
   add_com ("continue", class_run, continue_command, _("\
 Continue program being debugged, after signal or breakpoint.\n\
+Usage: continue [N]\n\
 If proceeding from breakpoint, a number N may be used as an argument,\n\
 which means to set the ignore count of that breakpoint to N - 1 (so that\n\
 the breakpoint won't break until the Nth time it is reached).\n\
diff --git a/gdb/infrun.c b/gdb/infrun.c
index 4f59a92..6663086 100644
--- a/gdb/infrun.c
+++ b/gdb/infrun.c
@@ -7099,12 +7099,17 @@ Specify a signal as argument to print info on that signal only."));
 
   c = add_com ("handle", class_run, handle_command, _("\
 Specify how to handle a signal.\n\
+Usage: handle SIGNAL [ACTIONS]\n\
 Args are signals and actions to apply to those signals.\n\
+If no actions are specified, the current settings for the specified signal\n\
+will be displayed instead.\n\
+\n\
 Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals\n\
 from 1-15 are allowed for compatibility with old versions of GDB.\n\
 Numeric ranges may be specified with the form LOW-HIGH (e.g. 1-5).\n\
 The special arg \"all\" is recognized to mean all signals except those\n\
 used by the debugger, typically SIGTRAP and SIGINT.\n\
+\n\
 Recognized actions include \"stop\", \"nostop\", \"print\", \"noprint\",\n\
 \"pass\", \"nopass\", \"ignore\", or \"noignore\".\n\
 Stop means reenter debugger if this signal happens (implies print).\n\
@@ -7113,6 +7118,7 @@ Pass means let program see this signal; otherwise program doesn't know.\n\
 Ignore is a synonym for nopass and noignore is a synonym for pass.\n\
 Pass and Stop may be combined."));
   set_cmd_completer (c, handle_completer);
+
   if (xdb_commands)
     {
       add_com ("lz", class_info, signals_info, _("\
-- 
1.7.9.7

Re: [PATCH v3] gdb: improve usage strings

[Doug Evans]

On Mon, Aug 13, 2012 at 10:29 PM, Mike Frysinger <vapier@gentoo.org> wrote:
> This adds Usage strings to a bunch of commands, tweaks the grammar in a
> few, and improves the help text for the handle command.
>
> Signed-off-by: Mike Frysinger <vapier@gentoo.org>
>
> 2012-08-11  Mike Frysinger  <vapier@gentoo.org>
>
>         * infcmd.c (_initialize_infcmd): Update help text for the signal,
>         stepi, nexti, finish, next, step, jump, and continue commands.
>         * infrun.c (_initialize_infrun): Update help text for the handle
>         command.
> ---
> v3
>         - tweak "signal" documentation more with feedback from Doug
>
>  gdb/infcmd.c |   29 ++++++++++++++++++++---------
>  gdb/infrun.c |    6 ++++++
>  2 files changed, 26 insertions(+), 9 deletions(-)
>
> diff --git a/gdb/infcmd.c b/gdb/infcmd.c
> index d56503c..cbd8a0a 100644
> --- a/gdb/infcmd.c
> +++ b/gdb/infcmd.c
> @@ -3017,40 +3017,49 @@ The target will wait for another debugger to connect.  Not available for\n\
>  all targets."));
>
>    c = add_com ("signal", class_run, signal_command, _("\
> -Continue program giving it signal specified by the argument.\n\
> -An argument of \"0\" means continue program without giving it a signal."));
> +Continue program with the specified signal.\n\
> +Usage: signal SIGNAL\n\
> +The SIGNAL arugment is processed the same as the handle command.\n\
> +\n\
> +An argument of \"0\" means continue the program without sending it a signal.\n\
> +This is useful in cases where the program stopped because of a signal,\n\
> +and you want to resume the program while discarding the signal."));
>    set_cmd_completer (c, signal_completer);
>
>    add_com ("stepi", class_run, stepi_command, _("\
>  Step one instruction exactly.\n\
> -Argument N means do this N times (or till program stops for another \
> +Usage: stepi [N]\n\
> +Argument N means step N times (or till program stops for another \
>  reason)."));
>    add_com_alias ("si", "stepi", class_alias, 0);
>
>    add_com ("nexti", class_run, nexti_command, _("\
>  Step one instruction, but proceed through subroutine calls.\n\
> -Argument N means do this N times (or till program stops for another \
> +Usage: nexti [N]\n\
> +Argument N means step N times (or till program stops for another \
>  reason)."));
>    add_com_alias ("ni", "nexti", class_alias, 0);
>
>    add_com ("finish", class_run, finish_command, _("\
>  Execute until selected stack frame returns.\n\
> +Usage: finish\n\
>  Upon return, the value returned is printed and put in the value history."));
>    add_com_alias ("fin", "finish", class_run, 1);
>
>    add_com ("next", class_run, next_command, _("\
>  Step program, proceeding through subroutine calls.\n\
> -Like the \"step\" command as long as subroutine calls do not happen;\n\
> -when they do, the call is treated as one instruction.\n\
> -Argument N means do this N times (or till program stops for another \
> -reason)."));
> +Usage: next [N]\n\
> +Unlike \"step\", if the current source line calls a subroutine,\n\
> +this command does not enter the subroutine, but instead steps over\n\
> +the call, in effect treating it as a single source line.)"));
>    add_com_alias ("n", "next", class_run, 1);
>    if (xdb_commands)
>      add_com_alias ("S", "next", class_run, 1);
>
>    add_com ("step", class_run, step_command, _("\
>  Step program until it reaches a different source line.\n\
> -Argument N means do this N times (or till program stops for another \
> +Usage: step [N]\n\
> +Argument N means step N times (or till program stops for another \
>  reason)."));
>    add_com_alias ("s", "step", class_run, 1);
>
> @@ -3069,6 +3078,7 @@ Execution will also stop upon exit from the current stack frame."));
>
>    c = add_com ("jump", class_run, jump_command, _("\
>  Continue program being debugged at specified line or address.\n\
> +Usage: jump <location>\n\
>  Give as argument either LINENUM or *ADDR, where ADDR is an expression\n\
>  for an address to start at."));
>    set_cmd_completer (c, location_completer);
> @@ -3090,6 +3100,7 @@ This command is a combination of tbreak and jump."));
>
>    add_com ("continue", class_run, continue_command, _("\
>  Continue program being debugged, after signal or breakpoint.\n\
> +Usage: continue [N]\n\
>  If proceeding from breakpoint, a number N may be used as an argument,\n\
>  which means to set the ignore count of that breakpoint to N - 1 (so that\n\
>  the breakpoint won't break until the Nth time it is reached).\n\
> diff --git a/gdb/infrun.c b/gdb/infrun.c
> index 4f59a92..6663086 100644
> --- a/gdb/infrun.c
> +++ b/gdb/infrun.c
> @@ -7099,12 +7099,17 @@ Specify a signal as argument to print info on that signal only."));
>
>    c = add_com ("handle", class_run, handle_command, _("\
>  Specify how to handle a signal.\n\
> +Usage: handle SIGNAL [ACTIONS]\n\
>  Args are signals and actions to apply to those signals.\n\
> +If no actions are specified, the current settings for the specified signal\n\
> +will be displayed instead.\n\
> +\n\
>  Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals\n\
>  from 1-15 are allowed for compatibility with old versions of GDB.\n\
>  Numeric ranges may be specified with the form LOW-HIGH (e.g. 1-5).\n\
>  The special arg \"all\" is recognized to mean all signals except those\n\
>  used by the debugger, typically SIGTRAP and SIGINT.\n\
> +\n\
>  Recognized actions include \"stop\", \"nostop\", \"print\", \"noprint\",\n\
>  \"pass\", \"nopass\", \"ignore\", or \"noignore\".\n\
>  Stop means reenter debugger if this signal happens (implies print).\n\
> @@ -7113,6 +7118,7 @@ Pass means let program see this signal; otherwise program doesn't know.\n\
>  Ignore is a synonym for nopass and noignore is a synonym for pass.\n\
>  Pass and Stop may be combined."));
>    set_cmd_completer (c, handle_completer);
> +
>    if (xdb_commands)
>      {
>        add_com ("lz", class_info, signals_info, _("\
> --
> 1.7.9.7
>


Ok with me, but I'd wait for Eli to check too.

Thanks!

Re: [PATCH v3] gdb: improve usage strings

[Eli Zaretskii]

> Date: Tue, 14 Aug 2012 10:34:10 -0700
> From: Doug Evans <dje@google.com>
> Cc: gdb-patches@sourceware.org, Eli Zaretskii <eliz@gnu.org>
> 
> Ok with me, but I'd wait for Eli to check too.
> 
> Thanks!

I'm quite sure I already did.  Mike, is that right?

Re: [PATCH v3] gdb: improve usage strings

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 525 bytes --]

On Tuesday 14 August 2012 14:10:14 Eli Zaretskii wrote:
> > Date: Tue, 14 Aug 2012 10:34:10 -0700
> > From: Doug Evans <dje@google.com>
> > Cc: gdb-patches@sourceware.org, Eli Zaretskii <eliz@gnu.org>
> > 
> > Ok with me, but I'd wait for Eli to check too.
> > 
> > Thanks!
> 
> I'm quite sure I already did.  Mike, is that right?

i've tweaked the signal wording, but i think the latest iteration covers 
everyone's concerns, so i'll merge this and we can fight over improving it 
further if need be ;)
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Regression for gdb.base/help.exp [Re: [PATCH v3] gdb: improve usage strings]

[Jan Kratochvil]

On Wed, 15 Aug 2012 03:58:41 +0200, Mike Frysinger wrote:
> so i'll merge this and we can fight over improving it further if need be ;)

Running ./gdb.base/help.exp ...
FAIL: gdb.base/help.exp: help finish
FAIL: gdb.base/help.exp: help jump
FAIL: gdb.base/help.exp: help next "n" abbreviation
FAIL: gdb.base/help.exp: help next
FAIL: gdb.base/help.exp: help nexti
FAIL: gdb.base/help.exp: help step "s" abbreviation
FAIL: gdb.base/help.exp: help step #1
FAIL: gdb.base/help.exp: help step #2
FAIL: gdb.base/help.exp: help stepi "si" abbreviation
FAIL: gdb.base/help.exp: help stepi
FAIL: gdb.base/help.exp: help signal



Regards,
Jan

Re: Regression for gdb.base/help.exp [Re: [PATCH v3] gdb: improve usage strings]

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1011 bytes --]

On Wednesday 15 August 2012 03:22:11 Jan Kratochvil wrote:
> On Wed, 15 Aug 2012 03:58:41 +0200, Mike Frysinger wrote:
> > so i'll merge this and we can fight over improving it further if need be
> > ;)
> 
> Running ./gdb.base/help.exp ...
> FAIL: gdb.base/help.exp: help finish
> FAIL: gdb.base/help.exp: help jump
> FAIL: gdb.base/help.exp: help next "n" abbreviation
> FAIL: gdb.base/help.exp: help next
> FAIL: gdb.base/help.exp: help nexti
> FAIL: gdb.base/help.exp: help step "s" abbreviation
> FAIL: gdb.base/help.exp: help step #1
> FAIL: gdb.base/help.exp: help step #2
> FAIL: gdb.base/help.exp: help stepi "si" abbreviation
> FAIL: gdb.base/help.exp: help stepi
> FAIL: gdb.base/help.exp: help signal

ah, figures.  i'll post a patch in a bit.

btw, is there an easy way to run one specific .exp ?  for gdb.base, i found i 
can cheat by doing:
	make check-gdb.base1 BASE1_FILES=gdb.base/help.exp 
but that seems like an awful hack and abuse of the current makefile ...
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Regression for gdb.base/help.exp [Re: [PATCH v3] gdb: improve usage strings]

[Doug Evans]

On Wed, Aug 15, 2012 at 9:25 AM, Mike Frysinger <vapier@gentoo.org> wrote:
> On Wednesday 15 August 2012 03:22:11 Jan Kratochvil wrote:
>> On Wed, 15 Aug 2012 03:58:41 +0200, Mike Frysinger wrote:
>> > so i'll merge this and we can fight over improving it further if need be
>> > ;)
>>
>> Running ./gdb.base/help.exp ...
>> FAIL: gdb.base/help.exp: help finish
>> FAIL: gdb.base/help.exp: help jump
>> FAIL: gdb.base/help.exp: help next "n" abbreviation
>> FAIL: gdb.base/help.exp: help next
>> FAIL: gdb.base/help.exp: help nexti
>> FAIL: gdb.base/help.exp: help step "s" abbreviation
>> FAIL: gdb.base/help.exp: help step #1
>> FAIL: gdb.base/help.exp: help step #2
>> FAIL: gdb.base/help.exp: help stepi "si" abbreviation
>> FAIL: gdb.base/help.exp: help stepi
>> FAIL: gdb.base/help.exp: help signal
>
> ah, figures.  i'll post a patch in a bit.
>
> btw, is there an easy way to run one specific .exp ?  for gdb.base, i found i
> can cheat by doing:
>         make check-gdb.base1 BASE1_FILES=gdb.base/help.exp
> but that seems like an awful hack and abuse of the current makefile ...
> -mike

make check RUNTESTFLAGS=foo.exp

Re: Regression for gdb.base/help.exp [Re: [PATCH v3] gdb: improve usage strings]

[Sergio Durigan Junior]

[-- Attachment #1: Type: text/plain, Size: 475 bytes --]

On Wednesday, August 15 2012, Mike Frysinger wrote:

> btw, is there an easy way to run one specific .exp ?  for gdb.base, i found i 
> can cheat by doing:

You can:

make check RUNTESTFLAGS='gdb.bla/test.exp' # or whatever test you want

If you want to run with -m32:

make check RUNTESTFLAGS='--target_board=unix/-m32 gdb.bla/test.exp'

There are indeed many options for RUNTESTFLAGS, you can see more at:

sourceware.org/gdb/wiki/TestingGDB

-- 
Sergio

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: Regression for gdb.base/help.exp [Re: [PATCH v3] gdb: improve usage strings]

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 8287 bytes --]

On Wednesday 15 August 2012 03:22:11 Jan Kratochvil wrote:
> On Wed, 15 Aug 2012 03:58:41 +0200, Mike Frysinger wrote:
> > so i'll merge this and we can fight over improving it further if need be
> > ;)
> 
> Running ./gdb.base/help.exp ...
> FAIL: gdb.base/help.exp: help finish
> FAIL: gdb.base/help.exp: help jump
> FAIL: gdb.base/help.exp: help next "n" abbreviation
> FAIL: gdb.base/help.exp: help next
> FAIL: gdb.base/help.exp: help nexti
> FAIL: gdb.base/help.exp: help step "s" abbreviation
> FAIL: gdb.base/help.exp: help step #1
> FAIL: gdb.base/help.exp: help step #2
> FAIL: gdb.base/help.exp: help stepi "si" abbreviation
> FAIL: gdb.base/help.exp: help stepi
> FAIL: gdb.base/help.exp: help signal

i've committed this
-mike

2012-08-16  Mike Frysinger  <vapier@gentoo.org>

	* infcmd.c (_initialize_infcmd): Remove trailing ) in next help text.

--- infcmd.c	15 Aug 2012 01:59:42 -0000	1.309
+++ infcmd.c	17 Aug 2012 03:03:46 -0000
@@ -3051,7 +3051,7 @@ Step program, proceeding through subrout
 Usage: next [N]\n\
 Unlike \"step\", if the current source line calls a subroutine,\n\
 this command does not enter the subroutine, but instead steps over\n\
-the call, in effect treating it as a single source line.)"));
+the call, in effect treating it as a single source line."));
   add_com_alias ("n", "next", class_run, 1);
   if (xdb_commands)
     add_com_alias ("S", "next", class_run, 1);

2012-08-16  Mike Frysinger  <vapier@gentoo.org>

	* gdb.base/help.exp: Update expected output.   

--- testsuite/gdb.base/help.exp	13 Aug 2012 21:14:48 -0000	1.60
+++ testsuite/gdb.base/help.exp	17 Aug 2012 03:03:46 -0000
@@ -194,7 +194,7 @@ gdb_test "help file" "Use FILE as progra
 # test help files
 gdb_test "help files" "Specifying.*" "help files"
 # test help finish
-gdb_test "help finish" "Execute until selected stack frame returns\.\[\r\n\]+Upon return, the value returned is printed and put in 
the value history\." "help finish"
+gdb_test "help finish" "Execute until selected stack frame returns\.\[\r\n\]+Usage: finish\[\r\n\]+Upon return, the value returned is 
printed and put in the value history\.\[\r\n\]+" "help finish"
 # test help forward-search
 gdb_test "help forward-search" "Search for regular expression \\(see regex\\(3\\)\\) from last line listed.*" "help forward-search"
 # test help gcore
@@ -295,7 +295,7 @@ gdb_test "help info watchpoints" \
 # test help inspect
 gdb_test "help inspect" "Same as \"print\" command, except that if you are running in the epoch\[\r\n\]+environment, the value is 
printed in its own window\." "help inspect"
 # test help jump
-gdb_test "help jump" "Continue program being debugged at specified line or address\.\[\r\n\]+Give as argument either LINENUM 
or \[*\]+ADDR, where ADDR is an expression\[\r\n\]+for an address to start at\." "help jump"
+gdb_test "help jump" "Continue program being debugged at specified line or address\.\[\r\n\]+Usage: jump 
<location>\[\r\n\]+Give as argument either LINENUM or \[*\]+ADDR, where ADDR is an expression\[\r\n\]+for an address to start 
at\." "help jump"
 # test help kill
 test_prefix_command_help "kill" {
     "Kill execution of program being debugged\.\[\r\n\]+"
@@ -309,11 +309,11 @@ gdb_test "help load" "Dynamically load F
 # test help make
 gdb_test "help make" "Run the ``make'' program using the rest of the line as arguments\." "help make"
 # test help next "n" abbreviation
-gdb_test "help n" "Step program, proceeding through subroutine calls\.\[\r\n\]+Like the \"step\" command as long as subroutine 
calls do not happen;\[\r\n\]+when they do, the call is treated as one instruction\.\[\r\n\]+Argument N means do this N times \\(or 
till program stops for another reason\\)\." "help next \"n\" abbreviation"
+gdb_test "help n" "Step program, proceeding through subroutine calls\.\[\r\n\]+Usage: next \\\[N\\\]\[\r\n\]+Unlike \"step\", if the 
current source line calls a subroutine,\[\r\n\]+this command does not enter the subroutine, but instead steps over\[\r\n\]+the call, 
in effect treating it as a single source line\.\[\r\n\]+" "help next \"n\" abbreviation"
 # test help next
-gdb_test "help next" "Step program, proceeding through subroutine calls\.\[\r\n\]+Like the \"step\" command as long as 
subroutine calls do not happen;\[\r\n\]+when they do, the call is treated as one instruction\.\[\r\n\]+Argument N means do this N 
times \\(or till program stops for another reason\\)\." "help next"
+gdb_test "help next" "Step program, proceeding through subroutine calls\.\[\r\n\]+Usage: next \\\[N\\\]\[\r\n\]+Unlike \"step\", if 
the current source line calls a subroutine,\[\r\n\]+this command does not enter the subroutine, but instead steps over\[\r\n\]+the 
call, in effect treating it as a single source line\.\[\r\n\]+" "help next \"n\" abbreviation"
 # test help nexti
-gdb_test "help ni" "Step one instruction, but proceed through subroutine calls\.\[\r\n\]+Argument N means do this N times \\(or till 
program stops for another reason\\)\." "help nexti"
+gdb_test "help ni" "Step one instruction, but proceed through subroutine calls\.\[\r\n\]+Usage: nexti \\\[N\\\]\[\r\n\]+Argument N 
means step N times \\(or till program stops for another reason\\)\.\[\r\n\]+" "help nexti"
 # all the commands that used to be here are now in "maintainance" instead
 # test help obscure
 test_class_help "obscure" {
@@ -365,9 +365,9 @@ test_class_help "running" {
     "Running the program\.\[\r\n\]+"
 }
 # test help step "s" abbreviation
-gdb_test "help s" "Step program until it reaches a different source line\.\[\r\n\]+Argument N means do this N times \\(or till 
program stops for another reason\\)\." "help step \"s\" abbreviation"
+gdb_test "help s" "Step program until it reaches a different source line\.\[\r\n\]+Usage: step \\\[N\\\]\[\r\n\]+Argument N means 
step N times \\(or till program stops for another reason\\)\.\[\r\n\]+" "help step \"s\" abbreviation"
 # test help step
-gdb_test "help step" "Step program until it reaches a different source line\.\[\r\n\]+Argument N means do this N times \\(or till 
program stops for another reason\\)\." "help step #1"
+gdb_test "help step" "Step program until it reaches a different source line\.\[\r\n\]+Usage: step \\\[N\\\]\[\r\n\]+Argument N 
means step N times \\(or till program stops for another reason\\)\.\[\r\n\]+" "help step #1"
 # test help search
 gdb_test "help search" "Search for regular expression \\(see regex\\(3\\)\\) from last line listed\..*" "help search"
 # test help section
@@ -590,13 +590,13 @@ test_prefix_command_help "show" {
     "Generic command for showing things about the debugger\.\[\r\n\]+"
 }
 # test help step
-gdb_test "help step" "Step program until it reaches a different source line\.\[\r\n\]+Argument N means do this N times \\(or till 
program stops for another reason\\)\." "help step #2"
+gdb_test "help step" "Step program until it reaches a different source line\.\[\r\n\]+Usage: step \\\[N\\\]\[\r\n\]+Argument N 
means step N times \\(or till program stops for another reason\\)\.\[\r\n\]+" "help step #2"
 # test help stepi "si" abbreviation
-gdb_test "help si" "Step one instruction exactly\.\[\r\n\]+Argument N means do this N times \\(or till program stops for another 
reason\\)\." "help stepi \"si\" abbreviation"
+gdb_test "help si" "Step one instruction exactly\.\[\r\n\]+Usage: stepi \\\[N\\\]\[\r\n\]+Argument N means step N times \\(or till 
program stops for another reason\\)\.\[\r\n\]+" "help stepi \"si\" abbreviation"
 # test help stepi
-gdb_test "help stepi" "Step one instruction exactly\.\[\r\n\]+Argument N means do this N times \\(or till program stops for another 
reason\\)\." "help stepi"
+gdb_test "help stepi" "Step one instruction exactly\.\[\r\n\]+Usage: stepi \\\[N\\\]\[\r\n\]+Argument N means step N times \\(or till 
program stops for another reason\\)\.\[\r\n\]+" "help stepi"
 # test help signal
-gdb_test "help signal" "Continue program giving it signal.*" "help signal"
+gdb_test "help signal" "Continue program with the specified signal.*" "help signal"
 # test help source
 # vxgdb reads .vxgdbinit
 # ".-s. .-v." is written that way to avoid the complications of trying

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

further improve "handle" help string

[Pedro Alves]

On 08/15/2012 02:58 AM, Mike Frysinger wrote:
> On Tuesday 14 August 2012 14:10:14 Eli Zaretskii wrote:
>>> Date: Tue, 14 Aug 2012 10:34:10 -0700
>>> From: Doug Evans <dje@google.com>
>>> Cc: gdb-patches@sourceware.org, Eli Zaretskii <eliz@gnu.org>
>>>
>>> Ok with me, but I'd wait for Eli to check too.
>>>
>>> Thanks!
>>
>> I'm quite sure I already did.  Mike, is that right?
> 
> i've tweaked the signal wording, but i think the latest iteration covers 
> everyone's concerns, so i'll merge this and we can fight over improving it 
> further if need be ;)

I'll byte ;-)

I'd like to add a mention that you can specify more than one signal (though
not complicate and distract the main body of the text with this).  I
use this occasionally.  Text mostly borrowed from the sources.

Tested on amd64 Fedora 17.

(gdb) help handle
Specify how to handle signals.
Usage: handle SIGNAL [ACTIONS]
Args are signals and actions to apply to those signals.
If no actions are specified, the current settings for the specified signals
will be displayed instead.

Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals
from 1-15 are allowed for compatibility with old versions of GDB.
Numeric ranges may be specified with the form LOW-HIGH (e.g. 1-5).
The special arg "all" is recognized to mean all signals except those
used by the debugger, typically SIGTRAP and SIGINT.

Recognized actions include "stop", "nostop", "print", "noprint",
"pass", "nopass", "ignore", or "noignore".
Stop means reenter debugger if this signal happens (implies print).
Print means print a message if this signal happens.
Pass means let program see this signal; otherwise program doesn't know.
Ignore is a synonym for nopass and noignore is a synonym for pass.
Pass and Stop may be combined.

Multiple signals may be specified.  Signal numbers and signal names
may be interspersed with actions, with the actions being performed for
all signals cumulatively specified.
(gdb) 


2012-08-23  Pedro Alves  <palves@redhat.com>

	gdb/
	* infrun.c (_initialize_infrun) <handle command help text>:
	Mention that multiple signals are supported.

	gdb/testsuite/
	* gdb.base/help.exp: Adjust to "handle" help text change.
---

 gdb/infrun.c                    |   10 +++++++---
 gdb/testsuite/gdb.base/help.exp |    6 +++---
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/gdb/infrun.c b/gdb/infrun.c
index 9628170..cbab993 100644
--- a/gdb/infrun.c
+++ b/gdb/infrun.c
@@ -7096,10 +7096,10 @@ Specify a signal as argument to print info on that signal only."));
   add_info_alias ("handle", "signals", 0);
 
   c = add_com ("handle", class_run, handle_command, _("\
-Specify how to handle a signal.\n\
+Specify how to handle signals.\n\
 Usage: handle SIGNAL [ACTIONS]\n\
 Args are signals and actions to apply to those signals.\n\
-If no actions are specified, the current settings for the specified signal\n\
+If no actions are specified, the current settings for the specified signals\n\
 will be displayed instead.\n\
 \n\
 Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals\n\
@@ -7114,7 +7114,11 @@ Stop means reenter debugger if this signal happens (implies print).\n\
 Print means print a message if this signal happens.\n\
 Pass means let program see this signal; otherwise program doesn't know.\n\
 Ignore is a synonym for nopass and noignore is a synonym for pass.\n\
-Pass and Stop may be combined."));
+Pass and Stop may be combined.\n\
+\n\
+Multiple signals may be specified.  Signal numbers and signal names\n\
+may be interspersed with actions, with the actions being performed for\n\
+all signals cumulatively specified."));
   set_cmd_completer (c, handle_completer);
 
   if (xdb_commands)
diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index b6582ba..7fffd00 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -219,7 +219,7 @@ gdb_test "help h" "Print list of commands\." "help help \"h\" abbreviation"
 # test help help
 gdb_test "help help" "Print list of commands\." "help help"
 # test help handle
-gdb_test "help handle" "Specify how to handle a signal\..*" "help handle"
+gdb_test "help handle" "Specify how to handle signals\..*" "help handle"
 # test help info "i" abbreviation
 test_prefix_command_help {"i" "info"} {
     "Generic command for showing things about the program being debugged\.\[\r\n\]+"
@@ -699,8 +699,8 @@ gdb_test "help info bogus-gdb-command" "Undefined info command: \"bogus-gdb-comm
 # test help gotcha
 gdb_test "help gotcha" "Undefined command: \"gotcha\"\.  Try \"help\"\." "help gotcha"
 # test apropos regex
-gdb_test "apropos \\\(print\[\^ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle a signal"
+gdb_test "apropos \\\(print\[\^ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals"
 # test apropos >1 word string
-gdb_test "apropos handle a signal" "handle -- Specify how to handle a signal"
+gdb_test "apropos handle signal" "handle -- Specify how to handle signals"
 # test apropos apropos
 gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP"

Re: further improve "handle" help string

[Eli Zaretskii]

> Date: Thu, 23 Aug 2012 17:26:32 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: Eli Zaretskii <eliz@gnu.org>, Doug Evans <dje@google.com>,
>         gdb-patches@sourceware.org
> 
> On 08/15/2012 02:58 AM, Mike Frysinger wrote:
> > On Tuesday 14 August 2012 14:10:14 Eli Zaretskii wrote:
> >>> Date: Tue, 14 Aug 2012 10:34:10 -0700
> >>> From: Doug Evans <dje@google.com>
> >>> Cc: gdb-patches@sourceware.org, Eli Zaretskii <eliz@gnu.org>
> >>>
> >>> Ok with me, but I'd wait for Eli to check too.
> >>>
> >>> Thanks!
> >>
> >> I'm quite sure I already did.  Mike, is that right?
> > 
> > i've tweaked the signal wording, but i think the latest iteration covers 
> > everyone's concerns, so i'll merge this and we can fight over improving it 
> > further if need be ;)
> 
> I'll byte ;-)
> 
> I'd like to add a mention that you can specify more than one signal (though
> not complicate and distract the main body of the text with this).  I
> use this occasionally.  Text mostly borrowed from the sources.
> 
> Tested on amd64 Fedora 17.
> 
> (gdb) help handle
> Specify how to handle signals.
> Usage: handle SIGNAL [ACTIONS]
> Args are signals and actions to apply to those signals.
> If no actions are specified, the current settings for the specified signals
> will be displayed instead.
> 
> Symbolic signals (e.g. SIGSEGV) are recommended but numeric signals
> from 1-15 are allowed for compatibility with old versions of GDB.
> Numeric ranges may be specified with the form LOW-HIGH (e.g. 1-5).
> The special arg "all" is recognized to mean all signals except those
> used by the debugger, typically SIGTRAP and SIGINT.
> 
> Recognized actions include "stop", "nostop", "print", "noprint",
> "pass", "nopass", "ignore", or "noignore".
> Stop means reenter debugger if this signal happens (implies print).
> Print means print a message if this signal happens.
> Pass means let program see this signal; otherwise program doesn't know.
> Ignore is a synonym for nopass and noignore is a synonym for pass.
> Pass and Stop may be combined.
> 
> Multiple signals may be specified.  Signal numbers and signal names
> may be interspersed with actions, with the actions being performed for
> all signals cumulatively specified.
> (gdb) 

OK, thanks.

Re: further improve "handle" help string

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1756 bytes --]

On Thursday 23 August 2012 12:26:32 Pedro Alves wrote:
> Multiple signals may be specified.  Signal numbers and signal names
> may be interspersed with actions, with the actions being performed for
> all signals cumulatively specified.

this doesn't accurately describe real world behavior (but maybe that's a 
bug?).  this is why i avoided that aspect in the first place :(.

for example:
(gdb) handle SIGHUP SIGUSR1 SIGUSR2 SIGPWR
Signal        Stop      Print   Pass to program Description
SIGHUP        Yes       Yes     Yes             Hangup
SIGUSR1       Yes       Yes     Yes             User defined signal 1
SIGUSR2       Yes       Yes     Yes             User defined signal 2
SIGPWR        Yes       Yes     Yes             Power fail/restart
(gdb) handle SIGHUP SIGUSR1 SIGUSR2 nostop SIGPWR
Signal        Stop      Print   Pass to program Description
SIGHUP        No        Yes     Yes             Hangup
SIGUSR1       No        Yes     Yes             User defined signal 1
SIGUSR2       No        Yes     Yes             User defined signal 2
SIGPWR        Yes       Yes     Yes             Power fail/restart
(gdb) handle SIGPWR
Signal        Stop      Print   Pass to program Description
SIGPWR        Yes       Yes     Yes             Power fail/restart
(gdb) handle SIGHUP SIGUSR1 SIGUSR2 SIGPWR nostop
Signal        Stop      Print   Pass to program Description
SIGHUP        No        Yes     Yes             Hangup
SIGUSR1       No        Yes     Yes             User defined signal 1
SIGUSR2       No        Yes     Yes             User defined signal 2
SIGPWR        No        Yes     Yes             Power fail/restart

so saying "all signals cumulatively" is not how the code is behaving.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: further improve "handle" help string

[Pedro Alves]

On 08/23/2012 06:18 PM, Mike Frysinger wrote:
> On Thursday 23 August 2012 12:26:32 Pedro Alves wrote:
>> Multiple signals may be specified.  Signal numbers and signal names
>> may be interspersed with actions, with the actions being performed for
>> all signals cumulatively specified.
> 
> this doesn't accurately describe real world behavior (but maybe that's a 
> bug?).  this is why i avoided that aspect in the first place :(.

> for example:
> (gdb) handle SIGHUP SIGUSR1 SIGUSR2 SIGPWR
> Signal        Stop      Print   Pass to program Description
> SIGHUP        Yes       Yes     Yes             Hangup
> SIGUSR1       Yes       Yes     Yes             User defined signal 1
> SIGUSR2       Yes       Yes     Yes             User defined signal 2
> SIGPWR        Yes       Yes     Yes             Power fail/restart
> (gdb) handle SIGHUP SIGUSR1 SIGUSR2 nostop SIGPWR
> Signal        Stop      Print   Pass to program Description
> SIGHUP        No        Yes     Yes             Hangup
> SIGUSR1       No        Yes     Yes             User defined signal 1
> SIGUSR2       No        Yes     Yes             User defined signal 2
> SIGPWR        Yes       Yes     Yes             Power fail/restart
> (gdb) handle SIGPWR
> Signal        Stop      Print   Pass to program Description
> SIGPWR        Yes       Yes     Yes             Power fail/restart
> (gdb) handle SIGHUP SIGUSR1 SIGUSR2 SIGPWR nostop
> Signal        Stop      Print   Pass to program Description
> SIGHUP        No        Yes     Yes             Hangup
> SIGUSR1       No        Yes     Yes             User defined signal 1
> SIGUSR2       No        Yes     Yes             User defined signal 2
> SIGPWR        No        Yes     Yes             Power fail/restart
> 
> so saying "all signals cumulatively" is not how the code is behaving.

I had interpreted "cumulatively" as what the code is doing.  As in,
"all signals specified so far, when the action is parsed".  That's what
we see above.  Another e.g.,

(gdb) handle SIGHUP SIGUSR1 noprint SIGUSR2 SIGPWR nopass
Signal        Stop      Print   Pass to program Description
SIGHUP        No        No      No              Hangup
SIGUSR1       No        No      No              User defined signal 1
SIGUSR2       Yes       Yes     No              User defined signal 2
SIGPWR        Yes       Yes     No              Power fail/restart

IOW, I interpreted it as "noprint" (implies nostop) applying to all signals
accumulated that far (SIGHUP, SIGUSR1), and then "nopass" applying to
all accumulated signals at the end (all 4).

Consequently, this:

(gdb) handle SIGHUP SIGUSR1 pass SIGUSR2 SIGPWR nopass

Sets all signals to "nopass".

I don't frequently intersperse.  Rather, I do things like:

  handle SIGTRAP SIG34 SIG35 pass nostop noprint

I have already applied the patch, but if we want to change the
behavior, or the text, that's fine with me.

-- 
Pedro Alves

Re: [PATCH v3] gdb: improve usage strings

[Pedro Alves]

On 08/14/2012 06:34 PM, Doug Evans wrote:
>>
>>    c = add_com ("signal", class_run, signal_command, _("\
>> -Continue program giving it signal specified by the argument.\n\
>> -An argument of \"0\" means continue program without giving it a signal."));
>> +Continue program with the specified signal.\n\
>> +Usage: signal SIGNAL\n\
>> +The SIGNAL arugment is processed the same as the handle command.\n\
               ^^^^^^^^

Typo.

-- 
Pedro Alves

Re: [PATCH v3] gdb: improve usage strings

[Pedro Alves]

On 08/23/2012 12:11 PM, Pedro Alves wrote:
> On 08/14/2012 06:34 PM, Doug Evans wrote:
>>>
>>>    c = add_com ("signal", class_run, signal_command, _("\
>>> -Continue program giving it signal specified by the argument.\n\
>>> -An argument of \"0\" means continue program without giving it a signal."));
>>> +Continue program with the specified signal.\n\
>>> +Usage: signal SIGNAL\n\
>>> +The SIGNAL arugment is processed the same as the handle command.\n\
>                ^^^^^^^^
> 
> Typo.

Fixed.

2012-08-23  Pedro Alves  <palves@redhat.com>

	* infcmd.c (_initialize_infcmd) <signal command>: Fix typo in help
	string.

---

 gdb/infcmd.c |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index 8300182..9d43193 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3019,7 +3019,7 @@ all targets."));
   c = add_com ("signal", class_run, signal_command, _("\
 Continue program with the specified signal.\n\
 Usage: signal SIGNAL\n\
-The SIGNAL arugment is processed the same as the handle command.\n\
+The SIGNAL argument is processed the same as the handle command.\n\
 \n\
 An argument of \"0\" means continue the program without sending it a signal.\n\
 This is useful in cases where the program stopped because of a signal,\n\