Show locno for 'multi location' breakpoint hit msg+conv var $_hit_bbnum $_hit_locno PR breakpoints/12464

This implements the request given in PR breakpoints/12464.

Before this patch, when a breakpoint that has multiple locations is reached,
GDB printed:
  Thread 1 "zeoes" hit Breakpoint 1, some_func () at somefunc1.c:5

This patch changes the message so that bkpt_print_id prints the precise
encountered breakpoint:
  Thread 1 "zeoes" hit Breakpoint 1.2, some_func () at somefunc1.c:5

In mi mode, bkpt_print_id also (optionally) prints a new table field "locno":
  locno is printed when the breakpoint hit has more than one location.
Note that according to the GDB user manual node 'GDB/MI Development and Front
Ends', it is ok to add new fields without changing the MI version.

Also, when a breakpoint is reached, the convenience variables
$_hit_bpnum and $_hit_locno are set to the encountered breakpoint number
and location number.

$_hit_bpnum and $_hit_locno can a.o. be used in the command list of a
breakpoint, to disable the specific encountered breakpoint, e.g.
   disable $_hit_bpnum.$_hit_locno

In case the breakpoint has only one location, $_hit_locno is set to
the value 1, so as to allow a command such as:
  disable $_hit_bpnum.$_hit_locno
to disable the breakpoint even when the breakpoint has only one location.

This also fixes a strange behaviour: when a breakpoint X has only
one location,
  enable|disable X.1
is accepted but transforms the breakpoint in a multiple locations
breakpoint having only one location.

The changes in RFA v4 handle the comments of Tom Tromey:
 - Changed convenience var names from $bkptno/$locno to
   $_hit_bpnum/$_hit_locno.
 - updated the tests and user manual accordingly.
   User manual also explictly describes that $_hit_locno is set to 1
   for a breakpoint with a single location.
 - The variable values are now set in bpstat_do_actions_1 so that
   they are set for silent breakpoints, and when several breakpoints
   are hit at the same time, that the variables are set to the printed
   breakpoint.

The changes in RFA v3 handle the additional comments of Eli:
 GDB/NEW:
  - Use max 80-column
  - Use 'code location' instead of 'location'.
  - Fix typo $bkpno
  - Ensure that disable $bkptno and disable $bkptno.$locno have
    each their explanation inthe example
  - Reworded the 'breakpoint-hit' paragraph.
 gdb.texinfo:
  - Use 'code location' instead of 'location'.
  - Add a note to clarify the distinction between $bkptno and $bpnum.
  - Use @kbd instead of examples with only one command.

Compared to RFA v1, the changes in v2 handle the comments given by
Keith Seitz and Eli Zaretskii:
  - Use %s for the result of paddress
  - Use bkptno_numopt_re instead of 2 different -re cases
  - use C@t{++}
  - Add index entries for $bkptno and $locno
  - Added an example for "locno" in the mi interface
  - Added examples in the Break command manual.

1 files changed, 91 insertions, 3 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index bb7b276..bababf3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -4375,9 +4375,75 @@ are operated on.
 @cindex latest breakpoint
 Breakpoints are set with the @code{break} command (abbreviated
 @code{b}).  The debugger convenience variable @samp{$bpnum} records the
-number of the breakpoint you've set most recently; see @ref{Convenience
-Vars,, Convenience Variables}, for a discussion of what you can do with
-convenience variables.
+number of the breakpoint you've set most recently:
+@smallexample
+(gdb) b main
+Breakpoint 1 at 0x11c6: file zeoes.c, line 24.
+(gdb) p $bpnum
+$1 = 1
+@end smallexample
+
+A breakpoint may be mapped to multiple code locations for example with
+inlined functions, Ada generics, C@t{++} templates or overloaded function names.
+@value{GDBN} then indicates the number of code locations in the breakpoint
+command output:
+@smallexample
+(gdb) b some_func
+Breakpoint 2 at 0x1179: some_func. (3 locations)
+(gdb) p $bpnum
+$2 = 2
+(gdb)
+@end smallexample
+
+@vindex $_hit_bpnum@r{, convenience variable}
+@vindex $_hit_locno@r{, convenience variable}
+When your program stops on a breakpoint, the convenience variables
+@samp{$_hit_bpnum} and @samp{$_hit_locno} are respectively set to the number of
+the encountered breakpoint and the number of the breakpoint's code location:
+@smallexample
+Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8
+8	  printf("some func\n");
+(gdb) p $_hit_bpnum
+$5 = 2
+(gdb) p $_hit_locno
+$6 = 1
+(gdb)
+@end smallexample
+
+Note that @samp{$_hit_bpnum} and @samp{$bpnum} are not equivalent:
+@samp{$_hit_bpnum} is set to the breakpoint number @b{last hit}, while
+@samp{$bpnum} is set to the breakpoint number @b{last set}.
+
+
+If the encountered breakpoint has only one code location, @samp{$_hit_locno}
+is set to 1:
+@smallexample
+Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24
+24	  if (argc > 1)
+(gdb) p $_hit_bpnum
+$3 = 1
+(gdb) p $_hit_locno
+$4 = 1
+(gdb)
+@end smallexample
+
+The @samp{$_hit_bpnum} and @samp{$_hit_locno} variables can typically be used
+in a breakpoint command list.
+(@pxref{Break Commands, ,Breakpoint Command Lists}).  For example, as
+part of the breakpoint command list, you can disable completely the
+encountered breakpoint using @kbd{disable $_hit_bpnum} or disable the
+specific encountered breakpoint location using
+@kbd{disable $_hit_bpnum.$_hit_locno}.
+If a breakpoint has only one location, @samp{$_hit_locno} is set to 1
+and the commands @kbd{disable $_hit_bpnum} and
+@kbd{disable $_hit_bpnum.$_hit_locno} both disable the breakpoint.
+
+You can also define aliases to easily disable the last hit location or
+last hit breakpoint:
+@smallexample
+(gdb) alias lld = disable $_hit_bpnum.$_hit_locno
+(gdb) alias lbd = disable $_hit_bpnum
+@end smallexample
 
 @table @code
 @item break @var{locspec}
@@ -5776,6 +5842,14 @@ Expressions}).
 Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
 disabled within a @var{command-list}.
 
+Inside a command list, you can use the command
+@kbd{disable $_hit_bpnum} to disable the encountered breakpoint.
+
+If your breakpoint has several code locations, the command
+@kbd{disable $_hit_bpnum.$_hit_locno} will disable the specific breakpoint
+code location encountered.  If the breakpoint has only one location,
+this command will disable the encountered breakpoint.
+
 You can use breakpoint commands to start your program up again.  Simply
 use the @code{continue} command, or @code{step}, or any other command
 that resumes execution.
@@ -32840,6 +32914,20 @@ line="13",arch="i386:x86_64"@}
 (gdb)
 @end smallexample
 
+For a @samp{breakpoint-hit} stopped reason, when the breakpoint
+encountered has multiple locations, the field @samp{bkptno} is
+followed by the field @samp{locno}.
+
+@smallexample
+-exec-continue
+^running
+(gdb)
+@@Hello world
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",locno="3",frame=@{
+func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
+line="13",arch="i386:x86_64"@}
+(gdb)
+@end smallexample
 
 @subheading The @code{-exec-finish} Command
 @findex -exec-finish