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

Eli Zaretskii via Gdb-patches
2022-05-30T16:16:28Z

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