Re: [pushed v5] gdb/manual: Introduce location specs

[Eli Zaretskii via Gdb-patches <gdb-patches@sourceware.org>]

> Date: Mon, 30 May 2022 15:44:59 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> >> -@item clear @var{location}
> >> -Delete any breakpoints set at the specified @var{location}.
> >> -@xref{Specify Location}, for the various forms of @var{location}; the
> >> -most useful ones are listed below:
> >> +@item clear @var{locspec}
> >> +Delete breakpoints with code locations that match @var{locspec}.
> >                                           ^^^^^^^^^^^^^^^^^^^^^^^^
> > "that are the result of resolving @var{locspec}"
> 
> That wouldn't actually be correct for this command.  For example:
> 
> (top-gdb) b gdb.c:29
> Breakpoint 4 at 0x555555641091: file /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c, line 29.
> (top-gdb) b *0x555555641092
> Breakpoint 5 at 0x555555641092: file /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c, line 29.
> (top-gdb) info breakpoints 
> Num     Type           Disp Enb Address            What
> 4       breakpoint     keep y   0x0000555555641091 in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:29
> 5       breakpoint     keep y   0x0000555555641092 in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:29
> 
> "gdb.c:29" resolves to address 0x0000555555641091, as can be seen when breakpoint 4 was
> created.  However, this:
> 
>  (top-gdb) clear gdb.c:29
>  Deleted breakpoints 4 5 
> 
> ... also deletes breakpoint 5.  GDB deleted it because its code location also matches
> the user input.

But then "matches locspec" is also inaccurate, and for the same
reason: they are two equivalent ways of describing the same process of
arriving at a code location from a location spec, or at least that's
how the text used them until now.

> This is explained just a bit below, here:
> 
>  @item clear @var{linenum}
>  @itemx clear @var{filename}:@var{linenum}
>  Delete any breakpoints set at or within the code of the specified
>  @var{linenum} of the specified @var{filename}.
>  @end table
> 
> Key here are "or within the code", and talking about the _specified_
> linenum/filename, not the resolved line/filename.

Then we need some change of text to the same effect where "clear
LOCSPEC" is described, right?

> >> +Here are examples of typical situations that result in a location spec
> >> +matching multiple concrete code locations in your program:
> > 
> > Should we also enumerate some situations where a location spec cannot
> > be completely resolved?  The text talks about that possibility, but
> > only in passing, with no details or practical examples.
> 
> I've added these examples under the multi-location examples:
> 
>  +And here are examples of typical situations that result in a location
>  +spec matching no code locations in your program at all:
>  +
>  +@itemize @bullet
>  +@item
>  +The location spec specifies a function name, and there are no
>  +functions in the program with that name.
>  +
>  +@item
>  +The location spec specifies a source file name, and there are no
>  +source files in the program with that name.
>  +
>  +@item
>  +The location spec specifies both a source file name and a source line
>  +number, and even though there are source files in the program that
>  +match the file name, none of those files has the specified line
>  +number.
>  +@end itemize

Shouldn't this mention explicitly the frequent situation where the
location specifies something in a yet-unloaded shared library?

> >> +register other than the program counter.  If @var{locspec} resolves to
> >> +an address in a different function from the one currently executing, the
> >> +results may be bizarre if the two functions expect different patterns
> >> +of arguments or of local variables.  For this reason, the @code{jump}
> >> +command requests confirmation if the specified line is not in the
> >> +function currently executing.                  ^^^^
> > 
> > "line" or "code location"?
> 
> I think it should say "jump address" here instead of "specified line", as this is
> not about a line the user input in the spec, but rather what address the locspec
> resolved to.

So perhaps it's better to say "if @var{locapsec} resolves to an
address that is not in the currently executing function".

>   /* See if we are trying to jump to another function.  */
>   fn = get_frame_function (get_current_frame ());
>   sfn = find_pc_function (sal.pc);
>   if (fn != NULL && sfn != fn)
>     {
>       if (!query (_("Line %d is not in `%s'.  Jump anyway? "), sal.line,
> 		  fn->print_name ()))
> 	{
> 	  error (_("Not confirmed."));
> 
> The query talks about "Line", but the check isn't comparing lines, this
> query will trigger even if you try to jump to a function without line info.
> That query's text should be fixed too, IMO.

Yes.

> >> +@item break-range @var{start-locspec}, @var{end-locspec}
> >> +Set a breakpoint for an address range given by @var{start-locspec} and
> >> +@var{end-locspec}, which are location specs.  @xref{Location
> >> +Specifications}, for a list of all the possible forms of location
> >> +specs.  If either @var{start-locspec} or @var{end-locspec} resolve to
> >> +multiple addresses in the program, then the command aborts with an
> >> +error without creating a breakpoint.  The breakpoint will stop
> >> +execution of the inferior whenever it executes an instruction at any
> >> +address within the specified range, including @var{start-locspec} and
> >> +@var{end-locspec}.
> > 
> > This deviates from the usual practice elsewhere, and talks about
> > location specs resolving into _addresses_ and not code locations.  is
> > that intentional and necessary?
> 
> Yes, it is intentional here, because the command is exactly about breaking
> on any address that falls within an address range.

Then I think this needs some additional text explaining that, or
qualifying the "location resolves to address" part.

Thanks.