[PATCH v4] gdb/manual: Introduce location specs

[PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

The current "Specify Location" section of the GDB manual starts with:

 "Several @value{GDBN} commands accept arguments that specify a location
 of your program's code."

And then, such commands are documented as taking a "location"
argument.  For example, here's a representative subset:

 @item break @var{location}
 @item clear @var{location}
 @item until @var{location}
 @item list @var{location}
 @item edit @var{location}
 @itemx info line @var{location}
 @item info macros @var{location}
 @item trace @var{location}
 @item info scope @var{location}
 @item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}

The issue here is that "location" isn't really correct for most of
these commands.  Instead, the "location" argument is really a
placeholder that represent an umbrella term for all of the
"linespecs", "explicit location", and "address location" input
formats.  GDB parses these and then finds the actual code locations
(plural) in the program that match.  For example, a "location"
specified like "-function func" will actually match all the code
locations in the program that correspond to the address/file/lineno of
all the functions named "func" in all the loaded programs and shared
libraries of all the inferiors.  A location specified like "-function
func -label lab" matches all the addresses of C labels named "lab" in
all functions named "func".  Etc.

This means that several of the commands that claim they accept a
"location", actually end up working with multiple locations, and the
manual doesn't explain that all that well.  In some cases, the command
will work with all the resolved locations.  In other cases, the
command aborts with an error if the location specification resolves to
multiple locations in the program.  In other cases, GDB just
arbitrarily and silently picks whatever is the first resolved code
location (which sounds like should be improved).

To clarify this, I propose we use the term "Location Specification",
with shorthand "locaction spec", when we're talking about the user
input, the argument or arguments that is/are passed to commands to
instruct GDB how to find locations of interest.  This is distinct from
the actual code locations in the program, which are what GDB finds
based on the user-specified location spec.  Then use "location
specification or the shorter "location spec" thoughout instead of
"location" when we're talking about the user input.

Thus, this commit does the following:

- renames the "Specify Location" section of the manual to "Location
  Specifications".

- It then introduces the term "Location Specification", with
  corresponding shorthand "location spec", as something distinct from
  an actual code location in the program.  It explains what a concrete
  code location is.  It explains that a location specification may be
  incomplete, and that it matches multiple code locations in the
  program.  It gives examples.  Most examples were moved from the "Set
  Breaks" section, and a couple new ones that didn't exist yet were
  added.  I think it is better to have these centralized in this
  "Location Specification" section, since all the other commands that
  accept a location spec have an xref that points there.

- Goes through the manual, and where "@var{location}" was used for a
  command argument, updated it to say "@var{locspec}" instead.  At the
  same time, tweaks the description of the affected commands to
  describe what happens when the location spec resolves to more than
  one location.  Most commands just did not say anything about that.

  One command -- "maint agent -at @var{location}" -- currently says it
  accepts a "location", suggesting it can accept address and explicit
  locations too, but that's incorrect.  In reality, it only accepts
  linespecs, so fix it accordingly.

  One MI command -- "-trace-find line" -- currently says it accepts a
  "line specification", but it can accept address and explicit
  locations too, so fix it accordingly.

Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b
---
 gdb/doc/gdb.texinfo | 419 +++++++++++++++++++++++++-------------------
 gdb/doc/guile.texi  |   2 +-
 gdb/doc/python.texi |   5 +-
 3 files changed, 246 insertions(+), 180 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 68679982919..6deaad88d31 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2024,7 +2024,7 @@ func<int>()    func<float>()
 (@value{GDBP}) p 'func<
 @end smallexample
 
-When setting breakpoints however (@pxref{Specify Location}), you don't
+When setting breakpoints however (@pxref{Location Specifications}), you don't
 usually need to type a quote before the function name, because
 @value{GDBN} understands that you want to set a breakpoint on a
 function:
@@ -4343,17 +4343,19 @@ Vars,, Convenience Variables}, for a discussion of what you can do with
 convenience variables.
 
 @table @code
-@item break @var{location}
-Set a breakpoint at the given @var{location}, which can specify a
-function name, a line number, or an address of an instruction.
-(@xref{Specify Location}, for a list of all the possible ways to
-specify a @var{location}.)  The breakpoint will stop your program just
-before it executes any of the code in the specified @var{location}.
+@item break @var{locspec}
+Set a breakpoint at all the code locations in your program the given
+@var{locspec} resolves to.  @var{locspec} can specify a function name,
+a line number, an address of an instruction, and more.  @xref{Location
+Specifications}, for the various forms of @var{locspec}.  The
+breakpoint will stop your program just before it executes the
+instruction at the address of any of the breakpoint's locations.
 
-When using source languages that permit overloading of symbols, such as
-C@t{++}, a function name may refer to more than one possible place to break.
-@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
-that situation.
+When using source languages that permit overloading of symbols, such
+as C@t{++}, a function name may refer to more than one symbol, and
+thus more than one place to break.  @xref{Ambiguous
+Expressions,,Ambiguous Expressions}, for a discussion of that
+situation.
 
 It is also possible to insert a breakpoint that will stop the program
 only if a specific thread (@pxref{Thread-Specific Breakpoints})
@@ -4614,35 +4616,16 @@ the breakpoints are conditional, this is even useful
 
 @cindex multiple locations, breakpoints
 @cindex breakpoints, multiple locations
-It is possible that a breakpoint corresponds to several locations
-in your program.  Examples of this situation are:
-
-@itemize @bullet
-@item
-Multiple functions in the program may have the same name.
-
-@item
-For a C@t{++} constructor, the @value{NGCC} compiler generates several
-instances of the function body, used in different cases.
-
-@item
-For a C@t{++} template function, a given line in the function can
-correspond to any number of instantiations.
-
-@item
-For an inlined function, a given source line can correspond to
-several places where that function is inlined.
-@end itemize
-
-In all those cases, @value{GDBN} will insert a breakpoint at all
-the relevant locations.
+It is possible that a single logical breakpoint is set at several code
+locations in your program.  @xref{Location Specifications}, for
+examples.
 
 A breakpoint with multiple locations is displayed in the breakpoint
 table using several rows---one header row, followed by one row for
 each breakpoint location.  The header row has @samp{<MULTIPLE>} in the
-address column.  The rows for individual locations contain the actual
-addresses for locations, and show the functions to which those
-locations belong.  The number column for a location is of the form
+address column.  Each breakpoint location row contains the actual
+address, source file, source line and function of its code location.
+The number column for a breakpoint location is of the form
 @var{breakpoint-number}.@var{location-number}.
 
 For example:
@@ -4711,31 +4694,34 @@ differ from regular breakpoints.  You can set conditions or commands,
 enable and disable them and perform other breakpoint operations.
 
 @value{GDBN} provides some additional commands for controlling what
-happens when the @samp{break} command cannot resolve breakpoint
-address specification to an address:
+happens when the @samp{break} command cannot resolve the location spec
+to any code location in your program (@pxref{Location
+Specifications}):
 
 @kindex set breakpoint pending
 @kindex show breakpoint pending
 @table @code
 @item set breakpoint pending auto
-This is the default behavior.  When @value{GDBN} cannot find the breakpoint
-location, it queries you whether a pending breakpoint should be created.
+This is the default behavior.  When @value{GDBN} cannot resolve the
+location spec, it should create a pending breakpoint without
+confirmation.
 
 @item set breakpoint pending on
-This indicates that an unrecognized breakpoint location should automatically
-result in a pending breakpoint being created.
+This indicates that when @value{GDBN} cannot resolve the location
+spec, it should create a pending breakpoint without confirmation.
 
 @item set breakpoint pending off
-This indicates that pending breakpoints are not to be created.  Any
-unrecognized breakpoint location results in an error.  This setting does
-not affect any pending breakpoints previously created.
+This indicates that pending breakpoints are not to be created.  If
+@value{GDBN} cannot resolve the location spec, it aborts the
+breakpoint creation with an error.  This setting does not affect any
+pending breakpoints previously created.
 
 @item show breakpoint pending
 Show the current behavior setting for creating pending breakpoints.
 @end table
 
 The settings above only affect the @code{break} command and its
-variants.  Once breakpoint is set, it will be automatically updated
+variants.  Once a breakpoint is set, it will be automatically updated
 as shared libraries are loaded and unloaded.
 
 @cindex automatic hardware breakpoints
@@ -5455,10 +5441,10 @@ selected stack frame (@pxref{Selection, ,Selecting a Frame}).  When
 the innermost frame is selected, this is a good way to delete a
 breakpoint where your program just stopped.
 
-@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}.
+@xref{Location Specifications}, for the various forms of
+@var{locspec}; the most useful ones are listed below:
 
 @table @code
 @item clear @var{function}
@@ -5815,10 +5801,11 @@ everything without needing to communicate with @value{GDBN}.
 
 @table @code
 @kindex dprintf
-@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}]
-Whenever execution reaches @var{location}, print the values of one or
-more @var{expressions} under the control of the string @var{template}.
-To print several values, separate them with commas.
+@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}]
+Whenever execution reaches a code location in your program that
+matches @var{locspec}, print the values of one or more
+@var{expressions} under the control of the string @var{template}.  To
+print several values, separate them with commas.
 
 @item set dprintf-style @var{style}
 Set the dprintf output to be handled in one of several different
@@ -6313,11 +6300,13 @@ statement---not in terms of the actual machine code.
 instruction stepping, and hence is slower than @code{until} with an
 argument.
 
-@item until @var{location}
-@itemx u @var{location}
-Continue running your program until either the specified @var{location} is
-reached, or the current stack frame returns.  The location is any of
-the forms described in @ref{Specify Location}.
+@item until @var{locspec}
+@itemx u @var{locspec}
+Continue running your program until either a code location in your
+program that matches @var{locspec} is reached, or the current stack
+frame returns.
+@var{locspec} is any of the forms described in @ref{Location
+Specifications}.
 This form of the command uses temporary breakpoints, and
 hence is quicker than @code{until} without an argument.  The specified
 location is actually reached only if it is in the current frame.  This
@@ -6338,11 +6327,11 @@ invocations have returned.
 @end smallexample
 
 
-@kindex advance @var{location}
-@item advance @var{location}
-Continue running the program up to the given @var{location}.  An argument is
-required, which should be of one of the forms described in
-@ref{Specify Location}.
+@kindex advance @var{locspec}
+@item advance @var{locspec}
+Continue running the program up to the code location indicated by
+@var{locspec}.  An argument is required, which should be of one of the
+forms described in @ref{Location Specifications}.
 Execution will also stop upon exit from the current stack
 frame.  This command is similar to @code{until}, but @code{advance} will
 not skip over recursive function calls, and the target location doesn't
@@ -6442,7 +6431,7 @@ A more flexible solution is to execute @kbd{skip boring}.  This instructs
 @code{foo}.
 
 Functions may be skipped by providing either a function name, linespec
-(@pxref{Specify Location}), regular expression that matches the function's
+(@pxref{Location Specifications}), regular expression that matches the function's
 name, file name or a @code{glob}-style pattern that matches the file name.
 
 On Posix systems the form of the regular expression is
@@ -6479,7 +6468,7 @@ over when stepping.
 @itemx -fu @var{linespec}
 Functions named by @var{linespec} or the function containing the line
 named by @var{linespec} will be skipped over when stepping.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @item -rfunction @var{regexp}
 @itemx -rfu @var{regexp}
@@ -6512,7 +6501,7 @@ will be skipped.
 @item skip function @r{[}@var{linespec}@r{]}
 After running this command, the function named by @var{linespec} or the
 function containing the line named by @var{linespec} will be skipped over when
-stepping.  @xref{Specify Location}.
+stepping.  @xref{Location Specifications}.
 
 If you do not specify @var{linespec}, the function you're currently debugging
 will be skipped.
@@ -7141,11 +7130,10 @@ breakpoints on all threads, or on a particular thread.
 @cindex breakpoints and threads
 @cindex thread breakpoints
 @kindex break @dots{} thread @var{thread-id}
-@item break @var{location} thread @var{thread-id}
-@itemx break @var{location} thread @var{thread-id} if @dots{}
-@var{location} specifies source lines; there are several ways of
-writing them (@pxref{Specify Location}), but the effect is always to
-specify some source line.
+@item break @var{locspec} thread @var{thread-id}
+@itemx break @var{locspec} thread @var{thread-id} if @dots{}
+@var{locspec} specifies a code location or locations in your program.
+@xref{Location Specifications}, for details.
 
 Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
 to specify that you only want @value{GDBN} to stop the program when a
@@ -8945,7 +8933,7 @@ prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
 
 @menu
 * List::                        Printing source lines
-* Specify Location::            How to specify code locations
+* Location Specifications::     How to specify code locations
 * Edit::                        Editing source files
 * Search::                      Searching source files
 * Source Path::                 Specifying source directories
@@ -8961,7 +8949,7 @@ prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
 To print lines from a source file, use the @code{list} command
 (abbreviated @code{l}).  By default, ten lines are printed.
 There are several ways to specify what part of the file you want to
-print; see @ref{Specify Location}, for the full list.
+print; see @ref{Location Specifications}, for the full list.
 
 Here are the forms of the @code{list} command most commonly used:
 
@@ -9008,26 +8996,35 @@ than listing the same lines again.  An exception is made for an
 argument of @samp{-}; that argument is preserved in repetition so that
 each repetition moves up in the source file.
 
-In general, the @code{list} command expects you to supply zero, one or two
-@dfn{locations}.  Locations specify source lines; there are several ways
-of writing them (@pxref{Specify Location}), but the effect is always
-to specify some source line.
+In general, the @code{list} command expects you to supply zero, one or
+two location specs.  These location specs are interpreted to specify
+source code lines; there are several ways of writing them
+(@pxref{Location Specifications}), but the effect is always to specify
+some source lines to display.
 
 Here is a complete description of the possible arguments for @code{list}:
 
 @table @code
-@item list @var{location}
-Print lines centered around the line specified by @var{location}.
+@item list @var{locspec}
+Print lines centered around the line or lines that @var{locspec}
+resolves to.
 
 @item list @var{first},@var{last}
 Print lines from @var{first} to @var{last}.  Both arguments are
-locations.  When a @code{list} command has two locations, and the
-source file of the second location is omitted, this refers to
-the same source file as the first location.
+location specs.  When a @code{list} command has two location specs,
+and the source file of the second location spec is omitted, this
+refers to the same source file as the first location spec.  If either
+@var{first} or @var{last} resolve to more than one source line in the
+program, then the list command will show the list of resolved source
+lines and does not proceed with the source code listing.
 
 @item list ,@var{last}
 Print lines ending with @var{last}.
 
+Likewise, if @var{last} resolves to more than one source line in the
+program, then the list command will print the list of resolved source
+lines and does not proceed with the source code listing.
+
 @item list @var{first},
 Print lines starting with @var{first}.
 
@@ -9041,17 +9038,75 @@ Print lines just before the lines last printed.
 As described in the preceding table.
 @end table
 
-@node Specify Location
-@section Specifying a Location
+@node Location Specifications
+@section Location Specifications
 @cindex specifying location
-@cindex location
+@cindex location spec
+@cindex locspec
 @cindex source location
+@cindex code location
 
 Several @value{GDBN} commands accept arguments that specify a location
-of your program's code.  Since @value{GDBN} is a source-level
-debugger, a location usually specifies some line in the source code.
-Locations may be specified using three different formats:
-linespec locations, explicit locations, or address locations.
+or locations of your program's code.  Since @value{GDBN} is a
+source-level debugger, a location specification usually indicates some
+line in the source code, but it can also indicate a function name, an
+address, a label, and more.
+
+A concrete code location in your program is uniquely identifiable by a
+set of logical attributes.  Typically, a line number, the source file
+the line belongs to, the fully-qualified and prototyped function it is
+defined in, and an instruction address.  Because each inferior has its
+own address space, also an inferior number.
+
+On the other hand, a @dfn{location specification} (a.k.a.@: location
+spec) is a way to find or refer to the concrete code locations in the
+program.  A location spec serves as a blueprint, and @value{GDBN}
+resolves the spec to actual code locations in your program by using
+the source and debug information.
+
+The location spec may be incomplete, and @value{GDBN} will do its best
+to find all the locations in the program that match it.  For example,
+a location spec may just indicate a line number and a source filename
+with no directory components, or even not specify a filename at all,
+just a line number.  Or, the spec may indicate a simple function name
+instead of a fully-qualified and prototyped function name (e.g.,
+@code{func} instead of @code{A::func(int)}).
+
+You may not have debug info for some of the instructions in the
+program, so a resolved location that itself points to such code will
+be incomplete and be missing some attributes, such as the source file
+and line number, and sometimes even function names.  Such an
+incomplete location is only usable in contexts that work with
+addresses and/or function names.  Some commands can only work with
+complete locations.
+
+Here are examples of typical situations that result in a location spec
+matching multiple concrete code locations in your program:
+
+@itemize @bullet
+@item
+The location spec specifies a function name, and multiple functions in
+the program may have the same name.
+
+@item
+The location spec specifies a file name, and multiple files in the
+program share the same name.
+
+@item
+For a C@t{++} constructor, the @value{NGCC} compiler generates several
+instances of the function body, used in different cases.
+
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to several
+places where that function is inlined.
+@end itemize
+
+Locations may be specified using three different formats: linespec
+locations, explicit locations, or address locations.
 
 @menu
 * Linespec Locations::                Linespec locations
@@ -9270,12 +9325,17 @@ Alternatively, there are several ways to specify what part of the file you
 want to print if you want to see other parts of the program:
 
 @table @code
-@item edit @var{location}
-Edit the source file specified by @code{location}.  Editing starts at
-that @var{location}, e.g., at the specified source line of the
-specified file.  @xref{Specify Location}, for all the possible forms
-of the @var{location} argument; here are the forms of the @code{edit}
-command most commonly used:
+@item edit @var{locspec}
+Edit the source file specified by @code{locspec}.  Editing starts at
+the source file and source line @code{locspec} resolves to.
+@xref{Location Specifications}, for all the possible forms of the
+@var{locspec} argument.
+
+If @code{locspec} resolves to more than one source line in your
+program, then the command prints the list of resolved source lines and
+does not proceed with the editing.
+
+Here are the forms of the @code{edit} command most commonly used:
 
 @table @code
 @item edit @var{number}
@@ -9655,11 +9715,12 @@ well as hex.
 @table @code
 @kindex info line
 @item info line
-@itemx info line @var{location}
+@itemx info line @var{locspec}
 Print the starting and ending addresses of the compiled code for
-source line @var{location}.  You can specify source lines in any of
-the ways documented in @ref{Specify Location}.  With no @var{location}
-information about the current source line is printed.
+source lines that @var{locspec} resolves to.  @xref{Location
+Specifications}, for the various forms of @var{locspec}.
+With no @var{locspec}, information about the current source line is
+printed.
 @end table
 
 For example, we can use @code{info line} to discover the location of
@@ -9674,8 +9735,9 @@ Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \
 
 @noindent
 @cindex code address and its source line
-We can also inquire (using @code{*@var{addr}} as the form for
-@var{location}) what source line covers a particular address:
+We can also inquire, using @code{*@var{addr}} as the form for
+@var{locspec}, what source line covers a particular address
+@var{addr}:
 @smallexample
 (@value{GDBP}) info line *0x63ff
 Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
@@ -9883,10 +9945,10 @@ Dump of assembler code from 0x400281 to 0x40028b:
 End of assembler dump.
 @end smallexample
 
-Addresses cannot be specified as a location (@pxref{Specify Location}).
-So, for example, if you want to disassemble function @code{bar}
-in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
-and not @samp{disassemble foo.c:bar}.
+Addresses cannot be specified with a location spec (@pxref{Location
+Specifications}).  So, for example, if you want to disassemble
+function @code{bar} in file @file{foo.c}, you must type
+@samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}.
 
 Some architectures have more than one commonly-used set of instruction
 mnemonics or other syntax.
@@ -14172,10 +14234,10 @@ argument processing and the beginning of @var{macro} for non C-like macros where
 the macro may begin with a hyphen.
 
 @kindex info macros
-@item info macros @var{location}
-Show all macro definitions that are in effect at the location specified
-by @var{location},  and describe the source location or compiler
-command-line where those definitions were established.
+@item info macros @var{locspec}
+Show all macro definitions that are in effect at the source line
+@var{locspec} resolves to, and describe the source location
+or compiler command-line where those definitions were established.
 
 @kindex macro define
 @cindex user-defined macros
@@ -14477,10 +14539,10 @@ conditions and actions.
 @table @code
 @cindex set tracepoint
 @kindex trace
-@item trace @var{location}
+@item trace @var{locspec}
 The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be any valid location.
-@xref{Specify Location}.  The @code{trace} command defines a tracepoint,
+Its argument @var{locspec} can be any valid location specification.
+@xref{Location Specifications}.  The @code{trace} command defines a tracepoint,
 which is a point in the target program where the debugger will briefly stop,
 collect some data, and then allow the program to continue.  Setting a tracepoint
 or changing its actions takes effect immediately if the remote stub
@@ -14516,14 +14578,14 @@ Here are some examples of using the @code{trace} command:
 @noindent
 You can abbreviate @code{trace} as @code{tr}.
 
-@item trace @var{location} if @var{cond}
+@item trace @var{locspec} if @var{cond}
 Set a tracepoint with condition @var{cond}; evaluate the expression
 @var{cond} each time the tracepoint is reached, and collect data only
 if the value is nonzero---that is, if @var{cond} evaluates as true.
 @xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
 information on tracepoint conditions.
 
-@item ftrace @var{location} [ if @var{cond} ]
+@item ftrace @var{locspec} [ if @var{cond} ]
 @cindex set fast tracepoint
 @cindex fast tracepoints, setting
 @kindex ftrace
@@ -14555,20 +14617,21 @@ sudo sysctl -w vm.mmap_min_addr=32768
 which sets the low address to 32K, which leaves plenty of room for
 trampolines.  The minimum address should be set to a page boundary.
 
-@item strace @var{location} [ if @var{cond} ]
+@item strace [@var{locspec} | -m @var{marker}] [ if @var{cond} ]
 @cindex set static tracepoint
 @cindex static tracepoints, setting
 @cindex probe static tracepoint marker
 @kindex strace
 The @code{strace} command sets a static tracepoint.  For targets that
 support it, setting a static tracepoint probes a static
-instrumentation point, or marker, found at @var{location}.  It may not
-be possible to set a static tracepoint at the desired location, in
-which case the command will exit with an explanatory message.
+instrumentation point, or marker, found at the code locations that match
+@var{locspec}.  It may not be possible to set a static tracepoint at
+the desired location, in which case the command will exit with an
+explanatory message.
 
 @value{GDBN} handles arguments to @code{strace} exactly as for
 @code{trace}, with the addition that the user can also specify
-@code{-m @var{marker}} as @var{location}.  This probes the marker
+@code{-m @var{marker}} instead of a location spec.  This probes the marker
 identified by the @var{marker} string identifier.  This identifier
 depends on the static tracepoint backend library your program is
 using.  You can find all the marker identifiers in the @samp{ID} field
@@ -17439,9 +17502,9 @@ peculiarities and holes to be aware of.
 
 @itemize @bullet
 @item
-Linespecs (@pxref{Specify Location}) are never relative to the current
-crate.  Instead, they act as if there were a global namespace of
-crates, somewhat similar to the way @code{extern crate} behaves.
+Linespecs (@pxref{Location Specifications}) are never relative to the
+current crate.  Instead, they act as if there were a global namespace
+of crates, somewhat similar to the way @code{extern crate} behaves.
 
 That is, if @value{GDBN} is stopped at a breakpoint in a function in
 crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
@@ -18762,15 +18825,14 @@ information.
 
 Flags @code{-c} and @code{-s} cannot be used together.
 
-@item break @var{location} task @var{taskno}
-@itemx break @var{location} task @var{taskno} if @dots{}
+@item break @var{locspec} task @var{taskno}
+@itemx break @var{locspec} task @var{taskno} if @dots{}
 @cindex breakpoints and tasks, in Ada
 @cindex task breakpoints, in Ada
 @kindex break @dots{} task @var{taskno}@r{ (Ada)}
 These commands are like the @code{break @dots{} thread @dots{}}
-command (@pxref{Thread Stops}).  The
-@var{location} argument specifies source lines, as described
-in @ref{Specify Location}.
+command (@pxref{Thread Stops}).  @xref{Location Specifications}, for
+the various forms of @var{locspec}.
 
 Use the qualifier @samp{task @var{taskno}} with a breakpoint command
 to specify that you only want @value{GDBN} to stop the program when a
@@ -19531,12 +19593,10 @@ These commands can be used to enable or disable type printers.
 
 @kindex info scope
 @cindex local variables
-@item info scope @var{location}
-List all the variables local to a particular scope.  This command
-accepts a @var{location} argument---a function name, a source line, or
-an address preceded by a @samp{*}, and prints all the variables local
-to the scope defined by that location.  (@xref{Specify Location}, for
-details about supported forms of @var{location}.)  For example:
+@item info scope @var{locspec}
+List all the variables local to the lexical scope @var{locspec}
+resolves to.  @xref{Location Specifications}, for details about
+supported forms of @var{locspec}.  For example:
 
 @smallexample
 (@value{GDBP}) @b{info scope command_line_handler}
@@ -20124,23 +20184,26 @@ an address of your own choosing, with the following commands:
 @table @code
 @kindex jump
 @kindex j @r{(@code{jump})}
-@item jump @var{location}
-@itemx j @var{location}
-Resume execution at @var{location}.  Execution stops again immediately
-if there is a breakpoint there.  @xref{Specify Location}, for a description
-of the different forms of @var{location}.  It is common
-practice to use the @code{tbreak} command in conjunction with
-@code{jump}.  @xref{Set Breaks, ,Setting Breakpoints}.
+@item jump @var{locspec}
+@itemx j @var{locspec}
+Resume execution at the address @var{locspec} resolves to.
+@xref{Location Specifications}, for a description of the different
+forms of @var{locspec}.  If @var{locspec} resolves to more than one
+address, the command aborts before jumping.
+Execution stops again immediately if there is a breakpoint there.  It
+is common practice to use the @code{tbreak} command in conjunction
+with @code{jump}.  @xref{Set Breaks, ,Setting Breakpoints}.
 
 The @code{jump} command does not change the current stack frame, or
 the stack pointer, or the contents of any memory location or any
-register other than the program counter.  If @var{location} is 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.  However, even bizarre results are predictable if you are
-well acquainted with the machine-language code of your program.
+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.  However, even bizarre results are
+predictable if you are well acquainted with the machine-language code
+of your program.
 @end table
 
 On many systems, you can get much the same effect as the @code{jump}
@@ -25365,15 +25428,16 @@ use the @code{break-range} command.
 
 @table @code
 @kindex break-range
-@item break-range @var{start-location}, @var{end-location}
-Set a breakpoint for an address range given by
-@var{start-location} and @var{end-location}, which can specify a function name,
-a line number, an offset of lines from the current line or from the start
-location, or an address of an instruction (see @ref{Specify Location},
-for a list of all the possible ways to specify a @var{location}.)
-The breakpoint will stop execution of the inferior whenever it
-executes an instruction at any address within the specified range,
-(including @var{start-location} and @var{end-location}.)
+@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}.
 
 @kindex set powerpc
 @item set powerpc soft-float
@@ -31192,11 +31256,11 @@ N.A.
 @smallexample
  -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ]
     [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ]
-    [ -p @var{thread-id} ] [ @var{location} ]
+    [ -p @var{thread-id} ] [ @var{locspec} ]
 @end smallexample
 
 @noindent
-If specified, @var{location}, can be one of:
+If specified, @var{locspec}, can be one of:
 
 @table @var
 @item linespec location
@@ -31235,10 +31299,10 @@ Insert a temporary breakpoint.
 @item -h
 Insert a hardware breakpoint.
 @item -f
-If @var{location} cannot be parsed (for example if it
+If @var{locspec} cannot be parsed (for example if it
 refers to unknown files or functions), create a pending
 breakpoint. Without this flag, @value{GDBN} will report
-an error, and won't create a breakpoint, if @var{location}
+an error, and won't create a breakpoint, if @var{locspec}
 cannot be parsed.
 @item -d
 Create a disabled breakpoint.
@@ -31320,12 +31384,12 @@ times="0"@}]@}
 @smallexample
  -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ]
     [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ]
-    [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
+    [ -p @var{thread-id} ] [ @var{locspec} ] [ @var{format} ]
     [ @var{argument} ]
 @end smallexample
 
 @noindent
-If supplied, @var{location} and @code{--qualified} may be specified
+If supplied, @var{locspec} and @code{--qualified} may be specified
 the same way as for the @code{-break-insert} command.
 @xref{-break-insert}.
 
@@ -31335,10 +31399,10 @@ The possible optional parameters of this command are:
 @item -t
 Insert a temporary breakpoint.
 @item -f
-If @var{location} cannot be parsed (for example, if it
+If @var{locspec} cannot be parsed (for example, if it
 refers to unknown files or functions), create a pending
 breakpoint.  Without this flag, @value{GDBN} will report
-an error, and won't create a breakpoint, if @var{location}
+an error, and won't create a breakpoint, if @var{locspec}
 cannot be parsed.
 @item -d
 Create a disabled breakpoint.
@@ -32551,12 +32615,12 @@ fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@}
 @subsubheading Synopsis
 
 @smallexample
- -exec-jump @var{location}
+ -exec-jump @var{locspec}
 @end smallexample
 
 Resumes execution of the inferior program at the location specified by
-parameter.  @xref{Specify Location}, for a description of the
-different forms of @var{location}.
+the parameter.  @xref{Location Specifications}, for a description of
+the different forms of @var{locspec}.
 
 @subsubheading @value{GDBN} Command
 
@@ -32870,13 +32934,13 @@ fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
 @subsubheading Synopsis
 
 @smallexample
- -exec-until [ @var{location} ]
+ -exec-until [ @var{locspec} ]
 @end smallexample
 
-Executes the inferior until the @var{location} specified in the
-argument is reached.  If there is no argument, the inferior executes
-until a source line greater than the current one is reached.  The
-reason for stopping in this case will be @samp{location-reached}.
+Executes the inferior until the address @var{locspec} resolves to.  If
+there is no argument, the inferior executes until a source line
+greater than the current one is reached.  The reason for stopping in
+this case will be @samp{location-reached}.
 
 @subsubheading @value{GDBN} Command
 
@@ -34935,7 +34999,7 @@ next trace frame that corresponds to a tracepoint at an address outside
 the specified range.  Both bounds are considered to be inside the range.
 
 @item line
-Line specification is required as parameter.  @xref{Specify Location}.
+Location specification is required as parameter.  @xref{Location Specifications}.
 Finds next trace frame that corresponds to a tracepoint at
 the specified location.
 
@@ -39438,8 +39502,8 @@ messages, see @ref{Debugging Output}.)
 @table @code
 @kindex maint agent
 @kindex maint agent-eval
-@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}
-@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression}
+@item maint agent @r{[}-at @var{linespec}@r{,}@r{]} @var{expression}
+@itemx maint agent-eval @r{[}-at @var{linespec}@r{,}@r{]} @var{expression}
 Translate the given @var{expression} into remote agent bytecodes.
 This command is useful for debugging the Agent Expression mechanism
 (@pxref{Agent Expressions}).  The @samp{agent} version produces an
@@ -39450,7 +39514,8 @@ globb} will include bytecodes to record four bytes of memory at each
 of the addresses of @code{globa} and @code{globb}, while discarding
 the result of the addition, while an evaluation expression will do the
 addition and return the sum.
-If @code{-at} is given, generate remote agent bytecode for @var{location}.
+If @code{-at} is given, generate remote agent bytecode for all
+the addresses @var{linespec} resolves to (@pxref{Linespec Locations}).
 If not, generate remote agent bytecode for current frame PC address.
 
 @kindex maint agent-printf
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 3c517230929..63916eed181 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1965,7 +1965,7 @@ This constant means that filename completion should be performed.
 
 @item COMPLETE_LOCATION
 This constant means that location completion should be done.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @item COMPLETE_COMMAND
 This constant means that completion should examine @value{GDBN}
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index cb5283e03c0..f933c7d30c9 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -577,7 +577,8 @@ either @code{None} or another tuple that contains all the locations
 that match the expression represented as @code{gdb.Symtab_and_line}
 objects (@pxref{Symbol Tables In Python}).  If @var{expression} is
 provided, it is decoded the way that @value{GDBN}'s inbuilt
-@code{break} or @code{edit} commands do (@pxref{Specify Location}).
+@code{break} or @code{edit} commands do (@pxref{Location
+Specifications}).
 @end defun
 
 @defun gdb.prompt_hook (current_prompt)
@@ -4186,7 +4187,7 @@ This constant means that filename completion should be performed.
 @vindex COMPLETE_LOCATION
 @item gdb.COMPLETE_LOCATION
 This constant means that location completion should be done.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @vindex COMPLETE_COMMAND
 @item gdb.COMPLETE_COMMAND

base-commit: fbcda577011d73fdcf1ebf86160b6fc8ddd95299
-- 
2.36.0

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> From: Pedro Alves <pedro@palves.net>
> Date: Thu, 26 May 2022 20:42:50 +0100
> 
>  gdb/doc/gdb.texinfo | 419 +++++++++++++++++++++++++-------------------
>  gdb/doc/guile.texi  |   2 +-
>  gdb/doc/python.texi |   5 +-
>  3 files changed, 246 insertions(+), 180 deletions(-)

Thanks.  The changes in descriptions of the commands that accept
location specs seem more-or-less okay, although I didn't yet read all
of them  in detail (so please don't push just yet).  The "Location
Specifications" section, OTOH, needs more work.  I didn't yet make up
my mind regarding what exactly should it look like, and one reason why
I'm not there yet is that your text doesn't seem to describe the "code
location" in full:

  > +A concrete code location in your program is uniquely identifiable by a
  > +set of logical attributes.  Typically, a line number, the source file
  > +the line belongs to, the fully-qualified and prototyped function it is
  > +defined in, and an instruction address.  Because each inferior has its
  > +own address space, also an inferior number.

The "typically" part and the overall style seem to say that this is
not the exhaustive list of all the attributes of a code location, just
a general idea.  Can you please present a full exhaustive list of the
attributes of a code location?

And another question: does the process of resolving a location spec to
obtain the corresponding code locations involve only filling in of the
attributes that were omitted from the spec, or does it also produce
attributes that can _never_ be part of the location spec?  IOW, can
the user type a location spec which will yield a code location that is
100% identical to the input spec?

IMO, the best way to describe "location specifications", "code
locations", and how the former leads to the latter depends on the
answers to those two questions.

Thanks.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 15:16, Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Date: Thu, 26 May 2022 20:42:50 +0100
>>
>>  gdb/doc/gdb.texinfo | 419 +++++++++++++++++++++++++-------------------
>>  gdb/doc/guile.texi  |   2 +-
>>  gdb/doc/python.texi |   5 +-
>>  3 files changed, 246 insertions(+), 180 deletions(-)
> 
> Thanks.  The changes in descriptions of the commands that accept
> location specs seem more-or-less okay, although I didn't yet read all
> of them  in detail (so please don't push just yet).  The "Location
> Specifications" section, OTOH, needs more work.  I didn't yet make up
> my mind regarding what exactly should it look like, and one reason why
> I'm not there yet is that your text doesn't seem to describe the "code
> location" in full:
> 
>   > +A concrete code location in your program is uniquely identifiable by a
>   > +set of logical attributes.  Typically, a line number, the source file
>   > +the line belongs to, the fully-qualified and prototyped function it is
>   > +defined in, and an instruction address.  Because each inferior has its
>   > +own address space, also an inferior number.
> 
> The "typically" part and the overall style seem to say that this is
> not the exhaustive list of all the attributes of a code location, just
> a general idea.  Can you please present a full exhaustive list of the
> attributes of a code location?

I meant to remove the "typically", and forgot it, sorry.  It is not
supposed to be there.

> 
> And another question: does the process of resolving a location spec to
> obtain the corresponding code locations involve only filling in of the
> attributes that were omitted from the spec, or does it also produce
> attributes that can _never_ be part of the location spec?  IOW, can
> the user type a location spec which will yield a code location that is
> 100% identical to the input spec?

Currently there's no way to explicitly specify the inferior with
any format of location specifications.  So if you do "b func", and you
have multiple inferiors, GDB will find code locations for "func" in all
the inferiors.  All the other attributes you can explicitly specify.
Not sure whether that answers your question.  I am not sure what you
mean by "100% identical".  A spec can never the identical to the actual
thing, the same way a cake recipe can never be identical to a cake, for
they are things of different nature.  It can only be that the actual
thing complies with or follows the spec.

> 
> IMO, the best way to describe "location specifications", "code
> locations", and how the former leads to the latter depends on the
> answers to those two questions.
> 
> Thanks.
> 

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 16:04:32 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> >   > +A concrete code location in your program is uniquely identifiable by a
> >   > +set of logical attributes.  Typically, a line number, the source file
> >   > +the line belongs to, the fully-qualified and prototyped function it is
> >   > +defined in, and an instruction address.  Because each inferior has its
> >   > +own address space, also an inferior number.
> > 
> > The "typically" part and the overall style seem to say that this is
> > not the exhaustive list of all the attributes of a code location, just
> > a general idea.  Can you please present a full exhaustive list of the
> > attributes of a code location?
> 
> I meant to remove the "typically", and forgot it, sorry.  It is not
> supposed to be there.

OK, so I take it the full list is:

  . absolute file name of the source
  . line number in the source file
  . fully-qualified and prototyped function
  . address
  . inferior number

> > And another question: does the process of resolving a location spec to
> > obtain the corresponding code locations involve only filling in of the
> > attributes that were omitted from the spec, or does it also produce
> > attributes that can _never_ be part of the location spec?  IOW, can
> > the user type a location spec which will yield a code location that is
> > 100% identical to the input spec?
> 
> Currently there's no way to explicitly specify the inferior with
> any format of location specifications.  So if you do "b func", and you
> have multiple inferiors, GDB will find code locations for "func" in all
> the inferiors.  All the other attributes you can explicitly specify.
> Not sure whether that answers your question.

I think it does, but:

>                                              I am not sure what you
> mean by "100% identical".  A spec can never the identical to the actual
> thing, the same way a cake recipe can never be identical to a cake, for
> they are things of different nature.  It can only be that the actual
> thing complies with or follows the spec.

I thought you just explained above that, when there's only one
inferior, the user can give a location spec which will resolve to a
code location that has exactly the same attributes as the spec?  IOW,
in this case the "resolution" of the spec produces a "thing" that to
the user looks exactly the same as the input spec?

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 16:52, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 16:04:32 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>>   > +A concrete code location in your program is uniquely identifiable by a
>>>   > +set of logical attributes.  Typically, a line number, the source file
>>>   > +the line belongs to, the fully-qualified and prototyped function it is
>>>   > +defined in, and an instruction address.  Because each inferior has its
>>>   > +own address space, also an inferior number.
>>>
>>> The "typically" part and the overall style seem to say that this is
>>> not the exhaustive list of all the attributes of a code location, just
>>> a general idea.  Can you please present a full exhaustive list of the
>>> attributes of a code location?
>>
>> I meant to remove the "typically", and forgot it, sorry.  It is not
>> supposed to be there.
> 
> OK, so I take it the full list is:
> 
>   . absolute file name of the source
>   . line number in the source file
>   . fully-qualified and prototyped function
>   . address
>   . inferior number

Yes.  Well, except "absolute" in the file name.  The file names in the
debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
and we may not be able to find the source file in the filesystem, so the
path the debug info tells us is all we get.

> 
>>> And another question: does the process of resolving a location spec to
>>> obtain the corresponding code locations involve only filling in of the
>>> attributes that were omitted from the spec, or does it also produce
>>> attributes that can _never_ be part of the location spec?  IOW, can
>>> the user type a location spec which will yield a code location that is
>>> 100% identical to the input spec?
>>
>> Currently there's no way to explicitly specify the inferior with
>> any format of location specifications.  So if you do "b func", and you
>> have multiple inferiors, GDB will find code locations for "func" in all
>> the inferiors.  All the other attributes you can explicitly specify.
>> Not sure whether that answers your question.
> 
> I think it does, but:
> 
>>                                              I am not sure what you
>> mean by "100% identical".  A spec can never the identical to the actual
>> thing, the same way a cake recipe can never be identical to a cake, for
>> they are things of different nature.  It can only be that the actual
>> thing complies with or follows the spec.
> 
> I thought you just explained above that, when there's only one
> inferior, the user can give a location spec which will resolve to a
> code location that has exactly the same attributes as the spec?  IOW,
> in this case the "resolution" of the spec produces a "thing" that to
> the user looks exactly the same as the input spec?

When you specify a function name, you can't specify an address
at the same time, for example.  There's no format that allows that.
So if you specify a function, you end up with code location that has
an address, but you didn't specify the address.  Conversely, when you
specify an address, gdb finds the source/line for the address if available,
as well as the function.

So you can't pass the whole set of attributes at once, some combinations can't
be specified, or are incompatible/ignored.

And then GDB knows more about the code locations than that set of attributes,
of course.  GDB knows the architecture of the instruction the location points 
at, for example.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 18:11:04 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> >   . absolute file name of the source
> >   . line number in the source file
> >   . fully-qualified and prototyped function
> >   . address
> >   . inferior number
> 
> Yes.  Well, except "absolute" in the file name.  The file names in the
> debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
> and we may not be able to find the source file in the filesystem, so the
> path the debug info tells us is all we get.

Then the directory should also be part of the attributes, no?

> >>                                              I am not sure what you
> >> mean by "100% identical".  A spec can never the identical to the actual
> >> thing, the same way a cake recipe can never be identical to a cake, for
> >> they are things of different nature.  It can only be that the actual
> >> thing complies with or follows the spec.
> > 
> > I thought you just explained above that, when there's only one
> > inferior, the user can give a location spec which will resolve to a
> > code location that has exactly the same attributes as the spec?  IOW,
> > in this case the "resolution" of the spec produces a "thing" that to
> > the user looks exactly the same as the input spec?
> 
> When you specify a function name, you can't specify an address
> at the same time, for example.  There's no format that allows that.
> So if you specify a function, you end up with code location that has
> an address, but you didn't specify the address.  Conversely, when you
> specify an address, gdb finds the source/line for the address if available,
> as well as the function.

That's understood, and it not important for what I have in mind.  The
important point is that the user can potentially specify every
attribute of a code location, even if some combinations cannot be
used.

> And then GDB knows more about the code locations than that set of attributes,
> of course.  GDB knows the architecture of the instruction the location points 
> at, for example.

Is that exposed to the user somewhere?  I'm only interested in what is
shown to the user and/or what has user-level consequences.  Internal
attributes that the user doesn't have to know about are out of scope
of this issue.

Thanks.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 18:31, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 18:11:04 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>>   . absolute file name of the source
>>>   . line number in the source file
>>>   . fully-qualified and prototyped function
>>>   . address
>>>   . inferior number
>>
>> Yes.  Well, except "absolute" in the file name.  The file names in the
>> debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
>> and we may not be able to find the source file in the filesystem, so the
>> path the debug info tells us is all we get.
> 
> Then the directory should also be part of the attributes, no?

I thought that in GNU terminology, "file name" already included the directory?
ISTR you saying that we shouldn't use "path" to describe directories sometime ago,
for example.  Maybe I'm misremembering it.

The text I wrote in v4 purposely says "the source file the line belongs to"
which avoids going into that detail.

> 
>>>>                                              I am not sure what you
>>>> mean by "100% identical".  A spec can never the identical to the actual
>>>> thing, the same way a cake recipe can never be identical to a cake, for
>>>> they are things of different nature.  It can only be that the actual
>>>> thing complies with or follows the spec.
>>>
>>> I thought you just explained above that, when there's only one
>>> inferior, the user can give a location spec which will resolve to a
>>> code location that has exactly the same attributes as the spec?  IOW,
>>> in this case the "resolution" of the spec produces a "thing" that to
>>> the user looks exactly the same as the input spec?
>>
>> When you specify a function name, you can't specify an address
>> at the same time, for example.  There's no format that allows that.
>> So if you specify a function, you end up with code location that has
>> an address, but you didn't specify the address.  Conversely, when you
>> specify an address, gdb finds the source/line for the address if available,
>> as well as the function.
> 
> That's understood, and it not important for what I have in mind.  The
> important point is that the user can potentially specify every
> attribute of a code location, even if some combinations cannot be
> used.

I guess I don't know how that fits your idea of "100% identical" then.

> 
>> And then GDB knows more about the code locations than that set of attributes,
>> of course.  GDB knows the architecture of the instruction the location points 
>> at, for example.
> 
> Is that exposed to the user somewhere?  I'm only interested in what is
> shown to the user and/or what has user-level consequences.  Internal
> attributes that the user doesn't have to know about are out of scope
> of this issue.

I guess not.

I don't really understand what you're after, so I don't know what to comment
further.  I sounds like you are trying to say that a location spec can be
exactly the same as a code location sometimes.  While in my view, the found code
locations will always have the attributes that match what the user specified,
otherwise the locations wouldn't have been found.  And I thought that that
was already clear in, or obvious from, the text I wrote, and from the specific
location spec format sections.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 18:51:14 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> >> Yes.  Well, except "absolute" in the file name.  The file names in the
> >> debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
> >> and we may not be able to find the source file in the filesystem, so the
> >> path the debug info tells us is all we get.
> > 
> > Then the directory should also be part of the attributes, no?
> 
> I thought that in GNU terminology, "file name" already included the directory?
> ISTR you saying that we shouldn't use "path" to describe directories sometime ago,
> for example.  Maybe I'm misremembering it.

A file name includes the directory, but the directory doesn't have to
be in the absolute form, as you pointed out.  So the directory
relative to which the file name is specified is part of the code
location, I think, because there could be file names in a program
which have the same name, but live in different subdirectories of a
source tree.

> The text I wrote in v4 purposely says "the source file the line belongs to"
> which avoids going into that detail.

Something to ponder, I guess.

> >> When you specify a function name, you can't specify an address
> >> at the same time, for example.  There's no format that allows that.
> >> So if you specify a function, you end up with code location that has
> >> an address, but you didn't specify the address.  Conversely, when you
> >> specify an address, gdb finds the source/line for the address if available,
> >> as well as the function.
> > 
> > That's understood, and it not important for what I have in mind.  The
> > important point is that the user can potentially specify every
> > attribute of a code location, even if some combinations cannot be
> > used.
> 
> I guess I don't know how that fits your idea of "100% identical" then.

I think it's important for describing what exactly happens during the
"resolution" of a location specification into code locations.

> I don't really understand what you're after, so I don't know what to comment
> further.  I sounds like you are trying to say that a location spec can be
> exactly the same as a code location sometimes.  While in my view, the found code
> locations will always have the attributes that match what the user specified,
> otherwise the locations wouldn't have been found.  And I thought that that
> was already clear in, or obvious from, the text I wrote, and from the specific
> location spec format sections.

Yes, but note that the last revision of your patch says "resolves
into", not "matches".  Which I think is a change for the better; I'm
trying to have a more accurate idea of what that "resolution" entails.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 19:23, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 18:51:14 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>>> Yes.  Well, except "absolute" in the file name.  The file names in the
>>>> debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
>>>> and we may not be able to find the source file in the filesystem, so the
>>>> path the debug info tells us is all we get.
>>>
>>> Then the directory should also be part of the attributes, no?
>>
>> I thought that in GNU terminology, "file name" already included the directory?
>> ISTR you saying that we shouldn't use "path" to describe directories sometime ago,
>> for example.  Maybe I'm misremembering it.
> 
> A file name includes the directory, but the directory doesn't have to
> be in the absolute form, as you pointed out.  So the directory
> relative to which the file name is specified is part of the code
> location, I think, because there could be file names in a program
> which have the same name, but live in different subdirectories of a
> source tree.

Yes.

> 
>> The text I wrote in v4 purposely says "the source file the line belongs to"
>> which avoids going into that detail.
> 
> Something to ponder, I guess.
> 
>>>> When you specify a function name, you can't specify an address
>>>> at the same time, for example.  There's no format that allows that.
>>>> So if you specify a function, you end up with code location that has
>>>> an address, but you didn't specify the address.  Conversely, when you
>>>> specify an address, gdb finds the source/line for the address if available,
>>>> as well as the function.
>>>
>>> That's understood, and it not important for what I have in mind.  The
>>> important point is that the user can potentially specify every
>>> attribute of a code location, even if some combinations cannot be
>>> used.
>>
>> I guess I don't know how that fits your idea of "100% identical" then.
> 
> I think it's important for describing what exactly happens during the
> "resolution" of a location specification into code locations.
> 
>> I don't really understand what you're after, so I don't know what to comment
>> further.  I sounds like you are trying to say that a location spec can be
>> exactly the same as a code location sometimes.  While in my view, the found code
>> locations will always have the attributes that match what the user specified,
>> otherwise the locations wouldn't have been found.  And I thought that that
>> was already clear in, or obvious from, the text I wrote, and from the specific
>> location spec format sections.
> 
> Yes, but note that the last revision of your patch says "resolves
> into", not "matches".  Which I think is a change for the better; I'm
> trying to have a more accurate idea of what that "resolution" entails.

Resolution is the act of find all the actual code location that match the user
input.  The found locations are the resolved code locations.

Here for example:

 +@item list @var{locspec}
 +Print lines centered around the line or lines that @var{locspec}
 +resolves to.

The meaning is that the user passes some input spec to GDB, which
may even not specify any line at all, like "line func", and GDB
finds all the matching locations.  For each resolved location, you have
a resolved line, resolved source file, resolved addr, resolved function, etc.
So saying "the lines that locspec resolves to" is a simpler form of saying
"the lines of the locations that locspec resolves to, ignoring locations
that have no line info".

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 19:42, Pedro Alves wrote:
> On 2022-05-27 19:23, Eli Zaretskii wrote:
>>> Date: Fri, 27 May 2022 18:51:14 +0100
>>> Cc: gdb-patches@sourceware.org
>>> From: Pedro Alves <pedro@palves.net>
>>>
>>>>> Yes.  Well, except "absolute" in the file name.  The file names in the
>>>>> debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
>>>>> and we may not be able to find the source file in the filesystem, so the
>>>>> path the debug info tells us is all we get.
>>>>
>>>> Then the directory should also be part of the attributes, no?
>>>
>>> I thought that in GNU terminology, "file name" already included the directory?
>>> ISTR you saying that we shouldn't use "path" to describe directories sometime ago,
>>> for example.  Maybe I'm misremembering it.
>>
>> A file name includes the directory, but the directory doesn't have to
>> be in the absolute form, as you pointed out.  So the directory
>> relative to which the file name is specified is part of the code
>> location, I think, because there could be file names in a program
>> which have the same name, but live in different subdirectories of a
>> source tree.
> 
> Yes.

BTW, my text says this:

 +The location spec may be incomplete, and @value{GDBN} will do its best
 +to find all the locations in the program that match it.  For example,
 +a location spec may just indicate a line number and a source filename
                                                        ^^^^^^^^^^^^^^^
 +with no directory components, 
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

and this example too:

 +@item
 +The location spec specifies a file name, and multiple files in the
 +program share the same name.


IMO, from this it should be obvious that the code location has directory
components that you can match.

The explicit locations section already says for example:

 @table @code
 @item -source @var{filename}
 The value specifies the source file name.  To differentiate between
 files with the same base name, prepend as many directories as is necessary
 to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}.  Otherwise
 @value{GDBN} will use the first file it finds with the given base
 name.   This option requires the use of either @code{-function} or @code{-line}.

I'm not sure we want to go into details like that in the intro section.  Users won't
be able to use any location spec format without reading the corresponding section,
so they'll see this.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 19:42:50 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> > Yes, but note that the last revision of your patch says "resolves
> > into", not "matches".  Which I think is a change for the better; I'm
> > trying to have a more accurate idea of what that "resolution" entails.
> 
> Resolution is the act of find all the actual code location that match the user
> input.  The found locations are the resolved code locations.
> 
> Here for example:
> 
>  +@item list @var{locspec}
>  +Print lines centered around the line or lines that @var{locspec}
>  +resolves to.
> 
> The meaning is that the user passes some input spec to GDB, which
> may even not specify any line at all, like "line func", and GDB
> finds all the matching locations.  For each resolved location, you have
> a resolved line, resolved source file, resolved addr, resolved function, etc.

I understand (I think).  But all this does is fill in the attributes
that were missing from the input location spec.  This is done either
by using the (implied) defaults, like the name of the current file, or
bhy using the debug info.  And if it turns out that some attribute can
be filled in more than one way, we have a breakpoint with multiple
code locations.  Right?

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 19:50:58 +0100
> From: Pedro Alves <pedro@palves.net>
> Cc: gdb-patches@sourceware.org
> 
> BTW, my text says this:
> 
>  +The location spec may be incomplete, and @value{GDBN} will do its best
>  +to find all the locations in the program that match it.  For example,
>  +a location spec may just indicate a line number and a source filename
>                                                         ^^^^^^^^^^^^^^^
>  +with no directory components, 
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> and this example too:
> 
>  +@item
>  +The location spec specifies a file name, and multiple files in the
>  +program share the same name.

That's about location specs; I was talking about the code location,
where the missing attributes need to be resolved.

> IMO, from this it should be obvious that the code location has directory
> components that you can match.

I don't think I follow: match with what and in what way?  Are you
talking about "matching" of an absolute file name with relative file
names?

> The explicit locations section already says for example:
> 
>  @table @code
>  @item -source @var{filename}
>  The value specifies the source file name.  To differentiate between
>  files with the same base name, prepend as many directories as is necessary
>  to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}.  Otherwise
>  @value{GDBN} will use the first file it finds with the given base
>  name.   This option requires the use of either @code{-function} or @code{-line}.
> 
> I'm not sure we want to go into details like that in the intro section.  Users won't
> be able to use any location spec format without reading the corresponding section,
> so they'll see this.

What I was talking about was not about using the location specs, it
was about explaining what it is and how it differs from the code
location.  I think we have to explain the terminology before we use
it, since it is not entirely trivial.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 19:55, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 19:42:50 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>> Yes, but note that the last revision of your patch says "resolves
>>> into", not "matches".  Which I think is a change for the better; I'm
>>> trying to have a more accurate idea of what that "resolution" entails.
>>
>> Resolution is the act of find all the actual code location that match the user
>> input.  The found locations are the resolved code locations.
>>
>> Here for example:
>>
>>  +@item list @var{locspec}
>>  +Print lines centered around the line or lines that @var{locspec}
>>  +resolves to.
>>
>> The meaning is that the user passes some input spec to GDB, which
>> may even not specify any line at all, like "line func", and GDB
>> finds all the matching locations.  For each resolved location, you have
>> a resolved line, resolved source file, resolved addr, resolved function, etc.
> 
> I understand (I think).  But all this does is fill in the attributes
> that were missing from the input location spec.  This is done either
> by using the (implied) defaults, like the name of the current file, or
> bhy using the debug info.  And if it turns out that some attribute can
> be filled in more than one way, we have a breakpoint with multiple
> code locations.  Right?
> 

You start with e.g., just one attribute, like "-function func".  This
makes GDB iterate over all the functions is knows about, finding the
ones that are called "func".  This matches "func(int)", "A::func()",
"func(long)", etc.  GDB collects the PC and source file and line number of
those functions too along the wa.  If you did "break -function func", then
you end up with a breakpoint with multiple code locations, one
for each function matched.

Or you start with "a/file.c:100".  This makes GDB iterate over all source
files it knows about, and then for each that has a file name that ends
with "a/file.c", like e.g., "src/program/a/file.c" and "somelib/a/file.c"
it searches for line 100, collecting the PC and function name of the
location.  If you did "break a/file.c:100", you end up with a breakpoint with
multiple locations, one per resolved location.  If you did 
"list a/file.c:100", GDB lists the source for around each of the locations.
Etc.

Or you start with "*0x1000".  Conceptually it's the same.  GDB finds the code
locations that match that, resolves that to a location with
PC/function/source/line, and then the command does what it wants with it.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 20:05:25 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> > I understand (I think).  But all this does is fill in the attributes
> > that were missing from the input location spec.  This is done either
> > by using the (implied) defaults, like the name of the current file, or
> > bhy using the debug info.  And if it turns out that some attribute can
> > be filled in more than one way, we have a breakpoint with multiple
> > code locations.  Right?
> > 
> 
> You start with e.g., just one attribute, like "-function func".  This
> makes GDB iterate over all the functions is knows about, finding the
> ones that are called "func".  This matches "func(int)", "A::func()",
> "func(long)", etc.  GDB collects the PC and source file and line number of
> those functions too along the wa.  If you did "break -function func", then
> you end up with a breakpoint with multiple code locations, one
> for each function matched.
> 
> Or you start with "a/file.c:100".  This makes GDB iterate over all source
> files it knows about, and then for each that has a file name that ends
> with "a/file.c", like e.g., "src/program/a/file.c" and "somelib/a/file.c"
> it searches for line 100, collecting the PC and function name of the
> location.  If you did "break a/file.c:100", you end up with a breakpoint with
> multiple locations, one per resolved location.  If you did 
> "list a/file.c:100", GDB lists the source for around each of the locations.
> Etc.
> 
> Or you start with "*0x1000".  Conceptually it's the same.  GDB finds the code
> locations that match that, resolves that to a location with
> PC/function/source/line, and then the command does what it wants with it.

Is this supposed to confirm my understanding, or to refute it?  I
think it confirms it.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 20:14, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 20:05:25 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>> I understand (I think).  But all this does is fill in the attributes
>>> that were missing from the input location spec.  This is done either
>>> by using the (implied) defaults, like the name of the current file, or
>>> bhy using the debug info.  And if it turns out that some attribute can
>>> be filled in more than one way, we have a breakpoint with multiple
>>> code locations.  Right?
>>>
>>
>> You start with e.g., just one attribute, like "-function func".  This
>> makes GDB iterate over all the functions is knows about, finding the
>> ones that are called "func".  This matches "func(int)", "A::func()",
>> "func(long)", etc.  GDB collects the PC and source file and line number of
>> those functions too along the wa.  If you did "break -function func", then
>> you end up with a breakpoint with multiple code locations, one
>> for each function matched.
>>
>> Or you start with "a/file.c:100".  This makes GDB iterate over all source
>> files it knows about, and then for each that has a file name that ends
>> with "a/file.c", like e.g., "src/program/a/file.c" and "somelib/a/file.c"
>> it searches for line 100, collecting the PC and function name of the
>> location.  If you did "break a/file.c:100", you end up with a breakpoint with
>> multiple locations, one per resolved location.  If you did 
>> "list a/file.c:100", GDB lists the source for around each of the locations.
>> Etc.
>>
>> Or you start with "*0x1000".  Conceptually it's the same.  GDB finds the code
>> locations that match that, resolves that to a location with
>> PC/function/source/line, and then the command does what it wants with it.
> 
> Is this supposed to confirm my understanding, or to refute it?  I
> think it confirms it.

I didn't understand what you meant by "attribute can be filled in
more than one way", so I explained how it works.  If you start with my example
for "-function func" example from above, what does "attribute is filled in more
than one way" mean in that example?

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 20:00, Eli Zaretskii wrote:

> What I was talking about was not about using the location specs, it
> was about explaining what it is and how it differs from the code
> location.  I think we have to explain the terminology before we use
> it, since it is not entirely trivial.

OK, here's what I added on top of v4, locally.  WDYT?

From 97024e5cd68a1608287c28ea06693a3c18804474 Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Fri, 27 May 2022 20:22:49 +0100
Subject: [PATCH] foo

Change-Id: I18ab66ae278767e2636aa76712e2d5c44ca6ee83
---
 gdb/doc/gdb.texinfo | 37 +++++++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 6deaad88d31..8f25f899263 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9053,10 +9053,13 @@ line in the source code, but it can also indicate a function name, an
 address, a label, and more.
 
 A concrete code location in your program is uniquely identifiable by a
-set of logical attributes.  Typically, a line number, the source file
-the line belongs to, the fully-qualified and prototyped function it is
-defined in, and an instruction address.  Because each inferior has its
-own address space, also an inferior number.
+set of logical attributes.  A line number, the source file the line
+belongs to, the fully-qualified and prototyped function it is defined
+in, and an instruction address.  Because each inferior has its own
+address space, also an inferior number.  The source file attribute has
+as many directory components as possible, retrieved from the debug
+information, and in absolute form if possible, but it may also be in
+relative form.
 
 On the other hand, a @dfn{location specification} (a.k.a.@: location
 spec) is a way to find or refer to the concrete code locations in the
@@ -9065,12 +9068,22 @@ resolves the spec to actual code locations in your program by using
 the source and debug information.
 
 The location spec may be incomplete, and @value{GDBN} will do its best
-to find all the locations in the program that match it.  For example,
-a location spec may just indicate a line number and a source filename
-with no directory components, or even not specify a filename at all,
-just a line number.  Or, the spec may indicate a simple function name
-instead of a fully-qualified and prototyped function name (e.g.,
-@code{func} instead of @code{A::func(int)}).
+to find all the locations in the program that match it.
+
+For example, a location spec may just indicate a line number and a
+source filename with no directory components, or even not specify a
+filename at all, just a line number.  To differentiate between files
+with the same base name, the spec may prepend as many directories as
+is necessary to uniquely identify the desired file.
+
+Or, the spec may indicate a simple function name instead of a
+fully-qualified and prototyped function name (e.g., @code{func}
+instead of @code{A::func(int)}).  To differentiate between functions
+with the same name, the spec may prepend as many class and namespace
+names as is necessary to uniquely identify the desired funnction,
+and/or it may specify the function parameters as well.  In addition,
+the spec may indicate that the function name should be interpreted as
+a fully qualified name.
 
 You may not have debug info for some of the instructions in the
 program, so a resolved location that itself points to such code will
@@ -9105,6 +9118,10 @@ For an inlined function, a given source line can correspond to several
 places where that function is inlined.
 @end itemize
 
+The act of finding all the actual code location that match the user
+input is called @dfn{resolving the location spec}.  The code locations
+that @value{GDBN} finds are the @dfn{resolved code locations}.
+
 Locations may be specified using three different formats: linespec
 locations, explicit locations, or address locations.
 

-- 
2.36.0

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 20:17:21 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> >> You start with e.g., just one attribute, like "-function func".  This
> >> makes GDB iterate over all the functions is knows about, finding the
> >> ones that are called "func".  This matches "func(int)", "A::func()",
> >> "func(long)", etc.  GDB collects the PC and source file and line number of
> >> those functions too along the wa.  If you did "break -function func", then
> >> you end up with a breakpoint with multiple code locations, one
> >> for each function matched.
> >>
> >> Or you start with "a/file.c:100".  This makes GDB iterate over all source
> >> files it knows about, and then for each that has a file name that ends
> >> with "a/file.c", like e.g., "src/program/a/file.c" and "somelib/a/file.c"
> >> it searches for line 100, collecting the PC and function name of the
> >> location.  If you did "break a/file.c:100", you end up with a breakpoint with
> >> multiple locations, one per resolved location.  If you did 
> >> "list a/file.c:100", GDB lists the source for around each of the locations.
> >> Etc.
> >>
> >> Or you start with "*0x1000".  Conceptually it's the same.  GDB finds the code
> >> locations that match that, resolves that to a location with
> >> PC/function/source/line, and then the command does what it wants with it.
> > 
> > Is this supposed to confirm my understanding, or to refute it?  I
> > think it confirms it.
> 
> I didn't understand what you meant by "attribute can be filled in
> more than one way", so I explained how it works.  If you start with my example
> for "-function func" example from above, what does "attribute is filled in more
> than one way" mean in that example?

It means that each of the following attributes of code location can
have more than one value that satisfies the location spec:

  . function prototype
  . possibly file name
  . line number
  . code address

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 20:34, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 20:17:21 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>>> You start with e.g., just one attribute, like "-function func".  This
>>>> makes GDB iterate over all the functions is knows about, finding the
>>>> ones that are called "func".  This matches "func(int)", "A::func()",
>>>> "func(long)", etc.  GDB collects the PC and source file and line number of
>>>> those functions too along the wa.  If you did "break -function func", then
>>>> you end up with a breakpoint with multiple code locations, one
>>>> for each function matched.
>>>>
>>>> Or you start with "a/file.c:100".  This makes GDB iterate over all source
>>>> files it knows about, and then for each that has a file name that ends
>>>> with "a/file.c", like e.g., "src/program/a/file.c" and "somelib/a/file.c"
>>>> it searches for line 100, collecting the PC and function name of the
>>>> location.  If you did "break a/file.c:100", you end up with a breakpoint with
>>>> multiple locations, one per resolved location.  If you did 
>>>> "list a/file.c:100", GDB lists the source for around each of the locations.
>>>> Etc.
>>>>
>>>> Or you start with "*0x1000".  Conceptually it's the same.  GDB finds the code
>>>> locations that match that, resolves that to a location with
>>>> PC/function/source/line, and then the command does what it wants with it.
>>>
>>> Is this supposed to confirm my understanding, or to refute it?  I
>>> think it confirms it.
>>
>> I didn't understand what you meant by "attribute can be filled in
>> more than one way", so I explained how it works.  If you start with my example
>> for "-function func" example from above, what does "attribute is filled in more
>> than one way" mean in that example?
> 
> It means that each of the following attributes of code location can
> have more than one value that satisfies the location spec:
> 
>   . function prototype
>   . possibly file name
>   . line number
>   . code address

OK.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> From: Pedro Alves <pedro@palves.net>
> Date: Thu, 26 May 2022 20:42:50 +0100
> 
>  gdb/doc/gdb.texinfo | 419 +++++++++++++++++++++++++-------------------
>  gdb/doc/guile.texi  |   2 +-
>  gdb/doc/python.texi |   5 +-
>  3 files changed, 246 insertions(+), 180 deletions(-)

Thanks, my comments are below.

> +@item break @var{locspec}
> +Set a breakpoint at all the code locations in your program the given
> +@var{locspec} resolves to.

I find the style that puts "resolves to" last awkward and hard to
read.  I suggest a slight rewording:

  Set a breakpoint at all the code locations in your program that are
  the result of resolving the given @var{locspec}.

> +a line number, an address of an instruction, and more.  @xref{Location
> +Specifications}, for the various forms of @var{locspec}.  The
> +breakpoint will stop your program just before it executes the
> +instruction at the address of any of the breakpoint's locations.
                                            ^^^^^^^^^^^^^^^^^^^^^^
"breakpoint's code locations"

>  A breakpoint with multiple locations is displayed in the breakpoint
                              ^^^^^^^^^
"code locations"

>  table using several rows---one header row, followed by one row for
>  each breakpoint location.  The header row has @samp{<MULTIPLE>} in the
        ^^^^^^^^^^^^^^^^^^^
"code location of the breakpoint"

> +address column.  Each breakpoint location row contains the actual
                         ^^^^^^^^^^^^^^^^^^^
"code location"

> +address, source file, source line and function of its code location.
> +The number column for a breakpoint location is of the form
                           ^^^^^^^^^^^^^^^^^^^
"code location"

>  @kindex set breakpoint pending
>  @kindex show breakpoint pending
>  @table @code
>  @item set breakpoint pending auto
> -This is the default behavior.  When @value{GDBN} cannot find the breakpoint
> -location, it queries you whether a pending breakpoint should be created.
> +This is the default behavior.  When @value{GDBN} cannot resolve the
> +location spec, it should create a pending breakpoint without
> +confirmation.
>  
>  @item set breakpoint pending on
> -This indicates that an unrecognized breakpoint location should automatically
> -result in a pending breakpoint being created.
> +This indicates that when @value{GDBN} cannot resolve the location
> +spec, it should create a pending breakpoint without confirmation.

These two option's values seem to have an identical description.  Is
that intentional?  I think the first of the two is a copy/paste error.

Btw, is the "cannot resolve the location spec" situation and its
reasons described somewhere?  The text in this section seems to
indicate this is described in "Location Specifications", but I don't
think I see it there.

>  The settings above only affect the @code{break} command and its
> -variants.  Once breakpoint is set, it will be automatically updated
> +variants.  Once a breakpoint is set, it will be automatically updated
>  as shared libraries are loaded and unloaded.

Does this mean the resolution process of an unresolved location spec
is retried each time a shared library is loaded?  If so, I think we
should say it here explicitly.

> -@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}"

> +@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}]
> +Whenever execution reaches a code location in your program that
> +matches @var{locspec}, print the values of one or more

Likewise here (and elsewhere): I don't think we should talk about
"matching a location spec", but about "resolution of a location spec".
"Matching" implies something that we don't really do here.

>  Print lines from @var{first} to @var{last}.  Both arguments are
> -locations.  When a @code{list} command has two locations, and the
> -source file of the second location is omitted, this refers to
> -the same source file as the first location.
> +location specs.  When a @code{list} command has two location specs,
> +and the source file of the second location spec is omitted, this
> +refers to the same source file as the first location spec.  If either
> +@var{first} or @var{last} resolve to more than one source line in the
> +program, then the list command will show the list of resolved source
> +lines and does not proceed with the source code listing.
             ^^^^^^^^^^^^^^^^
"will not proceed", to be consistent with "will show".

> +Likewise, if @var{last} resolves to more than one source line in the
> +program, then the list command will print the list of resolved source
> +lines and does not proceed with the source code listing.

Same here.

> +
>  @item list @var{first},
>  Print lines starting with @var{first}.
>  
> @@ -9041,17 +9038,75 @@ Print lines just before the lines last printed.
>  As described in the preceding table.
>  @end table
>  
> -@node Specify Location
> -@section Specifying a Location
> +@node Location Specifications
> +@section Location Specifications
>  @cindex specifying location
> -@cindex location
> +@cindex location spec
> +@cindex locspec
>  @cindex source location
> +@cindex code location
>  
>  Several @value{GDBN} commands accept arguments that specify a location
> -of your program's code.  Since @value{GDBN} is a source-level
> -debugger, a location usually specifies some line in the source code.
> -Locations may be specified using three different formats:
> -linespec locations, explicit locations, or address locations.
> +or locations of your program's code.  Since @value{GDBN} is a
> +source-level debugger, a location specification usually indicates some
> +line in the source code, but it can also indicate a function name, an
> +address, a label, and more.
> +
> +A concrete code location in your program is uniquely identifiable by a
> +set of logical attributes.  Typically, a line number, the source file
> +the line belongs to, the fully-qualified and prototyped function it is
> +defined in, and an instruction address.  Because each inferior has its
> +own address space, also an inferior number.
> +
> +On the other hand, a @dfn{location specification} (a.k.a.@: location
> +spec)

"location spec" should be in @dfn here the first time it is used.

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

> +Addresses cannot be specified with a location spec (@pxref{Location
> +Specifications}).

I think they can, but only if using one particular form of a location
spec, the *ADDR one.  Or am I missing something?

> +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"?

> +@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?

> -If @var{location} cannot be parsed (for example if it
> +If @var{locspec} cannot be parsed (for example if it
>  refers to unknown files or functions), create a pending
>  breakpoint. Without this flag, @value{GDBN} will report
             ^^
Two spaces between sentences.  (Yes, a mistake in the original text.)

>  @smallexample
> - -exec-jump @var{location}
> + -exec-jump @var{locspec}
>  @end smallexample
>  
>  Resumes execution of the inferior program at the location specified by
> -parameter.  @xref{Specify Location}, for a description of the
> -different forms of @var{location}.
> +the parameter.  @xref{Location Specifications}, for a description of
   ^^^^^^^^^^^^^
I think this should be "@var{locspec}".

> +Executes the inferior until the address @var{locspec} resolves to.  If

This is highly ambiguous: "until" here could be interpreted as
referring to "resolves" instead of to "address".  Suggest to rephrase:

  Executes the inferior until it reaches the address to which
  @var{locspec} resolves.

> +there is no argument, the inferior executes until a source line
> +greater than the current one is reached.

Suggest to get rid of the passive tense with

  "...until it reaches a source line greater than the current line."

Re: [PATCH v4] gdb/manual: Introduce location specs

[Eli Zaretskii]

> Date: Fri, 27 May 2022 20:30:06 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> On 2022-05-27 20:00, Eli Zaretskii wrote:
> 
> > What I was talking about was not about using the location specs, it
> > was about explaining what it is and how it differs from the code
> > location.  I think we have to explain the terminology before we use
> > it, since it is not entirely trivial.
> 
> OK, here's what I added on top of v4, locally.  WDYT?

LGTM, so I think this can go in, given the results of my review of the
rest of the patch (see my other message) are taken care of.

I will re-read this section after the changes are pushed, and decide
whether any additional clarifications are needed; if so, I will make
those changes later.

Thanks.

Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-28 08:43, Eli Zaretskii wrote:
>> Date: Fri, 27 May 2022 20:30:06 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>> On 2022-05-27 20:00, Eli Zaretskii wrote:
>>
>>> What I was talking about was not about using the location specs, it
>>> was about explaining what it is and how it differs from the code
>>> location.  I think we have to explain the terminology before we use
>>> it, since it is not entirely trivial.
>>
>> OK, here's what I added on top of v4, locally.  WDYT?
> 
> LGTM, so I think this can go in, given the results of my review of the
> rest of the patch (see my other message) are taken care of.

Great, thanks!  I've addressed your review in the other email and
pushed the result.  I'll send a detailed reply to your other message
after sending this one.

[pushed v5] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-28 08:39, Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Date: Thu, 26 May 2022 20:42:50 +0100
>>
>>  gdb/doc/gdb.texinfo | 419 +++++++++++++++++++++++++-------------------
>>  gdb/doc/guile.texi  |   2 +-
>>  gdb/doc/python.texi |   5 +-
>>  3 files changed, 246 insertions(+), 180 deletions(-)
> 
> Thanks, my comments are below.
> 
>> +@item break @var{locspec}
>> +Set a breakpoint at all the code locations in your program the given
>> +@var{locspec} resolves to.
> 
> I find the style that puts "resolves to" last awkward and hard to
> read.  I suggest a slight rewording:
> 
>   Set a breakpoint at all the code locations in your program that are
>   the result of resolving the given @var{locspec}.

Done, throughout.

> 
>> +a line number, an address of an instruction, and more.  @xref{Location
>> +Specifications}, for the various forms of @var{locspec}.  The
>> +breakpoint will stop your program just before it executes the
>> +instruction at the address of any of the breakpoint's locations.
>                                             ^^^^^^^^^^^^^^^^^^^^^^
> "breakpoint's code locations"

Done.

> 
>>  A breakpoint with multiple locations is displayed in the breakpoint
>                               ^^^^^^^^^
> "code locations"
> 
>>  table using several rows---one header row, followed by one row for
>>  each breakpoint location.  The header row has @samp{<MULTIPLE>} in the
>         ^^^^^^^^^^^^^^^^^^^
> "code location of the breakpoint"
> 
>> +address column.  Each breakpoint location row contains the actual
>                          ^^^^^^^^^^^^^^^^^^^
> "code location"
> 
>> +address, source file, source line and function of its code location.
>> +The number column for a breakpoint location is of the form
>                            ^^^^^^^^^^^^^^^^^^^
> "code location"
> 
>>  @kindex set breakpoint pending
>>  @kindex show breakpoint pending
>>  @table @code
>>  @item set breakpoint pending auto
>> -This is the default behavior.  When @value{GDBN} cannot find the breakpoint
>> -location, it queries you whether a pending breakpoint should be created.
>> +This is the default behavior.  When @value{GDBN} cannot resolve the
>> +location spec, it should create a pending breakpoint without
>> +confirmation.
>>  
>>  @item set breakpoint pending on
>> -This indicates that an unrecognized breakpoint location should automatically
>> -result in a pending breakpoint being created.
>> +This indicates that when @value{GDBN} cannot resolve the location
>> +spec, it should create a pending breakpoint without confirmation.
> 
> These two option's values seem to have an identical description.  Is
> that intentional?  I think the first of the two is a copy/paste error.

You're right.  Thanks for catching that.  Fixed.

> 
> Btw, is the "cannot resolve the location spec" situation and its
> reasons described somewhere?  The text in this section seems to
> indicate this is described in "Location Specifications", but I don't
> think I see it there.

Just above this table, we say:

 @value{GDBN} provides some additional commands for controlling what
 happens when the @samp{break} command cannot resolve the location spec
 to any code location in your program (@pxref{Location
 Specifications}):

So "cannot resolve the location spec" was just shorter way to say that,
to avoid repeting "to any code location in your program", which is clear
from context.

Anyhow, I've added this sentence to the "Location Specifications" section:

 "If @value{GDBN} cannot find any code location that matches the user
 input, it is said that @value{GDBN} could not resolve the location
 spec."

> 
>>  The settings above only affect the @code{break} command and its
>> -variants.  Once breakpoint is set, it will be automatically updated
>> +variants.  Once a breakpoint is set, it will be automatically updated
>>  as shared libraries are loaded and unloaded.
> 
> Does this mean the resolution process of an unresolved location spec
> is retried each time a shared library is loaded?  If so, I think we
> should say it here explicitly.

Yes.  This is also said (using different terms) a bit higher up, here:

 After the program is run, whenever a new shared library is loaded,
 @value{GDBN} reevaluates all the breakpoints.

My "make info breakpoints always show breakpoints in multi-location form"
patch reworked the "Set Breaks" section more thoroughly, including the description
of pending breakpoint.  I would prefer to leave deeper changes here to a follow
up patch, based on that one.

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

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.


> 
>> +@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}]
>> +Whenever execution reaches a code location in your program that
>> +matches @var{locspec}, print the values of one or more
> 
> Likewise here (and elsewhere): I don't think we should talk about
> "matching a location spec", but about "resolution of a location spec".
> "Matching" implies something that we don't really do here.

Done.

> 
>>  Print lines from @var{first} to @var{last}.  Both arguments are
>> -locations.  When a @code{list} command has two locations, and the
>> -source file of the second location is omitted, this refers to
>> -the same source file as the first location.
>> +location specs.  When a @code{list} command has two location specs,
>> +and the source file of the second location spec is omitted, this
>> +refers to the same source file as the first location spec.  If either
>> +@var{first} or @var{last} resolve to more than one source line in the
>> +program, then the list command will show the list of resolved source
>> +lines and does not proceed with the source code listing.
>              ^^^^^^^^^^^^^^^^
> "will not proceed", to be consistent with "will show".

I switched the other one to say "shows" instead "will show".  I hope
you don't mind.  Using future tense in tech manuals is a pet peeve of mine,
actually.  I don't know how it ended up here.  I probably copied this
from elsewhere.

> 
>> +Likewise, if @var{last} resolves to more than one source line in the
>> +program, then the list command will print the list of resolved source
>> +lines and does not proceed with the source code listing.
> 
> Same here.

Fixed the same way.

> 
>> +
>>  @item list @var{first},
>>  Print lines starting with @var{first}.
>>  
>> @@ -9041,17 +9038,75 @@ Print lines just before the lines last printed.
>>  As described in the preceding table.
>>  @end table
>>  
>> -@node Specify Location
>> -@section Specifying a Location
>> +@node Location Specifications
>> +@section Location Specifications
>>  @cindex specifying location
>> -@cindex location
>> +@cindex location spec
>> +@cindex locspec
>>  @cindex source location
>> +@cindex code location
>>  
>>  Several @value{GDBN} commands accept arguments that specify a location
>> -of your program's code.  Since @value{GDBN} is a source-level
>> -debugger, a location usually specifies some line in the source code.
>> -Locations may be specified using three different formats:
>> -linespec locations, explicit locations, or address locations.
>> +or locations of your program's code.  Since @value{GDBN} is a
>> +source-level debugger, a location specification usually indicates some
>> +line in the source code, but it can also indicate a function name, an
>> +address, a label, and more.
>> +
>> +A concrete code location in your program is uniquely identifiable by a
>> +set of logical attributes.  Typically, a line number, the source file
>> +the line belongs to, the fully-qualified and prototyped function it is
>> +defined in, and an instruction address.  Because each inferior has its
>> +own address space, also an inferior number.
>> +
>> +On the other hand, a @dfn{location specification} (a.k.a.@: location
>> +spec)
> 
> "location spec" should be in @dfn here the first time it is used.
> 

Done.

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

> 
>> +Addresses cannot be specified with a location spec (@pxref{Location
>> +Specifications}).
> 
> I think they can, but only if using one particular form of a location
> spec, the *ADDR one.  Or am I missing something?

This is talking about the addresses you can pass to the disassembly
command, not about location specs in general.  "disassemble"'s arguments are
expressions, not locations specs.  Note I had just changed "location" to "location spec".

I've now changed it to:

 Note that the @samp{disassemble} command's address arguments are
 specified using expressions in your programming language
 (@pxref{Expressions, ,Expressions}), not location specs
 (@pxref{Location Specifications}).  So, for example, if you want to
 disassemble function @code{bar} in file @file{foo.c}, you must type
 @samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}.

 
>> +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.  I did that change.  The previous sentence already explained the
situation in terms of addresses.  And early in the command's documentation we
explain that we resume at some address.

The code itself looks like this:

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

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

> 
>> -If @var{location} cannot be parsed (for example if it
>> +If @var{locspec} cannot be parsed (for example if it
>>  refers to unknown files or functions), create a pending
>>  breakpoint. Without this flag, @value{GDBN} will report
>              ^^
> Two spaces between sentences.  (Yes, a mistake in the original text.)

Thanks, fixed.  

I also tweaked "cannot be parsed" to "cannot be resolved".
"Cannot be parsed" seems plain wrong here.

> 
>>  @smallexample
>> - -exec-jump @var{location}
>> + -exec-jump @var{locspec}
>>  @end smallexample
>>  
>>  Resumes execution of the inferior program at the location specified by
>> -parameter.  @xref{Specify Location}, for a description of the
>> -different forms of @var{location}.
>> +the parameter.  @xref{Location Specifications}, for a description of
>    ^^^^^^^^^^^^^
> I think this should be "@var{locspec}".

Done.

> 
>> +Executes the inferior until the address @var{locspec} resolves to.  If
> 
> This is highly ambiguous: "until" here could be interpreted as
> referring to "resolves" instead of to "address".  Suggest to rephrase:
> 
>   Executes the inferior until it reaches the address to which
>   @var{locspec} resolves.

Done.

> 
>> +there is no argument, the inferior executes until a source line
>> +greater than the current one is reached.
> 
> Suggest to get rid of the passive tense with
> 
>   "...until it reaches a source line greater than the current line."
> 

Done.

This was for the "until" command.  I've tweaked the "advance" command's
description to use the same wording as the "until" command too.

Below is the patch that I merged.

~~~~
From 5541bfdc97936581c0ead915e9117e22f21bdb12 Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 17 May 2022 13:12:04 +0100
Subject: [PATCH] gdb/manual: Introduce location specs

The current "Specify Location" section of the GDB manual starts with:

 "Several @value{GDBN} commands accept arguments that specify a location
 of your program's code."

And then, such commands are documented as taking a "location"
argument.  For example, here's a representative subset:

 @item break @var{location}
 @item clear @var{location}
 @item until @var{location}
 @item list @var{location}
 @item edit @var{location}
 @itemx info line @var{location}
 @item info macros @var{location}
 @item trace @var{location}
 @item info scope @var{location}
 @item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}

The issue here is that "location" isn't really correct for most of
these commands.  Instead, the "location" argument is really a
placeholder that represent an umbrella term for all of the
"linespecs", "explicit location", and "address location" input
formats.  GDB parses these and then finds the actual code locations
(plural) in the program that match.  For example, a "location"
specified like "-function func" will actually match all the code
locations in the program that correspond to the address/file/lineno of
all the functions named "func" in all the loaded programs and shared
libraries of all the inferiors.  A location specified like "-function
func -label lab" matches all the addresses of C labels named "lab" in
all functions named "func".  Etc.

This means that several of the commands that claim they accept a
"location", actually end up working with multiple locations, and the
manual doesn't explain that all that well.  In some cases, the command
will work with all the resolved locations.  In other cases, the
command aborts with an error if the location specification resolves to
multiple locations in the program.  In other cases, GDB just
arbitrarily and silently picks whatever is the first resolved code
location (which sounds like should be improved).

To clarify this, I propose we use the term "Location Specification",
with shorthand "locaction spec", when we're talking about the user
input, the argument or arguments that is/are passed to commands to
instruct GDB how to find locations of interest.  This is distinct from
the actual code locations in the program, which are what GDB finds
based on the user-specified location spec.  Then use "location
specification or the shorter "location spec" thoughout instead of
"location" when we're talking about the user input.

Thus, this commit does the following:

- renames the "Specify Location" section of the manual to "Location
  Specifications".

- It then introduces the term "Location Specification", with
  corresponding shorthand "location spec", as something distinct from
  an actual code location in the program.  It explains what a concrete
  code location is.  It explains that a location specification may be
  incomplete, and that may match multiple code locations in the
  program, or no code location at all.  It gives examples.  Some
  pre-existing examples were moved from the "Set Breaks" section, and
  a few new ones that didn't exist yet were added.  I think it is
  better to have these centralized in this "Location Specification"
  section, since all the other commands that accept a location spec
  have an xref that points there.

- Goes through the manual, and where "@var{location}" was used for a
  command argument, updated it to say "@var{locspec}" instead.  At the
  same time, tweaks the description of the affected commands to
  describe what happens when the location spec resolves to more than
  one location.  Most commands just did not say anything about that.

  One command -- "maint agent -at @var{location}" -- currently says it
  accepts a "location", suggesting it can accept address and explicit
  locations too, but that's incorrect.  In reality, it only accepts
  linespecs, so fix it accordingly.

  One MI command -- "-trace-find line" -- currently says it accepts a
  "line specification", but it can accept address and explicit
  locations too, so fix it accordingly.

Special thanks goes to Eli Zaretskii for reviews and rewording
suggestions.

Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b
---
 gdb/doc/gdb.texinfo | 489 +++++++++++++++++++++++++++-----------------
 gdb/doc/guile.texi  |   2 +-
 gdb/doc/python.texi |   5 +-
 3 files changed, 305 insertions(+), 191 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 68679982919..3cf4e2c73c0 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2024,7 +2024,7 @@ func<int>()    func<float>()
 (@value{GDBP}) p 'func<
 @end smallexample
 
-When setting breakpoints however (@pxref{Specify Location}), you don't
+When setting breakpoints however (@pxref{Location Specifications}), you don't
 usually need to type a quote before the function name, because
 @value{GDBN} understands that you want to set a breakpoint on a
 function:
@@ -4343,17 +4343,20 @@ Vars,, Convenience Variables}, for a discussion of what you can do with
 convenience variables.
 
 @table @code
-@item break @var{location}
-Set a breakpoint at the given @var{location}, which can specify a
-function name, a line number, or an address of an instruction.
-(@xref{Specify Location}, for a list of all the possible ways to
-specify a @var{location}.)  The breakpoint will stop your program just
-before it executes any of the code in the specified @var{location}.
+@item break @var{locspec}
+Set a breakpoint at all the code locations in your program that result
+from resolving the given @var{locspec}.  @var{locspec} can specify a
+function name, a line number, an address of an instruction, and more.
+@xref{Location Specifications}, for the various forms of
+@var{locspec}.  The breakpoint will stop your program just before it
+executes the instruction at the address of any of the breakpoint's
+code locations.
 
-When using source languages that permit overloading of symbols, such as
-C@t{++}, a function name may refer to more than one possible place to break.
-@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
-that situation.
+When using source languages that permit overloading of symbols, such
+as C@t{++}, a function name may refer to more than one symbol, and
+thus more than one place to break.  @xref{Ambiguous
+Expressions,,Ambiguous Expressions}, for a discussion of that
+situation.
 
 It is also possible to insert a breakpoint that will stop the program
 only if a specific thread (@pxref{Thread-Specific Breakpoints})
@@ -4614,35 +4617,16 @@ the breakpoints are conditional, this is even useful
 
 @cindex multiple locations, breakpoints
 @cindex breakpoints, multiple locations
-It is possible that a breakpoint corresponds to several locations
-in your program.  Examples of this situation are:
-
-@itemize @bullet
-@item
-Multiple functions in the program may have the same name.
-
-@item
-For a C@t{++} constructor, the @value{NGCC} compiler generates several
-instances of the function body, used in different cases.
-
-@item
-For a C@t{++} template function, a given line in the function can
-correspond to any number of instantiations.
-
-@item
-For an inlined function, a given source line can correspond to
-several places where that function is inlined.
-@end itemize
-
-In all those cases, @value{GDBN} will insert a breakpoint at all
-the relevant locations.
-
-A breakpoint with multiple locations is displayed in the breakpoint
-table using several rows---one header row, followed by one row for
-each breakpoint location.  The header row has @samp{<MULTIPLE>} in the
-address column.  The rows for individual locations contain the actual
-addresses for locations, and show the functions to which those
-locations belong.  The number column for a location is of the form
+It is possible that a single logical breakpoint is set at several code
+locations in your program.  @xref{Location Specifications}, for
+examples.
+
+A breakpoint with multiple code locations is displayed in the
+breakpoint table using several rows---one header row, followed by one
+row for each code location.  The header row has @samp{<MULTIPLE>} in
+the address column.  Each code location row contains the actual
+address, source file, source line and function of its code location.
+The number column for a code location is of the form
 @var{breakpoint-number}.@var{location-number}.
 
 For example:
@@ -4711,31 +4695,34 @@ differ from regular breakpoints.  You can set conditions or commands,
 enable and disable them and perform other breakpoint operations.
 
 @value{GDBN} provides some additional commands for controlling what
-happens when the @samp{break} command cannot resolve breakpoint
-address specification to an address:
+happens when the @samp{break} command cannot resolve the location spec
+to any code location in your program (@pxref{Location
+Specifications}):
 
 @kindex set breakpoint pending
 @kindex show breakpoint pending
 @table @code
 @item set breakpoint pending auto
-This is the default behavior.  When @value{GDBN} cannot find the breakpoint
-location, it queries you whether a pending breakpoint should be created.
+This is the default behavior.  When @value{GDBN} cannot resolve the
+location spec, it queries you whether a pending breakpoint should be
+created.
 
 @item set breakpoint pending on
-This indicates that an unrecognized breakpoint location should automatically
-result in a pending breakpoint being created.
+This indicates that when @value{GDBN} cannot resolve the location
+spec, it should create a pending breakpoint without confirmation.
 
 @item set breakpoint pending off
-This indicates that pending breakpoints are not to be created.  Any
-unrecognized breakpoint location results in an error.  This setting does
-not affect any pending breakpoints previously created.
+This indicates that pending breakpoints are not to be created.  If
+@value{GDBN} cannot resolve the location spec, it aborts the
+breakpoint creation with an error.  This setting does not affect any
+pending breakpoints previously created.
 
 @item show breakpoint pending
 Show the current behavior setting for creating pending breakpoints.
 @end table
 
 The settings above only affect the @code{break} command and its
-variants.  Once breakpoint is set, it will be automatically updated
+variants.  Once a breakpoint is set, it will be automatically updated
 as shared libraries are loaded and unloaded.
 
 @cindex automatic hardware breakpoints
@@ -5455,10 +5442,10 @@ selected stack frame (@pxref{Selection, ,Selecting a Frame}).  When
 the innermost frame is selected, this is a good way to delete a
 breakpoint where your program just stopped.
 
-@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}.
+@xref{Location Specifications}, for the various forms of
+@var{locspec}; the most useful ones are listed below:
 
 @table @code
 @item clear @var{function}
@@ -5815,10 +5802,11 @@ everything without needing to communicate with @value{GDBN}.
 
 @table @code
 @kindex dprintf
-@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}]
-Whenever execution reaches @var{location}, print the values of one or
-more @var{expressions} under the control of the string @var{template}.
-To print several values, separate them with commas.
+@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}]
+Whenever execution reaches a code location that results from resolving
+@var{locspec}, print the values of one or more @var{expressions} under
+the control of the string @var{template}.  To print several values,
+separate them with commas.
 
 @item set dprintf-style @var{style}
 Set the dprintf output to be handled in one of several different
@@ -6313,11 +6301,12 @@ statement---not in terms of the actual machine code.
 instruction stepping, and hence is slower than @code{until} with an
 argument.
 
-@item until @var{location}
-@itemx u @var{location}
-Continue running your program until either the specified @var{location} is
-reached, or the current stack frame returns.  The location is any of
-the forms described in @ref{Specify Location}.
+@item until @var{locspec}
+@itemx u @var{locspec}
+Continue running your program until either it reaches a code location
+that results from resolving @var{locspec}, or the current stack frame
+returns.  @var{locspec} is any of the forms described in @ref{Location
+Specifications}.
 This form of the command uses temporary breakpoints, and
 hence is quicker than @code{until} without an argument.  The specified
 location is actually reached only if it is in the current frame.  This
@@ -6338,15 +6327,15 @@ invocations have returned.
 @end smallexample
 
 
-@kindex advance @var{location}
-@item advance @var{location}
-Continue running the program up to the given @var{location}.  An argument is
-required, which should be of one of the forms described in
-@ref{Specify Location}.
-Execution will also stop upon exit from the current stack
-frame.  This command is similar to @code{until}, but @code{advance} will
-not skip over recursive function calls, and the target location doesn't
-have to be in the same frame as the current one.
+@kindex advance @var{locspec}
+@item advance @var{locspec}
+Continue running your program until either it reaches a code location
+that results from resolving @var{locspec}, or the current stack frame
+returns.  @var{locspec} is any of the forms described in @ref{Location
+Specifications}.  This command is similar to @code{until}, but
+@code{advance} will not skip over recursive function calls, and the
+target code location doesn't have to be in the same frame as the
+current one.
 
 
 @kindex stepi
@@ -6442,7 +6431,7 @@ A more flexible solution is to execute @kbd{skip boring}.  This instructs
 @code{foo}.
 
 Functions may be skipped by providing either a function name, linespec
-(@pxref{Specify Location}), regular expression that matches the function's
+(@pxref{Location Specifications}), regular expression that matches the function's
 name, file name or a @code{glob}-style pattern that matches the file name.
 
 On Posix systems the form of the regular expression is
@@ -6479,7 +6468,7 @@ over when stepping.
 @itemx -fu @var{linespec}
 Functions named by @var{linespec} or the function containing the line
 named by @var{linespec} will be skipped over when stepping.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @item -rfunction @var{regexp}
 @itemx -rfu @var{regexp}
@@ -6512,7 +6501,7 @@ will be skipped.
 @item skip function @r{[}@var{linespec}@r{]}
 After running this command, the function named by @var{linespec} or the
 function containing the line named by @var{linespec} will be skipped over when
-stepping.  @xref{Specify Location}.
+stepping.  @xref{Location Specifications}.
 
 If you do not specify @var{linespec}, the function you're currently debugging
 will be skipped.
@@ -7141,11 +7130,10 @@ breakpoints on all threads, or on a particular thread.
 @cindex breakpoints and threads
 @cindex thread breakpoints
 @kindex break @dots{} thread @var{thread-id}
-@item break @var{location} thread @var{thread-id}
-@itemx break @var{location} thread @var{thread-id} if @dots{}
-@var{location} specifies source lines; there are several ways of
-writing them (@pxref{Specify Location}), but the effect is always to
-specify some source line.
+@item break @var{locspec} thread @var{thread-id}
+@itemx break @var{locspec} thread @var{thread-id} if @dots{}
+@var{locspec} specifies a code location or locations in your program.
+@xref{Location Specifications}, for details.
 
 Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
 to specify that you only want @value{GDBN} to stop the program when a
@@ -8945,7 +8933,7 @@ prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
 
 @menu
 * List::                        Printing source lines
-* Specify Location::            How to specify code locations
+* Location Specifications::     How to specify code locations
 * Edit::                        Editing source files
 * Search::                      Searching source files
 * Source Path::                 Specifying source directories
@@ -8961,7 +8949,7 @@ prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
 To print lines from a source file, use the @code{list} command
 (abbreviated @code{l}).  By default, ten lines are printed.
 There are several ways to specify what part of the file you want to
-print; see @ref{Specify Location}, for the full list.
+print; see @ref{Location Specifications}, for the full list.
 
 Here are the forms of the @code{list} command most commonly used:
 
@@ -9008,26 +8996,35 @@ than listing the same lines again.  An exception is made for an
 argument of @samp{-}; that argument is preserved in repetition so that
 each repetition moves up in the source file.
 
-In general, the @code{list} command expects you to supply zero, one or two
-@dfn{locations}.  Locations specify source lines; there are several ways
-of writing them (@pxref{Specify Location}), but the effect is always
-to specify some source line.
+In general, the @code{list} command expects you to supply zero, one or
+two location specs.  These location specs are interpreted to resolve
+to source code lines; there are several ways of writing them
+(@pxref{Location Specifications}), but the effect is always to resolve
+to some source lines to display.
 
 Here is a complete description of the possible arguments for @code{list}:
 
 @table @code
-@item list @var{location}
-Print lines centered around the line specified by @var{location}.
+@item list @var{locspec}
+Print lines centered around the line or lines of all the code
+locations that result from resolving @var{locspec}.
 
 @item list @var{first},@var{last}
 Print lines from @var{first} to @var{last}.  Both arguments are
-locations.  When a @code{list} command has two locations, and the
-source file of the second location is omitted, this refers to
-the same source file as the first location.
+location specs.  When a @code{list} command has two location specs,
+and the source file of the second location spec is omitted, this
+refers to the same source file as the first location spec.  If either
+@var{first} or @var{last} resolve to more than one source line in the
+program, then the list command shows the list of resolved source
+lines and does not proceed with the source code listing.
 
 @item list ,@var{last}
 Print lines ending with @var{last}.
 
+Likewise, if @var{last} resolves to more than one source line in the
+program, then the list command prints the list of resolved source
+lines and does not proceed with the source code listing.
+
 @item list @var{first},
 Print lines starting with @var{first}.
 
@@ -9041,17 +9038,115 @@ Print lines just before the lines last printed.
 As described in the preceding table.
 @end table
 
-@node Specify Location
-@section Specifying a Location
+@node Location Specifications
+@section Location Specifications
 @cindex specifying location
-@cindex location
+@cindex location spec
+@cindex locspec
 @cindex source location
+@cindex code location
 
 Several @value{GDBN} commands accept arguments that specify a location
-of your program's code.  Since @value{GDBN} is a source-level
-debugger, a location usually specifies some line in the source code.
-Locations may be specified using three different formats:
-linespec locations, explicit locations, or address locations.
+or locations of your program's code.  Since @value{GDBN} is a
+source-level debugger, a location specification usually indicates some
+line in the source code, but it can also indicate a function name, an
+address, a label, and more.
+
+A concrete code location in your program is uniquely identifiable by a
+set of logical attributes.  A line number, the source file the line
+belongs to, the fully-qualified and prototyped function it is defined
+in, and an instruction address.  Because each inferior has its own
+address space, also an inferior number.  The source file attribute has
+as many directory components as possible, retrieved from the debug
+information, and in absolute form if possible, but it may also be in
+relative form.
+
+On the other hand, a @dfn{location specification} (a.k.a.@:
+@dfn{location spec}) is a way to find or refer to the concrete code
+locations in the program.  A location spec serves as a blueprint, and
+@value{GDBN} resolves the spec to actual code locations in your
+program by using the source and debug information.
+
+The location spec may be incomplete, and @value{GDBN} will do its best
+to find all the locations in the program that match it.
+
+For example, a location spec may just indicate a line number and a
+source filename with no directory components, or even not specify a
+filename at all, just a line number.  To differentiate between files
+with the same base name, the spec may prepend as many directories as
+is necessary to uniquely identify the desired file.
+
+Or, the spec may indicate a simple function name instead of a
+fully-qualified and prototyped function name (e.g., @code{func}
+instead of @code{A::func(int)}).  To differentiate between functions
+with the same name, the spec may prepend as many class and namespace
+names as is necessary to uniquely identify the desired function,
+and/or it may specify the function parameters as well.  In addition,
+the spec may indicate that the specified function name should be
+interpreted as a fully-qualified name.
+
+You may not have debug info for some of the instructions in the
+program, so a resolved code location that itself points to such code
+will be incomplete and be missing some attributes, such as the source
+file and line number, and sometimes even function names.  Such an
+incomplete code location is only usable in contexts that work with
+addresses and/or function names.  Some commands can only work with
+complete code locations.
+
+Here are examples of typical situations that result in a location spec
+matching multiple concrete code locations in your program:
+
+@itemize @bullet
+@item
+The location spec specifies a function name, and multiple functions in
+the program may have the same name.
+
+@item
+The location spec specifies a source file name, and multiple source
+files in the program share the same name.
+
+@item
+For a C@t{++} constructor, the @value{NGCC} compiler generates several
+instances of the function body, used in different cases.
+
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to several
+places where that function is inlined.
+@end itemize
+
+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
+
+The act of finding all the actual code locations that match the user
+input is called @dfn{resolving the location spec}.  The code locations
+that @value{GDBN} finds are the @dfn{resolved code locations}.
+
+If @value{GDBN} cannot find any code location that matches the user
+input, it is said that @value{GDBN} could not resolve the location
+spec.
+
+Locations may be specified using three different formats: linespec
+locations, explicit locations, or address locations.
 
 @menu
 * Linespec Locations::                Linespec locations
@@ -9270,12 +9365,18 @@ Alternatively, there are several ways to specify what part of the file you
 want to print if you want to see other parts of the program:
 
 @table @code
-@item edit @var{location}
-Edit the source file specified by @code{location}.  Editing starts at
-that @var{location}, e.g., at the specified source line of the
-specified file.  @xref{Specify Location}, for all the possible forms
-of the @var{location} argument; here are the forms of the @code{edit}
-command most commonly used:
+@item edit @var{locspec}
+Edit the source file of the code location that results from resolving
+@code{locspec}.  Editing starts at the source file and source line
+@code{locspec} resolves to.
+@xref{Location Specifications}, for all the possible forms of the
+@var{locspec} argument.
+
+If @code{locspec} resolves to more than one source line in your
+program, then the command prints the list of resolved source lines and
+does not proceed with the editing.
+
+Here are the forms of the @code{edit} command most commonly used:
 
 @table @code
 @item edit @var{number}
@@ -9655,11 +9756,13 @@ well as hex.
 @table @code
 @kindex info line
 @item info line
-@itemx info line @var{location}
-Print the starting and ending addresses of the compiled code for
-source line @var{location}.  You can specify source lines in any of
-the ways documented in @ref{Specify Location}.  With no @var{location}
-information about the current source line is printed.
+@itemx info line @var{locspec}
+Print the starting and ending addresses of the compiled code for the
+source lines of the code locations that result from resolving
+@var{locspec}.  @xref{Location Specifications}, for the various forms
+of @var{locspec}.
+With no @var{locspec}, information about the current source line is
+printed.
 @end table
 
 For example, we can use @code{info line} to discover the location of
@@ -9674,8 +9777,9 @@ Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \
 
 @noindent
 @cindex code address and its source line
-We can also inquire (using @code{*@var{addr}} as the form for
-@var{location}) what source line covers a particular address:
+We can also inquire, using @code{*@var{addr}} as the form for
+@var{locspec}, what source line covers a particular address
+@var{addr}:
 @smallexample
 (@value{GDBP}) info line *0x63ff
 Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
@@ -9883,10 +9987,12 @@ Dump of assembler code from 0x400281 to 0x40028b:
 End of assembler dump.
 @end smallexample
 
-Addresses cannot be specified as a location (@pxref{Specify Location}).
-So, for example, if you want to disassemble function @code{bar}
-in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
-and not @samp{disassemble foo.c:bar}.
+Note that the @samp{disassemble} command's address arguments are
+specified using expressions in your programming language
+(@pxref{Expressions, ,Expressions}), not location specs
+(@pxref{Location Specifications}).  So, for example, if you want to
+disassemble function @code{bar} in file @file{foo.c}, you must type
+@samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}.
 
 Some architectures have more than one commonly-used set of instruction
 mnemonics or other syntax.
@@ -14172,10 +14278,11 @@ argument processing and the beginning of @var{macro} for non C-like macros where
 the macro may begin with a hyphen.
 
 @kindex info macros
-@item info macros @var{location}
-Show all macro definitions that are in effect at the location specified
-by @var{location},  and describe the source location or compiler
-command-line where those definitions were established.
+@item info macros @var{locspec}
+Show all macro definitions that are in effect at the source line of
+the code location that results from resolving @var{locspec}, and
+describe the source location or compiler command-line where those
+definitions were established.
 
 @kindex macro define
 @cindex user-defined macros
@@ -14477,10 +14584,10 @@ conditions and actions.
 @table @code
 @cindex set tracepoint
 @kindex trace
-@item trace @var{location}
+@item trace @var{locspec}
 The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be any valid location.
-@xref{Specify Location}.  The @code{trace} command defines a tracepoint,
+Its argument @var{locspec} can be any valid location specification.
+@xref{Location Specifications}.  The @code{trace} command defines a tracepoint,
 which is a point in the target program where the debugger will briefly stop,
 collect some data, and then allow the program to continue.  Setting a tracepoint
 or changing its actions takes effect immediately if the remote stub
@@ -14516,14 +14623,14 @@ Here are some examples of using the @code{trace} command:
 @noindent
 You can abbreviate @code{trace} as @code{tr}.
 
-@item trace @var{location} if @var{cond}
+@item trace @var{locspec} if @var{cond}
 Set a tracepoint with condition @var{cond}; evaluate the expression
 @var{cond} each time the tracepoint is reached, and collect data only
 if the value is nonzero---that is, if @var{cond} evaluates as true.
 @xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
 information on tracepoint conditions.
 
-@item ftrace @var{location} [ if @var{cond} ]
+@item ftrace @var{locspec} [ if @var{cond} ]
 @cindex set fast tracepoint
 @cindex fast tracepoints, setting
 @kindex ftrace
@@ -14555,20 +14662,21 @@ sudo sysctl -w vm.mmap_min_addr=32768
 which sets the low address to 32K, which leaves plenty of room for
 trampolines.  The minimum address should be set to a page boundary.
 
-@item strace @var{location} [ if @var{cond} ]
+@item strace [@var{locspec} | -m @var{marker}] [ if @var{cond} ]
 @cindex set static tracepoint
 @cindex static tracepoints, setting
 @cindex probe static tracepoint marker
 @kindex strace
 The @code{strace} command sets a static tracepoint.  For targets that
 support it, setting a static tracepoint probes a static
-instrumentation point, or marker, found at @var{location}.  It may not
-be possible to set a static tracepoint at the desired location, in
-which case the command will exit with an explanatory message.
+instrumentation point, or marker, found at the code locations that
+result from resolving @var{locspec}.  It may not be possible to set a
+static tracepoint at the desired code location, in which case the
+command will exit with an explanatory message.
 
 @value{GDBN} handles arguments to @code{strace} exactly as for
 @code{trace}, with the addition that the user can also specify
-@code{-m @var{marker}} as @var{location}.  This probes the marker
+@code{-m @var{marker}} instead of a location spec.  This probes the marker
 identified by the @var{marker} string identifier.  This identifier
 depends on the static tracepoint backend library your program is
 using.  You can find all the marker identifiers in the @samp{ID} field
@@ -17439,9 +17547,9 @@ peculiarities and holes to be aware of.
 
 @itemize @bullet
 @item
-Linespecs (@pxref{Specify Location}) are never relative to the current
-crate.  Instead, they act as if there were a global namespace of
-crates, somewhat similar to the way @code{extern crate} behaves.
+Linespecs (@pxref{Location Specifications}) are never relative to the
+current crate.  Instead, they act as if there were a global namespace
+of crates, somewhat similar to the way @code{extern crate} behaves.
 
 That is, if @value{GDBN} is stopped at a breakpoint in a function in
 crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
@@ -18762,15 +18870,14 @@ information.
 
 Flags @code{-c} and @code{-s} cannot be used together.
 
-@item break @var{location} task @var{taskno}
-@itemx break @var{location} task @var{taskno} if @dots{}
+@item break @var{locspec} task @var{taskno}
+@itemx break @var{locspec} task @var{taskno} if @dots{}
 @cindex breakpoints and tasks, in Ada
 @cindex task breakpoints, in Ada
 @kindex break @dots{} task @var{taskno}@r{ (Ada)}
 These commands are like the @code{break @dots{} thread @dots{}}
-command (@pxref{Thread Stops}).  The
-@var{location} argument specifies source lines, as described
-in @ref{Specify Location}.
+command (@pxref{Thread Stops}).  @xref{Location Specifications}, for
+the various forms of @var{locspec}.
 
 Use the qualifier @samp{task @var{taskno}} with a breakpoint command
 to specify that you only want @value{GDBN} to stop the program when a
@@ -19531,12 +19638,11 @@ These commands can be used to enable or disable type printers.
 
 @kindex info scope
 @cindex local variables
-@item info scope @var{location}
-List all the variables local to a particular scope.  This command
-accepts a @var{location} argument---a function name, a source line, or
-an address preceded by a @samp{*}, and prints all the variables local
-to the scope defined by that location.  (@xref{Specify Location}, for
-details about supported forms of @var{location}.)  For example:
+@item info scope @var{locspec}
+List all the variables local to the lexical scope of the code location
+that results from resolving @var{locspec}.  @xref{Location
+Specifications}, for details about supported forms of @var{locspec}.
+For example:
 
 @smallexample
 (@value{GDBP}) @b{info scope command_line_handler}
@@ -20124,23 +20230,27 @@ an address of your own choosing, with the following commands:
 @table @code
 @kindex jump
 @kindex j @r{(@code{jump})}
-@item jump @var{location}
-@itemx j @var{location}
-Resume execution at @var{location}.  Execution stops again immediately
-if there is a breakpoint there.  @xref{Specify Location}, for a description
-of the different forms of @var{location}.  It is common
-practice to use the @code{tbreak} command in conjunction with
-@code{jump}.  @xref{Set Breaks, ,Setting Breakpoints}.
+@item jump @var{locspec}
+@itemx j @var{locspec}
+Resume execution at the address of the code location that results from
+resolving @var{locspec}.
+@xref{Location Specifications}, for a description of the different
+forms of @var{locspec}.  If @var{locspec} resolves to more than one
+address, the command aborts before jumping.
+Execution stops again immediately if there is a breakpoint there.  It
+is common practice to use the @code{tbreak} command in conjunction
+with @code{jump}.  @xref{Set Breaks, ,Setting Breakpoints}.
 
 The @code{jump} command does not change the current stack frame, or
 the stack pointer, or the contents of any memory location or any
-register other than the program counter.  If @var{location} is 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.  However, even bizarre results are predictable if you are
-well acquainted with the machine-language code of your program.
+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 jump address is not in the
+function currently executing.  However, even bizarre results are
+predictable if you are well acquainted with the machine-language code
+of your program.
 @end table
 
 On many systems, you can get much the same effect as the @code{jump}
@@ -25365,15 +25475,16 @@ use the @code{break-range} command.
 
 @table @code
 @kindex break-range
-@item break-range @var{start-location}, @var{end-location}
-Set a breakpoint for an address range given by
-@var{start-location} and @var{end-location}, which can specify a function name,
-a line number, an offset of lines from the current line or from the start
-location, or an address of an instruction (see @ref{Specify Location},
-for a list of all the possible ways to specify a @var{location}.)
-The breakpoint will stop execution of the inferior whenever it
-executes an instruction at any address within the specified range,
-(including @var{start-location} and @var{end-location}.)
+@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}.
 
 @kindex set powerpc
 @item set powerpc soft-float
@@ -31192,11 +31303,11 @@ N.A.
 @smallexample
  -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ]
     [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ]
-    [ -p @var{thread-id} ] [ @var{location} ]
+    [ -p @var{thread-id} ] [ @var{locspec} ]
 @end smallexample
 
 @noindent
-If specified, @var{location}, can be one of:
+If specified, @var{locspec}, can be one of:
 
 @table @var
 @item linespec location
@@ -31235,10 +31346,10 @@ Insert a temporary breakpoint.
 @item -h
 Insert a hardware breakpoint.
 @item -f
-If @var{location} cannot be parsed (for example if it
+If @var{locspec} cannot be resolved (for example if it
 refers to unknown files or functions), create a pending
-breakpoint. Without this flag, @value{GDBN} will report
-an error, and won't create a breakpoint, if @var{location}
+breakpoint.  Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{locspec}
 cannot be parsed.
 @item -d
 Create a disabled breakpoint.
@@ -31320,12 +31431,12 @@ times="0"@}]@}
 @smallexample
  -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ]
     [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ]
-    [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
+    [ -p @var{thread-id} ] [ @var{locspec} ] [ @var{format} ]
     [ @var{argument} ]
 @end smallexample
 
 @noindent
-If supplied, @var{location} and @code{--qualified} may be specified
+If supplied, @var{locspec} and @code{--qualified} may be specified
 the same way as for the @code{-break-insert} command.
 @xref{-break-insert}.
 
@@ -31335,10 +31446,10 @@ The possible optional parameters of this command are:
 @item -t
 Insert a temporary breakpoint.
 @item -f
-If @var{location} cannot be parsed (for example, if it
+If @var{locspec} cannot be parsed (for example, if it
 refers to unknown files or functions), create a pending
 breakpoint.  Without this flag, @value{GDBN} will report
-an error, and won't create a breakpoint, if @var{location}
+an error, and won't create a breakpoint, if @var{locspec}
 cannot be parsed.
 @item -d
 Create a disabled breakpoint.
@@ -32551,12 +32662,12 @@ fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@}
 @subsubheading Synopsis
 
 @smallexample
- -exec-jump @var{location}
+ -exec-jump @var{locspec}
 @end smallexample
 
-Resumes execution of the inferior program at the location specified by
-parameter.  @xref{Specify Location}, for a description of the
-different forms of @var{location}.
+Resumes execution of the inferior program at the address to
+which @var{locspec} resolves.  @xref{Location Specifications},
+for a description of the different forms of @var{locspec}.
 
 @subsubheading @value{GDBN} Command
 
@@ -32870,13 +32981,13 @@ fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
 @subsubheading Synopsis
 
 @smallexample
- -exec-until [ @var{location} ]
+ -exec-until [ @var{locspec} ]
 @end smallexample
 
-Executes the inferior until the @var{location} specified in the
-argument is reached.  If there is no argument, the inferior executes
-until a source line greater than the current one is reached.  The
-reason for stopping in this case will be @samp{location-reached}.
+Executes the inferior until it reaches the address to which
+@var{locspec} resolves.  If there is no argument, the inferior
+executes until it reaches a source line greater than the current one.
+The reason for stopping in this case will be @samp{location-reached}.
 
 @subsubheading @value{GDBN} Command
 
@@ -34935,7 +35046,7 @@ next trace frame that corresponds to a tracepoint at an address outside
 the specified range.  Both bounds are considered to be inside the range.
 
 @item line
-Line specification is required as parameter.  @xref{Specify Location}.
+Location specification is required as parameter.  @xref{Location Specifications}.
 Finds next trace frame that corresponds to a tracepoint at
 the specified location.
 
@@ -39438,8 +39549,8 @@ messages, see @ref{Debugging Output}.)
 @table @code
 @kindex maint agent
 @kindex maint agent-eval
-@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}
-@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression}
+@item maint agent @r{[}-at @var{linespec}@r{,}@r{]} @var{expression}
+@itemx maint agent-eval @r{[}-at @var{linespec}@r{,}@r{]} @var{expression}
 Translate the given @var{expression} into remote agent bytecodes.
 This command is useful for debugging the Agent Expression mechanism
 (@pxref{Agent Expressions}).  The @samp{agent} version produces an
@@ -39450,7 +39561,9 @@ globb} will include bytecodes to record four bytes of memory at each
 of the addresses of @code{globa} and @code{globb}, while discarding
 the result of the addition, while an evaluation expression will do the
 addition and return the sum.
-If @code{-at} is given, generate remote agent bytecode for @var{location}.
+If @code{-at} is given, generate remote agent bytecode for all the
+addresses to which @var{linespec} resolves (@pxref{Linespec
+Locations}).
 If not, generate remote agent bytecode for current frame PC address.
 
 @kindex maint agent-printf
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 3c517230929..63916eed181 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1965,7 +1965,7 @@ This constant means that filename completion should be performed.
 
 @item COMPLETE_LOCATION
 This constant means that location completion should be done.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @item COMPLETE_COMMAND
 This constant means that completion should examine @value{GDBN}
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index cb5283e03c0..f933c7d30c9 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -577,7 +577,8 @@ either @code{None} or another tuple that contains all the locations
 that match the expression represented as @code{gdb.Symtab_and_line}
 objects (@pxref{Symbol Tables In Python}).  If @var{expression} is
 provided, it is decoded the way that @value{GDBN}'s inbuilt
-@code{break} or @code{edit} commands do (@pxref{Specify Location}).
+@code{break} or @code{edit} commands do (@pxref{Location
+Specifications}).
 @end defun
 
 @defun gdb.prompt_hook (current_prompt)
@@ -4186,7 +4187,7 @@ This constant means that filename completion should be performed.
 @vindex COMPLETE_LOCATION
 @item gdb.COMPLETE_LOCATION
 This constant means that location completion should be done.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @vindex COMPLETE_COMMAND
 @item gdb.COMPLETE_COMMAND

base-commit: 09cb5e2312e299bd3e362f8acb070560a06d156a
-- 
2.36.0

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

[Eli Zaretskii]

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

[PATCH] Improve clear command's documentation

[Pedro Alves]

Handling this one issue at a time.

On 2022-05-30 17:15, Eli Zaretskii wrote:
>> 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?

How about this, basically a complete rewrite of the clear command's
documentation:

From 2efda4c0040ba088da5e0e03b5afdd2b0248ec5b Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 31 May 2022 10:54:17 +0100
Subject: [PATCH] Improve clear command's documentation

Change-Id: I9440052fd28f795d6f7c93a4576beadd21f28885
---
 gdb/doc/gdb.texinfo | 46 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 3cf4e2c73c0..b497901473d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5443,21 +5443,47 @@ the innermost frame is selected, this is a good way to delete a
 breakpoint where your program just stopped.
 
 @item clear @var{locspec}
-Delete breakpoints with code locations that match @var{locspec}.
-@xref{Location Specifications}, for the various forms of
-@var{locspec}; the most useful ones are listed below:
+Delete breakpoints with code locations that match either address,
+source file and line number, or function name specified in
+@var{locspec}.  @xref{Location Specifications}, for the various forms
+of @var{locspec}.
+
+The location spec to breakpoint code location matching is done in the
+following ways, depending on what the location spec specifies:
 
 @table @code
-@item clear @var{function}
-@itemx clear @var{filename}:@var{function}
-Delete any breakpoints set at entry to the named @var{function}.
+@item if @var{locspec} specifies a line number
+If @var{locspec} specifies a line number, such as e.g., with one of
+the following forms:
 
-@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}.
+@table @code
+@item @code{clear @var{linenum}}
+@item @code{clear @var{filename}:@var{linenum}}
+@item @code{clear -line @var{linenum}}
+@item @code{clear -source @var{filename} -line @var{linenum}}
 @end table
 
+@noindent
+then the command deletes any breakpoints with a code location set at
+or within the code of the specified @var{linenum} of files that match
+the specified @var{filename}, or of files that match the current
+source file, if no file name was specified.
+
+@item if @var{locspec} specifies an address
+If @var{locspec} specifies an address, with @code{clear *@var{addr}},
+then the command deletes any breakpoints with a code location set at
+the given address.
+
+@item if @var{locspec} specifies a function
+If @var{locspec} specifies a function, such as with @code{clear
+@var{function}} or @code{clear -function @var{function}}, then the
+command deletes any breakpoints with a code location set at entry to a
+function whose name matches @var{function}.
+@end table
+
+Ambiguity in file name and function name matching can be resolved as
+described in @ref{Location Specifications}.
+
 @cindex delete breakpoints
 @kindex delete
 @kindex d @r{(@code{delete})}

base-commit: 5541bfdc97936581c0ead915e9117e22f21bdb12
-- 
2.36.0

[PATCH] Explicitly mention yet-unloaded shared libraries in location spec examples

[Pedro Alves]

On 2022-05-30 17:15, Eli Zaretskii wrote:
>>>> +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?
> 

Maybe.  How about this.

From 4fc52ddcdf871c365a3abc6f681fb79ac473728a Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 31 May 2022 12:06:50 +0100
Subject: [PATCH] Explicitly mention yet-unloaded shared libraries in location
 spec examples

Change-Id: I05639ddb3bf620c7297b57ed286adc3aa926b7b6
---
 gdb/doc/gdb.texinfo | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b497901473d..7886f3eb3dd 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9150,11 +9150,13 @@ 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.
+functions in the program with that name, or they only exist in a
+yet-unloaded shared library.
 
 @item
 The location spec specifies a source file name, and there are no
-source files in the program with that name.
+source files in the program with that name, or they only exist in a
+yet-unloaded shared library.
 
 @item
 The location spec specifies both a source file name and a source line

base-commit: 5541bfdc97936581c0ead915e9117e22f21bdb12
prerequisite-patch-id: 02daf94a0a458024d52b3a10e80608fd3e26738a
-- 
2.36.0

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

[Pedro Alves]

On 2022-05-30 17:15, Eli Zaretskii wrote:
>>>> +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".
> 

Dunno, that just repeats the exact same text in previous sentence.
I think the current text says the same, and reads better for avoiding
the duplication.

[PATCH] Improve break-range's documentation

[Pedro Alves]

On 2022-05-30 17:15, Eli Zaretskii wrote:
>>>> +@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.

How about this:

From 40c64ac6d4d7d6caef7156ceb31387b343eef324 Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 31 May 2022 12:18:49 +0100
Subject: [PATCH] Improve break-range's documentation

Change-Id: Iac26e1d2e7d8dc8a7d9516e6bdcc5c3fc4af45c8
---
 gdb/doc/gdb.texinfo | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7886f3eb3dd..c2fb78f933f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -25496,7 +25496,7 @@ about the @code{mask} argument in @ref{Set Watchpoints}.
 PowerPC embedded processors support hardware accelerated
 @dfn{ranged breakpoints}.  A ranged breakpoint stops execution of
 the inferior whenever it executes an instruction at any address within
-the range it specifies.  To set a ranged breakpoint in @value{GDBN},
+the range it was set at.  To set a ranged breakpoint in @value{GDBN},
 use the @code{break-range} command.
 
 @value{GDBN} provides the following PowerPC-specific commands:
@@ -25507,12 +25507,14 @@ use the @code{break-range} command.
 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}.
+specs.  @value{GDBN} resolves both @var{start-locspec} and
+@var{end-locspec}, and uses the addresses of the resolved code
+locations as start and end addresses of the range to break at.  If
+either @var{start-locspec} or @var{end-locspec} resolve to multiple
+code locations 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
+between the start and end addresses, inclusive.
 
 @kindex set powerpc
 @item set powerpc soft-float

-- 
2.36.0

Re: [PATCH] Explicitly mention yet-unloaded shared libraries in location spec examples

[Eli Zaretskii]

> Date: Tue, 31 May 2022 12:13:54 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> > Shouldn't this mention explicitly the frequent situation where the
> > location specifies something in a yet-unloaded shared library?
> > 
> 
> Maybe.  How about this.

LGTM, thanks.

Re: [PATCH] Improve break-range's documentation

[Eli Zaretskii]

> Date: Tue, 31 May 2022 12:31:40 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
>  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}.
> +specs.  @value{GDBN} resolves both @var{start-locspec} and
> +@var{end-locspec}, and uses the addresses of the resolved code
> +locations as start and end addresses of the range to break at.  If
> +either @var{start-locspec} or @var{end-locspec} resolve to multiple
> +code locations 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
> +between the start and end addresses, inclusive.

This is fine, but please swap the last sentence with the one before
it, since, as written, the penultimate sentence breaks the logic of
the description of what the command does by describing an exceptional
situation too early.

Thanks.

Re: [PATCH] Improve break-range's documentation

[Pedro Alves]

On 2022-05-31 12:55, Eli Zaretskii wrote:
>> Date: Tue, 31 May 2022 12:31:40 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>  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}.
>> +specs.  @value{GDBN} resolves both @var{start-locspec} and
>> +@var{end-locspec}, and uses the addresses of the resolved code
>> +locations as start and end addresses of the range to break at.  If
>> +either @var{start-locspec} or @var{end-locspec} resolve to multiple
>> +code locations 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
>> +between the start and end addresses, inclusive.
> 
> This is fine, but please swap the last sentence with the one before
> it, since, as written, the penultimate sentence breaks the logic of
> the description of what the command does by describing an exceptional
> situation too early.

The way it is written made sense to me, as we first say GDB resolves
the locspecs, and then the exceptional situation is exactly about the
resolving we just described.

Anyhow, I'll change it and merge.

Re: [PATCH] Improve break-range's documentation

[Eli Zaretskii]

> Date: Tue, 31 May 2022 13:03:30 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> >> +specs.  @value{GDBN} resolves both @var{start-locspec} and
> >> +@var{end-locspec}, and uses the addresses of the resolved code
> >> +locations as start and end addresses of the range to break at.  If
> >> +either @var{start-locspec} or @var{end-locspec} resolve to multiple
> >> +code locations 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
> >> +between the start and end addresses, inclusive.
> > 
> > This is fine, but please swap the last sentence with the one before
> > it, since, as written, the penultimate sentence breaks the logic of
> > the description of what the command does by describing an exceptional
> > situation too early.
> 
> The way it is written made sense to me, as we first say GDB resolves
> the locspecs, and then the exceptional situation is exactly about the
> resolving we just described.

IME, it is usually better to describe what the command does normally,
and only after that what it does in an exceptional case.  Users are
usually after the former.

> Anyhow, I'll change it and merge.

Thanks.

Re: [PATCH] Improve clear command's documentation

[Eli Zaretskii]

> Date: Tue, 31 May 2022 12:05:53 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> How about this, basically a complete rewrite of the clear command's
> documentation:

Thanks, the idea to rewrite it is indeed a good one.  But the actual
text IMO came out highly repetitive, and has several markup issues.
Rather than commenting on each issue, I suggest the following reworded
text:

 @item clear @var{locspec}
 Delete any breakpoint whose code location corresponds to
 @var{locspec}.  @xref{Location Specifications}, for the various forms
 of  @var{locspec}.  Which code locations correspond to @var{locspec}
 depends on the form used in the location specifications @var{locspec}:

 @table @code
 @item @var{linenum}
 @itemx @var{filename}:@var{linenum}
 @itemx -line @var{linenum}
 @itemx -source @var{filename} -line @var{linenum}
 If @var{locspec} specifies a line number, with or without a file
 name, the command deletes any breakpoint whose code location is
 at or within the specified line @var{linenum} in files that match the
 specified @var{filename}.  If @var{filename} is omitted, it defaults
 to the current source file.

 @item *@var{address}
 If @var{locspec} specifies an address, the command deletes any
 breakpoint whose code location is at the given @var{address}.

 @item @var{function}
 @itemx -function @var{function}
 If @var{locspec} specifies a function, the command deletes any
 breakpoint whose code location is at the entry to any function whose
 name matches @var{function}.
 @end table

 Ambiguity in names of files and functions can be resolved as
 described in @ref{Location Specifications}.

WDYT?

Re: [PATCH] Improve clear command's documentation

[Pedro Alves]

On 2022-05-31 13:36, Eli Zaretskii wrote:
>> Date: Tue, 31 May 2022 12:05:53 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>> How about this, basically a complete rewrite of the clear command's
>> documentation:
> 
> Thanks, the idea to rewrite it is indeed a good one.  But the actual
> text IMO came out highly repetitive, and has several markup issues.
> Rather than commenting on each issue, I suggest the following reworded
> text:
> 
>  @item clear @var{locspec}
>  Delete any breakpoint whose code location corresponds to
>  @var{locspec}.  @xref{Location Specifications}, for the various forms
>  of  @var{locspec}.  Which code locations correspond to @var{locspec}
>  depends on the form used in the location specifications @var{locspec}:
> 
>  @table @code
>  @item @var{linenum}
>  @itemx @var{filename}:@var{linenum}
>  @itemx -line @var{linenum}
>  @itemx -source @var{filename} -line @var{linenum}
>  If @var{locspec} specifies a line number, with or without a file
>  name, the command deletes any breakpoint whose code location is
>  at or within the specified line @var{linenum} in files that match the
>  specified @var{filename}.  If @var{filename} is omitted, it defaults
>  to the current source file.
> 
>  @item *@var{address}
>  If @var{locspec} specifies an address, the command deletes any
>  breakpoint whose code location is at the given @var{address}.
> 
>  @item @var{function}
>  @itemx -function @var{function}
>  If @var{locspec} specifies a function, the command deletes any
>  breakpoint whose code location is at the entry to any function whose
>  name matches @var{function}.
>  @end table
> 
>  Ambiguity in names of files and functions can be resolved as
>  described in @ref{Location Specifications}.
> 
> WDYT?
> 

I like this a lot.  Will you merge it, or shall I?

Re: [PATCH] Improve clear command's documentation

[Eli Zaretskii]

> Date: Tue, 31 May 2022 14:04:00 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> > WDYT?
> > 
> 
> I like this a lot.  Will you merge it, or shall I?

I'd prefer that you did, if you don't mind, so that all the changes
would be together, or close.

Thanks.

Re: [PATCH] Improve clear command's documentation

[Pedro Alves]

On 2022-05-31 14:42, Eli Zaretskii wrote:
>> Date: Tue, 31 May 2022 14:04:00 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>> WDYT?
>>>
>>
>> I like this a lot.  Will you merge it, or shall I?
> 
> I'd prefer that you did, if you don't mind, so that all the changes
> would be together, or close.

Done.  Just with one small tweak -- your text used wording that assumes a breakpoint
only has one location, "deletes any breakpoint whose code location is at", etc.
I tweaked it to say "any breakpoint with a code location that is at", etc.  

If you have a multi location breakpoint, and you specify one of the locations,
gdb really deletes the whole breakpoint:

(top-gdb) info breakpoints 3
Num     Type           Disp Enb Address            What
3       breakpoint     keep y   <MULTIPLE>         
3.1                         y   0x00000000000ed06c in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:25
3.2                         y   0x000000000086aa66 in selftests::string_view::capacity_1::main() at /home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/capacity/1.cc:167
3.3                         y   0x000000000086ae85 in selftests::string_view::cons_1::main() at /home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/1.cc:62
...
(top-gdb) clear *0x00000000000ed06c
Deleted breakpoint 3 
(top-gdb)

Re: [PATCH] Improve clear command's documentation

[Eli Zaretskii]

> Date: Tue, 31 May 2022 15:47:20 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> Done.  Just with one small tweak -- your text used wording that assumes a breakpoint
> only has one location, "deletes any breakpoint whose code location is at", etc.
> I tweaked it to say "any breakpoint with a code location that is at", etc.  

Right.  I copied your original text too faithfully ;-)

RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Eli Zaretskii]

> Date: Mon, 30 May 2022 15:44:59 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> From: Pedro Alves <pedro@palves.net>
> Date: Tue, 17 May 2022 13:12:04 +0100
> Subject: [PATCH] gdb/manual: Introduce location specs
> 
> The current "Specify Location" section of the GDB manual starts with:
> 
>  "Several @value{GDBN} commands accept arguments that specify a location
>  of your program's code."

I'd like to propose slight rewording and rearrangement of the section
which you modified with that commit.  Below please find: (a) the full
modified text of the section, and (b) diffs against the current master
branch.

WDYT?

----------------------------------------------------------------------
@node Location Specifications
@section Location Specifications
@cindex specifying location
@cindex locspec
@cindex source location
@cindex code location

@cindex location spec
Several @value{GDBN} commands accept arguments that specify a location
or locations of your program's code.  Since @value{GDBN} is a
source-level debugger, a location specification usually indicates some
line in some source file, but it can also do that indirectly, by
specifying a function name, an address, a label, etc.  The different
forms of specifying a location that @value{GDBN} recognizes are
collectively known as forms of @dfn{location specification}, or
@dfn{location spec}.  This section documents the forms of specifying
locations that @value{GDBN} recognizes.

@cindex location resolution
@cindex resolution of location spec
When you specify a location, @value{GDBN} needs to find the place in
your program, known as @dfn{code location}, that corresponds to the
given location spec.  We call this process of finding actual code
locations corresponding to a location spec @dfn{location resolution}.

A concrete code location in your program is uniquely identifiable by a
set of several attributes: its source line number, the name of its
source file, the fully-qualified and prototyped function in which it
is defined, and an instruction address.  Because each inferior has its
own address space, the inferior number is also a necessary part of
these attributes.  By contrast, location specs you type will many
times omit some of these attributes.  For example, it is customary to
specify just the source line number to mean a line in the current
source file, or specify just the basename of the file, omitting its
directories.  In other words, a location spec is usually incomplete, a
kind of blueprint, and @value{GDBN} needs to complete the missing
attributes by using the implied defaults, and by considering the
source code and the debug information available to it.  This is what
location resolution is about.

The resolution of an incomplete location spec can produce more than a
single code location, if the spec doesn't allow distinguishing between
them.  Here are some examples of situations that result in a location
spec matching multiple code locations in your program:

@itemize @bullet
@item
The location spec specifies a function name, and there are several
functions in the program which have that name.  (To distinguish
between them, you can specify a fully-qualified and prototyped
function name, such as @code{A::func(int)} instead of just
@code{func}.)

@item
The location spec specifies a source file name, and there are several
source files in the program that share the same name, for example
several files with the same basename in different subdirectories.  (To
distinguish between them, specify enough leading directories with the
file name.)

@item
For a C@t{++} constructor, the @value{NGCC} compiler generates several
instances of the function body, used in different cases, but their
source-level names are identical, unless you qualify them.

@item
For a C@t{++} template function, a given line in the function can
correspond to any number of instantiations.

@item
For an inlined function, a given source line can correspond to several
actual code locations with that function's inlined code.
@end itemize

Resolution of a location spec can also fail to produce a complete code
location, or even fail to produce any code location.  Here are some
examples of such situations:

@itemize @bullet
@item
Some parts of the program lack detailed enough debug info, so the
resolved code location lacks some attributes, like source file name
and line number, leaving just the instruction address and perhaps also
a function name.  Such an incomplete code location is only usable in
contexts that work with addresses and/or function names.  Some
commands can only work with complete code locations.

@item
The location spec specifies a function name, and there are no
functions in the program by that name, or they only exist in a
yet-unloaded shared library.

@item
The location spec specifies a source file name, and there are no
source files in the program by that name, or they only exist in a
yet-unloaded shared library.

@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

Locations may be specified using three different formats: linespec
locations, explicit locations, or address locations.  The following
subsections describe these formats.

@menu
* Linespec Locations::                Linespec locations
* Explicit Locations::                Explicit locations
* Address Locations::                 Address locations
@end menu

----------------------------------------------------------------------

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5f09f3a..3395735 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9056,73 +9056,67 @@
 @node Location Specifications
 @section Location Specifications
 @cindex specifying location
-@cindex location spec
 @cindex locspec
 @cindex source location
 @cindex code location
 
+@cindex location spec
 Several @value{GDBN} commands accept arguments that specify a location
 or locations of your program's code.  Since @value{GDBN} is a
 source-level debugger, a location specification usually indicates some
-line in the source code, but it can also indicate a function name, an
-address, a label, and more.
+line in some source file, but it can also do that indirectly, by
+specifying a function name, an address, a label, etc.  The different
+forms of specifying a location that @value{GDBN} recognizes are
+collectively known as forms of @dfn{location specification}, or
+@dfn{location spec}.  This section documents the forms of specifying
+locations that @value{GDBN} recognizes.
+
+@cindex location resolution
+@cindex resolution of location spec
+When you specify a location, @value{GDBN} needs to find the place in
+your program, known as @dfn{code location}, that corresponds to the
+given location spec.  We call this process of finding actual code
+locations corresponding to a location spec @dfn{location resolution}.
 
 A concrete code location in your program is uniquely identifiable by a
-set of logical attributes.  A line number, the source file the line
-belongs to, the fully-qualified and prototyped function it is defined
-in, and an instruction address.  Because each inferior has its own
-address space, also an inferior number.  The source file attribute has
-as many directory components as possible, retrieved from the debug
-information, and in absolute form if possible, but it may also be in
-relative form.
-
-On the other hand, a @dfn{location specification} (a.k.a.@:
-@dfn{location spec}) is a way to find or refer to the concrete code
-locations in the program.  A location spec serves as a blueprint, and
-@value{GDBN} resolves the spec to actual code locations in your
-program by using the source and debug information.
-
-The location spec may be incomplete, and @value{GDBN} will do its best
-to find all the locations in the program that match it.
-
-For example, a location spec may just indicate a line number and a
-source filename with no directory components, or even not specify a
-filename at all, just a line number.  To differentiate between files
-with the same base name, the spec may prepend as many directories as
-is necessary to uniquely identify the desired file.
-
-Or, the spec may indicate a simple function name instead of a
-fully-qualified and prototyped function name (e.g., @code{func}
-instead of @code{A::func(int)}).  To differentiate between functions
-with the same name, the spec may prepend as many class and namespace
-names as is necessary to uniquely identify the desired function,
-and/or it may specify the function parameters as well.  In addition,
-the spec may indicate that the specified function name should be
-interpreted as a fully-qualified name.
-
-You may not have debug info for some of the instructions in the
-program, so a resolved code location that itself points to such code
-will be incomplete and be missing some attributes, such as the source
-file and line number, and sometimes even function names.  Such an
-incomplete code location is only usable in contexts that work with
-addresses and/or function names.  Some commands can only work with
-complete code locations.
-
-Here are examples of typical situations that result in a location spec
-matching multiple concrete code locations in your program:
+set of several attributes: its source line number, the name of its
+source file, the fully-qualified and prototyped function in which it
+is defined, and an instruction address.  Because each inferior has its
+own address space, the inferior number is also a necessary part of
+these attributes.  By contrast, location specs you type will many
+times omit some of these attributes.  For example, it is customary to
+specify just the source line number to mean a line in the current
+source file, or specify just the basename of the file, omitting its
+directories.  In other words, a location spec is usually incomplete, a
+kind of blueprint, and @value{GDBN} needs to complete the missing
+attributes by using the implied defaults, and by considering the
+source code and the debug information available to it.  This is what
+location resolution is about.
+
+The resolution of an incomplete location spec can produce more than a
+single code location, if the spec doesn't allow distinguishing between
+them.  Here are some examples of situations that result in a location
+spec matching multiple code locations in your program:
 
 @itemize @bullet
 @item
-The location spec specifies a function name, and multiple functions in
-the program may have the same name.
+The location spec specifies a function name, and there are several
+functions in the program which have that name.  (To distinguish
+between them, you can specify a fully-qualified and prototyped
+function name, such as @code{A::func(int)} instead of just
+@code{func}.)
 
 @item
-The location spec specifies a source file name, and multiple source
-files in the program share the same name.
+The location spec specifies a source file name, and there are several
+source files in the program that share the same name, for example
+several files with the same basename in different subdirectories.  (To
+distinguish between them, specify enough leading directories with the
+file name.)
 
 @item
 For a C@t{++} constructor, the @value{NGCC} compiler generates several
-instances of the function body, used in different cases.
+instances of the function body, used in different cases, but their
+source-level names are identical, unless you qualify them.
 
 @item
 For a C@t{++} template function, a given line in the function can
@@ -9130,21 +9124,30 @@
 
 @item
 For an inlined function, a given source line can correspond to several
-places where that function is inlined.
+actual code locations with that function's inlined code.
 @end itemize
 
-And here are examples of typical situations that result in a location
-spec matching no code locations in your program at all:
+Resolution of a location spec can also fail to produce a complete code
+location, or even fail to produce any code location.  Here are some
+examples of such situations:
 
 @itemize @bullet
 @item
+Some parts of the program lack detailed enough debug info, so the
+resolved code location lacks some attributes, like source file name
+and line number, leaving just the instruction address and perhaps also
+a function name.  Such an incomplete code location is only usable in
+contexts that work with addresses and/or function names.  Some
+commands can only work with complete code locations.
+
+@item
 The location spec specifies a function name, and there are no
-functions in the program with that name, or they only exist in a
+functions in the program by that name, or they only exist in a
 yet-unloaded shared library.
 
 @item
 The location spec specifies a source file name, and there are no
-source files in the program with that name, or they only exist in a
+source files in the program by that name, or they only exist in a
 yet-unloaded shared library.
 
 @item
@@ -9154,16 +9157,9 @@
 number.
 @end itemize
 
-The act of finding all the actual code locations that match the user
-input is called @dfn{resolving the location spec}.  The code locations
-that @value{GDBN} finds are the @dfn{resolved code locations}.
-
-If @value{GDBN} cannot find any code location that matches the user
-input, it is said that @value{GDBN} could not resolve the location
-spec.
-
 Locations may be specified using three different formats: linespec
-locations, explicit locations, or address locations.
+locations, explicit locations, or address locations.  The following
+subsections describe these formats.
 
 @menu
 * Linespec Locations::                Linespec locations

Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Pedro Alves]

On 2022-06-01 18:17, Eli Zaretskii wrote:

> ----------------------------------------------------------------------
> @node Location Specifications
> @section Location Specifications
> @cindex specifying location
> @cindex locspec
> @cindex source location
> @cindex code location
> 
> @cindex location spec
> Several @value{GDBN} commands accept arguments that specify a location
> or locations of your program's code.  Since @value{GDBN} is a
> source-level debugger, a location specification usually indicates some
> line in some source file, but it can also do that indirectly, by
> specifying a function name, an address, a label, etc.  The different
> forms of specifying a location that @value{GDBN} recognizes are
> collectively known as forms of @dfn{location specification}, or
> @dfn{location spec}.  This section documents the forms of specifying
> locations that @value{GDBN} recognizes.
> 
> @cindex location resolution
> @cindex resolution of location spec
> When you specify a location, @value{GDBN} needs to find the place in
> your program, known as @dfn{code location}, that corresponds to the
> given location spec.  We call this process of finding actual code
> locations corresponding to a location spec @dfn{location resolution}.
> 
> A concrete code location in your program is uniquely identifiable by a
> set of several attributes: its source line number, the name of its
> source file, the fully-qualified and prototyped function in which it
> is defined, and an instruction address.  Because each inferior has its
> own address space, the inferior number is also a necessary part of
> these attributes.  By contrast, location specs you type will many

I built the manual here with the patch, to read in the html form in the browser,
and found this paragraph very long and dense.  I find it much more readable if we have a
paragraph break here (line break + empty line), before "By contract".  Above we talk
about actual code locations.  And below we talk about location specs.  

If you look for "By contrast" in the manual, you will see that the only two
other instances also start a new text block.

> times omit some of these attributes.  For example, it is customary to
> specify just the source line number to mean a line in the current
> source file, or specify just the basename of the file, omitting its
> directories.  In other words, a location spec is usually incomplete, a
> kind of blueprint, and @value{GDBN} needs to complete the missing
> attributes by using the implied defaults, and by considering the
> source code and the debug information available to it.  This is what
> location resolution is about.
> 



> ----------------------------------------------------------------------
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 5f09f3a..3395735 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -9056,73 +9056,67 @@
>  @node Location Specifications
>  @section Location Specifications
>  @cindex specifying location
> -@cindex location spec
>  @cindex locspec
>  @cindex source location
>  @cindex code location
>  
> +@cindex location spec
>  Several @value{GDBN} commands accept arguments that specify a location
>  or locations of your program's code.  Since @value{GDBN} is a
>  source-level debugger, a location specification usually indicates some
> -line in the source code, but it can also indicate a function name, an
> -address, a label, and more.
> +line in some source file, but it can also do that indirectly, by
> +specifying a function name, an address, a label, etc.  

This is changing the meaning of what was said.  It is now reading as if
the line number is what are are after, and that function, address, etc.
are merely means to get to the line number.  While before, we were saying that
usually you specify the line number, but you can also specify some
function, or even a precise address.  The new text gives a lot more emphasis to
the resolved line number.

I think it's a difference in the interpretation of "indicate".  The original
text uses it to mean the arguments the user can specify (otherwise it wouldn't
be talking about "a label" or function _name_), while in your version you seem
to be using "indicate" to mean the line number you want the spec to resolve to.

There are commands that accept location specs and want to resolve them to
addresses, others to lines, etc., and you can specify a line to find the address,
and conversely you can also specify an address to find a line.

Maybe we should say _that_ somehow, instead of the "Since @value{GDBN} is a
source-level debugger, a location specification usually indicates some
line" sentence, which I find kind of an unnecessary assertion.  Specifying
function names to break at the function's entry is very usual too, for example.

Or we can just keep the same wording as before.

>  
>  @item
>  For a C@t{++} constructor, the @value{NGCC} compiler generates several
> -instances of the function body, used in different cases.
> +instances of the function body, used in different cases, but their
> +source-level names are identical, unless you qualify them.

What do you mean by "qualify" here?


Otherwise this looks great!

Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Eli Zaretskii]

> Date: Thu, 2 Jun 2022 12:10:54 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> > A concrete code location in your program is uniquely identifiable by a
> > set of several attributes: its source line number, the name of its
> > source file, the fully-qualified and prototyped function in which it
> > is defined, and an instruction address.  Because each inferior has its
> > own address space, the inferior number is also a necessary part of
> > these attributes.  By contrast, location specs you type will many
> 
> I built the manual here with the patch, to read in the html form in the browser,
> and found this paragraph very long and dense.  I find it much more readable if we have a
> paragraph break here (line break + empty line), before "By contract".  Above we talk
> about actual code locations.  And below we talk about location specs.  

Sure, breaking there is fine, thanks.

> >  Several @value{GDBN} commands accept arguments that specify a location
> >  or locations of your program's code.  Since @value{GDBN} is a
> >  source-level debugger, a location specification usually indicates some
> > -line in the source code, but it can also indicate a function name, an
> > -address, a label, and more.
> > +line in some source file, but it can also do that indirectly, by
> > +specifying a function name, an address, a label, etc.  
> 
> This is changing the meaning of what was said.  It is now reading as if
> the line number is what are are after, and that function, address, etc.
> are merely means to get to the line number.  While before, we were saying that
> usually you specify the line number, but you can also specify some
> function, or even a precise address.  The new text gives a lot more emphasis to
> the resolved line number.

I didn't say "number", though, I just said "line".  That's different:
since GDB is a source-level debugger (as the text says), the location
spec identifies some line in the source code.  But it doesn't
necessarily do that via its number.

The point of that paragraph, as I interpret it, is to say that a
function name, a label, or an address all identify a certain line in
the source.

> I think it's a difference in the interpretation of "indicate".  The original
> text uses it to mean the arguments the user can specify (otherwise it wouldn't
> be talking about "a label" or function _name_), while in your version you seem
> to be using "indicate" to mean the line number you want the spec to resolve to.
> 
> There are commands that accept location specs and want to resolve them to
> addresses, others to lines, etc., and you can specify a line to find the address,
> and conversely you can also specify an address to find a line.
> 
> Maybe we should say _that_ somehow, instead of the "Since @value{GDBN} is a
> source-level debugger, a location specification usually indicates some
> line" sentence, which I find kind of an unnecessary assertion.  Specifying
> function names to break at the function's entry is very usual too, for example.

I'm not sure I understand the issue.  "Indicates" was in your original
wording:

 Several @value{GDBN} commands accept arguments that specify a location
 or locations of your program's code.  Since @value{GDBN} is a
 source-level debugger, a location specification usually indicates some
 line in the source code, but it can also indicate a function name, an
 address, a label, and more.

The changes I made to these two sentences are really exceedingly
minor, so I wonder how could they change the meaning.  Could you point
to the modifications which change the meaning?

If you meant what the user specifies, then I agree that perhaps
"indicate" is not the best word, but I didn't interpret the above as
alluding to what the user specifies, I interpreted it to what the user
_means_ by the spec: the user always means some source-code level
location.

> >  @item
> >  For a C@t{++} constructor, the @value{NGCC} compiler generates several
> > -instances of the function body, used in different cases.
> > +instances of the function body, used in different cases, but their
> > +source-level names are identical, unless you qualify them.
> 
> What do you mean by "qualify" here?

The "fully-qualified and prototyped function" part.

> Otherwise this looks great!

Thanks.

Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Pedro Alves]

On 2022-06-02 12:49, Eli Zaretskii wrote:
>> Date: Thu, 2 Jun 2022 12:10:54 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>> A concrete code location in your program is uniquely identifiable by a
>>> set of several attributes: its source line number, the name of its
>>> source file, the fully-qualified and prototyped function in which it
>>> is defined, and an instruction address.  Because each inferior has its
>>> own address space, the inferior number is also a necessary part of
>>> these attributes.  By contrast, location specs you type will many
>>
>> I built the manual here with the patch, to read in the html form in the browser,
>> and found this paragraph very long and dense.  I find it much more readable if we have a
>> paragraph break here (line break + empty line), before "By contract".  Above we talk
>> about actual code locations.  And below we talk about location specs.  
> 
> Sure, breaking there is fine, thanks.
> 
>>>  Several @value{GDBN} commands accept arguments that specify a location
>>>  or locations of your program's code.  Since @value{GDBN} is a
>>>  source-level debugger, a location specification usually indicates some
>>> -line in the source code, but it can also indicate a function name, an
>>> -address, a label, and more.
>>> +line in some source file, but it can also do that indirectly, by
>>> +specifying a function name, an address, a label, etc.  
>>
>> This is changing the meaning of what was said.  It is now reading as if
>> the line number is what are are after, and that function, address, etc.
>> are merely means to get to the line number.  While before, we were saying that
>> usually you specify the line number, but you can also specify some
>> function, or even a precise address.  The new text gives a lot more emphasis to
>> the resolved line number.
> 
> I didn't say "number", though, I just said "line".  That's different:
> since GDB is a source-level debugger (as the text says), the location
> spec identifies some line in the source code.  But it doesn't
> necessarily do that via its number.
> 
> The point of that paragraph, as I interpret it, is to say that a
> function name, a label, or an address all identify a certain line in
> the source.

That was not my intention, as I explained in the paragraph just below:

> 
>> I think it's a difference in the interpretation of "indicate".  The original
>> text uses it to mean the arguments the user can specify (otherwise it wouldn't
>> be talking about "a label" or function _name_), while in your version you seem
>> to be using "indicate" to mean the line number you want the spec to resolve to.
>>
>> There are commands that accept location specs and want to resolve them to
>> addresses, others to lines, etc., and you can specify a line to find the address,
>> and conversely you can also specify an address to find a line.
>>
>> Maybe we should say _that_ somehow, instead of the "Since @value{GDBN} is a
>> source-level debugger, a location specification usually indicates some
>> line" sentence, which I find kind of an unnecessary assertion.  Specifying
>> function names to break at the function's entry is very usual too, for example.
> 
> I'm not sure I understand the issue.  "Indicates" was in your original
> wording:

The original text before my changes used "specifies":

 Several @value{GDBN} commands accept arguments that specify a location
 of your program's code.  Since @value{GDBN} is a source-level
 debugger, a location usually specifies some line in the source code.
 Locations may be specified using three different formats:
 linespec locations, explicit locations, or address locations.

and I wanted to extend it to give the function name, address, label, etc. examples,
other attributes one can specify.

I don't recall exactly how I got to "indicate".  To me, in something
like "-line LINENUM", LINENUM is the line indicated in the spec.  In
"-function FUNC", FUNC is the function name indicated in the spec.
I think I was just trying to avoid the repetition in "a specification specifies",
which sounds like it was a mistake, as it introduced ambiguity.  Better to
go back to "specifies".

> 
>  Several @value{GDBN} commands accept arguments that specify a location
>  or locations of your program's code.  Since @value{GDBN} is a
>  source-level debugger, a location specification usually indicates some
>  line in the source code, but it can also indicate a function name, an
>  address, a label, and more.
> 
> The changes I made to these two sentences are really exceedingly
> minor, so I wonder how could they change the meaning.  Could you point
> to the modifications which change the meaning?

I already explained in the text quoted above.  Here again, and with some emphasis:

 >> I think it's a difference in the interpretation of "indicate".  The original
 >> text uses it to mean the arguments the user can specify (otherwise it wouldn't
                                                             ^^^^^^^^^^^^^^^^^^^^^
 >> be talking about "a label" or function _name_), while in your version you seem
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 >> to be using "indicate" to mean the line number you want the spec to resolve to.
 >>
 >> There are commands that accept location specs and want to resolve them to
 >> addresses, others to lines, etc., and you can specify a line to find the address,
 >> and conversely you can also specify an address to find a line.

> 
> If you meant what the user specifies, then I agree that perhaps
> "indicate" is not the best word, 

Yes, agreed.

> but I didn't interpret the above as
> alluding to what the user specifies, I interpreted it to what the user
> _means_ by the spec: 

Right, the word was ambiguous and I didn't realize it when I used it.  Let's
fix that.

I'm fine if you want to instead change this to talk about the resolved
line in the program, but if we do that, then we should not give emphasis
to the line, but instead do something like I said before:

 >> There are commands that accept location specs and want to resolve them to
 >> addresses, others to lines, etc., and you can specify a line to find the address,
 >> and conversely you can also specify an address to find a line.
 >>
 >> Maybe we should say _that_ somehow, instead of the "Since @value{GDBN} is a
 >> source-level debugger, a location specification usually indicates some
 >> line" sentence, which I find kind of an unnecessary assertion.  Specifying
 >> function names to break at the function's entry is very usual too, for example.

> the user always means some source-code level location.

Note the word "means" here is ambiguous.  I take it you want to say "what the user
wants the spec to resolve to."

Not always a line, no.  The user may mean an address in the program too.
Recall some commands talk about that, like "jump":

 @item jump @var{locspec}
 @itemx j @var{locspec}
 Resume execution at the address of the code location that results from
 resolving @var{locspec}.

Or e.g., if you set a break like "b *ADDR", you want it to stick to that
address.  If you set a break like "b line", you want it to stick to that line.
Even though, those two specs may well resolve to the same line at that given
moment (which may change if shared libraries are subsequently loaded, or the
program is modified and/or recompiled).

> 
>>>  @item
>>>  For a C@t{++} constructor, the @value{NGCC} compiler generates several
>>> -instances of the function body, used in different cases.
>>> +instances of the function body, used in different cases, but their
>>> +source-level names are identical, unless you qualify them.
>>
>> What do you mean by "qualify" here?
> 
> The "fully-qualified and prototyped function" part.

That's unrelated to what is being alluded to here.  This is referring to in-charge
vs not-in-charge constructors ( and I just moved the example from "Set Breaks", so
don't shoot the messenger ;-) ):

 https://sourceware.org/legacy-ml/gdb/2003-10/msg00015.html

(that message obviously predates multi-location breakpoints.)

... an implementation detail that results in a breakpoint set on a constructor,
resolves to more than one code location, even if you specify a fully-qualified and
prototyped name, because the compiler emits two (slightly different) instances
of the function body machine code, for the same source code.  E.g., using a
testcase in the testsuite that covers this:

$ gdb ./testsuite/outputs/gdb.cp/mb-ctor/mb-ctor
...
(gdb) b -qualified Derived::Derived(int) 
Breakpoint 1 at 0x11b5: -qualified Derived::Derived(int). (2 locations)
(gdb) info breakpoints 
Num     Type           Disp Enb Address            What
1       breakpoint     keep y   <MULTIPLE>         
1.1                         y   0x00000000000011b5 in Derived::Derived(int) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
1.2                         y   0x0000000000001211 in Derived::Derived(int) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34

(gdb) r
Starting program: /home/pedro/gdb/binutils-gdb/build/gdb/testsuite/outputs/gdb.cp/mb-ctor/mb-ctor 

Breakpoint 1, Derived::Derived (this=0x7fffffffdac0, i=7, __in_chrg=<optimized out>, __vtt_parm=<optimized out>) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
34      Derived::Derived(int i) : Base(i)
(gdb) p $pc
$1 = (void (*)(void)) 0x555555555211 <Derived::Derived(int)+19>
(gdb) bt
#0  Derived::Derived (this=0x7fffffffdac0, i=7, __in_chrg=<optimized out>, __vtt_parm=<optimized out>) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
#1  0x000055555555531f in main () at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:61
(gdb) c
Continuing.

Breakpoint 1, Derived::Derived (this=0x7fffffffdaa0, __vtt_parm=0x555555557cb8 <VTT for DeeplyDerived+8>, i=15, __in_chrg=<optimized out>)
    at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
34      Derived::Derived(int i) : Base(i)
(gdb) p $pc
$2 = (void (*)(void)) 0x5555555551b5 <Derived::Derived(int)+19>
(gdb) bt
#0  Derived::Derived (this=0x7fffffffdaa0, __vtt_parm=0x555555557cb8 <VTT for DeeplyDerived+8>, i=15, __in_chrg=<optimized out>)
    at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
#1  0x00005555555553a7 in DeeplyDerived::DeeplyDerived (this=0x7fffffffdaa0, i=15, __in_chrg=<optimized out>, __vtt_parm=<optimized out>)
    at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:54
#2  0x0000555555555330 in main () at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:65
(gdb) 

Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Eli Zaretskii]

> Date: Thu, 2 Jun 2022 13:40:10 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> The original text before my changes used "specifies":
> 
>  Several @value{GDBN} commands accept arguments that specify a location
>  of your program's code.  Since @value{GDBN} is a source-level
>  debugger, a location usually specifies some line in the source code.
>  Locations may be specified using three different formats:
>  linespec locations, explicit locations, or address locations.
> 
> and I wanted to extend it to give the function name, address, label, etc. examples,
> other attributes one can specify.
> 
> I don't recall exactly how I got to "indicate".  To me, in something
> like "-line LINENUM", LINENUM is the line indicated in the spec.  In
> "-function FUNC", FUNC is the function name indicated in the spec.
> I think I was just trying to avoid the repetition in "a specification specifies",
> which sounds like it was a mistake, as it introduced ambiguity.  Better to
> go back to "specifies".

OK, how about this instead?

  Several @value{GDBN} commands accept arguments that specify a location
  or locations of your program's code.  Many times locations are
  specified using a source line number, but they can also be specified
  by a function name, an address, a label, etc.  The different
  forms of specifying a location that @value{GDBN} recognizes are
  collectively known as forms of @dfn{location specification}, or
  @dfn{location spec}.  This section documents the forms of specifying
  locations that @value{GDBN} recognizes.

> >>>  For a C@t{++} constructor, the @value{NGCC} compiler generates several
> >>> -instances of the function body, used in different cases.
> >>> +instances of the function body, used in different cases, but their
> >>> +source-level names are identical, unless you qualify them.
> >>
> >> What do you mean by "qualify" here?
> > 
> > The "fully-qualified and prototyped function" part.
> 
> That's unrelated to what is being alluded to here.

OK, I will drop the "unless you qualify them" part.

Thanks.

Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Pedro Alves]

On 2022-06-02 13:56, Eli Zaretskii wrote:
>> Date: Thu, 2 Jun 2022 13:40:10 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>> The original text before my changes used "specifies":
>>
>>  Several @value{GDBN} commands accept arguments that specify a location
>>  of your program's code.  Since @value{GDBN} is a source-level
>>  debugger, a location usually specifies some line in the source code.
>>  Locations may be specified using three different formats:
>>  linespec locations, explicit locations, or address locations.
>>
>> and I wanted to extend it to give the function name, address, label, etc. examples,
>> other attributes one can specify.
>>
>> I don't recall exactly how I got to "indicate".  To me, in something
>> like "-line LINENUM", LINENUM is the line indicated in the spec.  In
>> "-function FUNC", FUNC is the function name indicated in the spec.
>> I think I was just trying to avoid the repetition in "a specification specifies",
>> which sounds like it was a mistake, as it introduced ambiguity.  Better to
>> go back to "specifies".
> 
> OK, how about this instead?
> 
>   Several @value{GDBN} commands accept arguments that specify a location
>   or locations of your program's code.  Many times locations are
>   specified using a source line number, but they can also be specified
>   by a function name, an address, a label, etc.  The different
>   forms of specifying a location that @value{GDBN} recognizes are
>   collectively known as forms of @dfn{location specification}, or
>   @dfn{location spec}.  This section documents the forms of specifying
>   locations that @value{GDBN} recognizes.

Perfect.

> 
>>>>>  For a C@t{++} constructor, the @value{NGCC} compiler generates several
>>>>> -instances of the function body, used in different cases.
>>>>> +instances of the function body, used in different cases, but their
>>>>> +source-level names are identical, unless you qualify them.
>>>>
>>>> What do you mean by "qualify" here?
>>>
>>> The "fully-qualified and prototyped function" part.
>>
>> That's unrelated to what is being alluded to here.
> 
> OK, I will drop the "unless you qualify them" part.

Sounds good.

Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Eli Zaretskii]

> Date: Thu, 2 Jun 2022 14:44:31 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> > OK, how about this instead?
> > 
> >   Several @value{GDBN} commands accept arguments that specify a location
> >   or locations of your program's code.  Many times locations are
> >   specified using a source line number, but they can also be specified
> >   by a function name, an address, a label, etc.  The different
> >   forms of specifying a location that @value{GDBN} recognizes are
> >   collectively known as forms of @dfn{location specification}, or
> >   @dfn{location spec}.  This section documents the forms of specifying
> >   locations that @value{GDBN} recognizes.
> 
> Perfect.
> 
> > 
> >>>>>  For a C@t{++} constructor, the @value{NGCC} compiler generates several
> >>>>> -instances of the function body, used in different cases.
> >>>>> +instances of the function body, used in different cases, but their
> >>>>> +source-level names are identical, unless you qualify them.
> >>>>
> >>>> What do you mean by "qualify" here?
> >>>
> >>> The "fully-qualified and prototyped function" part.
> >>
> >> That's unrelated to what is being alluded to here.
> > 
> > OK, I will drop the "unless you qualify them" part.
> 
> Sounds good.

Thanks, I made those changes and pushed.