* [PATCH] gdb/manual: Introduce locspecs
@ 2022-05-25 19:31 Pedro Alves
2022-05-25 19:56 ` Eli Zaretskii
0 siblings, 1 reply; 12+ messages in thread
From: Pedro Alves @ 2022-05-25 19:31 UTC (permalink / raw)
To: gdb-patches
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 locations
(plural) in the program that match. For example, a "location"
specified like "-function func" will actually match all the 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 "-label lab"
matches all the addresses & source lines of where a C label name "lab"
is defined. 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 matched locations. In other cases, the command
aborts with an error if the location specification matches multiple
locations in the program. In other cases, GDB just arbitrarily and
silently picks whatever is the first location that matches (which
sounds like should be improved).
To clarify this, I propose we use the term "Location Specification",
with shorthand "locspec", 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
locations in the program, which are what GDB finds based on the
user-specified locspec. Then use "locspec" 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 "locspec", as something distinct from an
actual location in the program. It explains that a location
specification may match multiple locations in the program. It gives
examples of how that happens. 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 locspec 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 locspec matches more than one
location in the program. 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 this one is updated differently from the others.
Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b
---
gdb/doc/gdb.texinfo | 372 ++++++++++++++++++++++++--------------------
gdb/doc/guile.texi | 2 +-
gdb/doc/python.texi | 5 +-
3 files changed, 210 insertions(+), 169 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 68679982919..15175012ebb 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 locations the given @var{locspec} matches.
+@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 any of the code at 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,28 +4616,8 @@ 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 breakpoint corresponds to several 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
@@ -4711,32 +4693,35 @@ 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 find any location that
+matches the locspec (@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 find any
+location that matches the locspec, 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 find any location that
+matches the locspec, it should create a pending breakpoint without
+asking for 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 find any location that matches the locspec, 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
-as shared libraries are loaded and unloaded.
+variants. Once a breakpoint is created, it will be automatically
+updated as shared libraries are loaded and unloaded.
@cindex automatic hardware breakpoints
For some targets, @value{GDBN} can automatically decide if hardware or
@@ -5455,10 +5440,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 any breakpoints set at the 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 +5800,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 location 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 +6299,11 @@ 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 location 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 +6324,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 location that matches
+@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 +6428,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 +6465,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 +6498,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 +7127,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 location or locations in your program's
+code. @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 +8930,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 +8946,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:
@@ -9009,25 +8994,33 @@ 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
+locspecs. The locspecs specify source lines; there are several ways
+of writing them (@pxref{Location Specifications}), but the effect is always
to specify some source line.
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 for the locations that
+match @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.
+locspecs. When a @code{list} command has two locspecs, and the source
+file of the second locspec is omitted, this refers to the same source
+file as the first locspec. If either @var{first} or @var{last} match
+more than one location in the program, then the list command will
+print the list of ambiguous locations and does not print any source
+lines.
@item list ,@var{last}
Print lines ending with @var{last}.
+Likewise, if @var{last} matches more than one location in the program,
+then the list command will print the list of ambiguous locations and
+does not print any source lines.
+
@item list @var{first},
Print lines starting with @var{first}.
@@ -9041,17 +9034,50 @@ 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 locspec
@cindex source 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.
+
+As shorthand, and to better distinguish from actual locations in the
+program, a location specification is refered to as a @dfn{locspec}
+throughout the manual.
+
+A locspec serves as a blueprint, and it may match more than one actual
+location in your program. Examples of this situation are:
+
+@itemize @bullet
+@item
+The locspec specifies a function name, and multiple functions in the
+program may have the same name.
+
+@item
+The locspec 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 +9296,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 specified location, e.g., at the specified source line of the
+specified file. @xref{Location Specifications}, for all the possible
+forms of the @var{locspec} argument.
+
+If @code{locspec} matches more than one location in your program, then
+the command prints the list of locations 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 +9686,11 @@ 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 match @var{locspec}. You can specify source lines in any of
+the ways documented in @ref{Location Specifications}. 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
@@ -9675,7 +9706,7 @@ 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:
+@var{locspec}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
@@ -9883,10 +9914,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 as a locspec (@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 +14203,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 first location in
+your program that matches @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 +14509,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 +14548,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 +14587,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 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}} as location. 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 +17472,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 +18795,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 +19563,13 @@ These commands can be used to enable or disable type printers.
@kindex info scope
@cindex local variables
-@item info scope @var{location}
+@item info scope @var{locspec}
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:
+accepts a location specification 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 the first location in your
+program that matches @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 +20157,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 location that matches @var{locspec}.
+@xref{Location Specifications}, for a description of the different
+forms of @var{locspec}. If @var{locspec} matches more than one
+location, the command aborts before jumping to any location.
+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} matches a
+location 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 +25401,18 @@ use the @code{break-range} command.
@table @code
@kindex break-range
-@item break-range @var{start-location}, @var{end-location}
+@item break-range @var{start-locspec}, @var{end-locspec}
Set a breakpoint for an address range given by
-@var{start-location} and @var{end-location}, which can specify a function name,
+@var{start-locspec} and @var{end-locspec}, 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}.)
+location, or an address of an instruction (see @ref{Location Specifications},
+for a list of all the possible ways to specify a locspec).
+If either @var{start-locspec} or @var{end-locspec} match multiple
+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 within the specified range,
-(including @var{start-location} and @var{end-location}.)
+(including @var{start-locspec} and @var{end-locspec}.)
@kindex set powerpc
@item set powerpc soft-float
@@ -31192,11 +31231,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 +31274,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 +31359,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 +31374,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 +32590,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 +32909,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 a location that matches @var{locspec} 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}.
@subsubheading @value{GDBN} Command
@@ -34935,7 +34974,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}.
+Line specification is required as parameter. @xref{Location Specifications}.
Finds next trace frame that corresponds to a tracepoint at
the specified location.
@@ -39438,8 +39477,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 +39489,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
+locations that match @var{linespec} (@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
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-25 19:31 [PATCH] gdb/manual: Introduce locspecs Pedro Alves
@ 2022-05-25 19:56 ` Eli Zaretskii
2022-05-25 20:05 ` Pedro Alves
2022-05-25 21:02 ` [PATCH v2] gdb/manual: Introduce location specs Pedro Alves
0 siblings, 2 replies; 12+ messages in thread
From: Eli Zaretskii @ 2022-05-25 19:56 UTC (permalink / raw)
To: Pedro Alves; +Cc: gdb-patches
> From: Pedro Alves <pedro@palves.net>
> Date: Wed, 25 May 2022 20:31:26 +0100
>
> To clarify this, I propose we use the term "Location Specification",
> with shorthand "locspec", 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
> locations in the program, which are what GDB finds based on the
> user-specified locspec. Then use "locspec" thoughout instead of
> "location" when we're talking about the user input.
Sorry, but I don't think this is a good idea. It is IMO okay to
introduce "location specification" into our terminology; it is even
okay to use "location spec" as its shorthand. But "locspec" is too
much: it's not a word, so it doesn't explain itself enough, and thus
cannot be used very far from where it is defined, because the reader
will likely not understand what it means. "Locspec" is fine to use in
the likes of @var{locspec}, where we describe commands that take a
location specification as an argument, but using it as a general term
everywhere in the manual (and we have quite a lot of references to
location specs, as several commands work in these terms) will make the
manual more awkward to write (we will need a lot more references to
where "locspec" is defined), and as result harder to read where these
are mentioned, due to the need to actually go to that cross-referenced
section.
As I suggested elsewhere, I think it would be a better idea to reserve
the use of "location" only to these specifications, and use some other
term (e.g., "address") for the actual "resolved" locations that are
places in the program's code. That will allow us to use "location" as
a shorthand for "location specification", something that will
inevitably happen anyway (people being what they are: we hate to type
long phrases when we think a shorter one will do). If we use
"location" for two related but different concepts, this tendency will
cause confusing text both in the manual and even in our discussions
here on the list.
Or maybe there are other ideas to resolve this difficulty. If someone
has alternative proposals, please describe them, and let's discuss.
Thanks.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-25 19:56 ` Eli Zaretskii
@ 2022-05-25 20:05 ` Pedro Alves
2022-05-25 21:24 ` Philippe Waroquiers
2022-05-26 12:56 ` Eli Zaretskii
2022-05-25 21:02 ` [PATCH v2] gdb/manual: Introduce location specs Pedro Alves
1 sibling, 2 replies; 12+ messages in thread
From: Pedro Alves @ 2022-05-25 20:05 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On 2022-05-25 20:56, Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Date: Wed, 25 May 2022 20:31:26 +0100
>>
>> To clarify this, I propose we use the term "Location Specification",
>> with shorthand "locspec", 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
>> locations in the program, which are what GDB finds based on the
>> user-specified locspec. Then use "locspec" thoughout instead of
>> "location" when we're talking about the user input.
>
> Sorry, but I don't think this is a good idea. It is IMO okay to
> introduce "location specification" into our terminology; it is even
> okay to use "location spec" as its shorthand. But "locspec" is too
> much: it's not a word, so it doesn't explain itself enough, and thus
> cannot be used very far from where it is defined, because the reader
> will likely not understand what it means.
Yet, we have "linespec" and people understand it just fine, it's described
once in a single spot in the manual. "locspec" just sounds novel now, but it won't be
novel anymore once we start using it. It sounds like you are against any term that
is new just because it is new. That just blocks progress forever. It is not reasonable.
New shorthand names for for things that are referred very frequently should be fine
to invent. Our users aren't dummies and they learn things.
> "Locspec" is fine to use in
> the likes of @var{locspec}, where we describe commands that take a
> location specification as an argument, but using it as a general term
> everywhere in the manual (and we have quite a lot of references to
> location specs, as several commands work in these terms) will make the
> manual more awkward to write (we will need a lot more references to
> where "locspec" is defined),
No we wont. Everywhere I used "locspec" already has a xref to where
it is defined... Please give the patch a change and read it in more detail.
> and as result harder to read where these
> are mentioned, due to the need to actually go to that cross-referenced
> section.
>
> As I suggested elsewhere, I think it would be a better idea to reserve
> the use of "location" only to these specifications, and use some other
> term (e.g., "address") for the actual "resolved" locations that are
> places in the program's code. That will allow us to use "location" as
> a shorthand for "location specification", something that will
> inevitably happen anyway (people being what they are: we hate to type
> long phrases when we think a shorter one will do). If we use
> "location" for two related but different concepts, this tendency will
> cause confusing text both in the manual and even in our discussions
> here on the list.
And I've already explained why that would be incorrect. Please give it a read, here:
https://sourceware.org/pipermail/gdb-patches/2022-May/189418.html
>
> Or maybe there are other ideas to resolve this difficulty. If someone
> has alternative proposals, please describe them, and let's discuss.
>
> Thanks.
>
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v2] gdb/manual: Introduce location specs
2022-05-25 19:56 ` Eli Zaretskii
2022-05-25 20:05 ` Pedro Alves
@ 2022-05-25 21:02 ` Pedro Alves
2022-05-26 6:50 ` Eli Zaretskii
1 sibling, 1 reply; 12+ messages in thread
From: Pedro Alves @ 2022-05-25 21:02 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On 2022-05-25 20:56, Eli Zaretskii wrote:
> Sorry, but I don't think this is a good idea. It is IMO okay to
> introduce "location specification" into our terminology; it is even
> okay to use "location spec" as its shorthand. But "locspec" is too
> much: it's not a word, so it doesn't explain itself enough, and thus
> cannot be used very far from where it is defined, because the reader
> will likely not understand what it means. "Locspec" is fine to use in
> the likes of @var{locspec}, where we describe commands that take a
> location specification as an argument,
Here's a version of the patch that does that. I went through all references
to "locspec" that weren't a case of "@var{locspec} describing a comment argument",
and replaced them with "location spec". I take it from your comments above
that you would be OK with this.
Thus, is this version OK to apply?
From 0a974fe62adf468c8e58ae0a8c4cfa4354662b9d Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 17 May 2022 13:12:04 +0100
Subject: [PATCH v2] 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 locations
(plural) in the program that match. For example, a "location"
specified like "-function func" will actually match all the 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 "-label lab"
matches all the addresses & source lines of where a C label name "lab"
is defined. 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 matched locations. In other cases, the command
aborts with an error if the location specification matches multiple
locations in the program. In other cases, GDB just arbitrarily and
silently picks whatever is the first location that matches (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 locations in the program, which are what GDB finds based on
the user-specified locspec. 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 location in the program. It explains that a location
specification may match multiple locations in the program. It gives
examples of how that happens. 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 locspec 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 matches more than one
location in the program. 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 this one is updated differently from the others.
Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b
---
gdb/doc/gdb.texinfo | 372 ++++++++++++++++++++++++--------------------
gdb/doc/guile.texi | 2 +-
gdb/doc/python.texi | 5 +-
3 files changed, 208 insertions(+), 171 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 68679982919..75ac582dc65 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 locations the given @var{locspec} matches.
+@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 any of the code at 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,28 +4616,8 @@ 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 breakpoint corresponds to several 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
@@ -4711,23 +4693,26 @@ 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 find any location that
+matches the location spec (@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 find any
+location that matches 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 find any location that
+matches the location spec, it should create a pending breakpoint
+without asking for 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
+This indicates that pending breakpoints are not to be created. If
+@value{GDBN} cannot find any location that matches 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
@@ -4735,8 +4720,8 @@ 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
-as shared libraries are loaded and unloaded.
+variants. Once a breakpoint is created, it will be automatically
+updated as shared libraries are loaded and unloaded.
@cindex automatic hardware breakpoints
For some targets, @value{GDBN} can automatically decide if hardware or
@@ -5455,10 +5440,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 any breakpoints set at the 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 +5800,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 location 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 +6299,11 @@ 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 location 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 +6324,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 location that matches
+@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 +6428,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 +6465,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 +6498,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 +7127,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 location or locations in your program's
+code. @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 +8930,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 +8946,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 +8993,34 @@ 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. The location specs specify source lines; there
+are several ways of writing them (@pxref{Location Specifications}),
+but the effect is always to specify some source line.
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 for the locations that
+match @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} match
+more than one location in the program, then the list command will
+print the list of ambiguous locations and does not print any source
+lines.
@item list ,@var{last}
Print lines ending with @var{last}.
+Likewise, if @var{last} matches more than one location in the program,
+then the list command will print the list of ambiguous locations and
+does not print any source lines.
+
@item list @var{first},
Print lines starting with @var{first}.
@@ -9041,17 +9034,46 @@ 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
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 location spec serves as a blueprint, and it may match more than one
+actual location in your program. Examples of this situation are:
+
+@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 +9292,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 specified location, e.g., at the specified source line of the
+specified file. @xref{Location Specifications}, for all the possible
+forms of the @var{locspec} argument.
+
+If @code{locspec} matches more than one location in your program, then
+the command prints the list of locations 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 +9682,11 @@ 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 match @var{locspec}. You can specify source lines in any of
+the ways documented in @ref{Location Specifications}. 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
@@ -9675,7 +9702,7 @@ 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:
+@var{locspec}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
@@ -9883,10 +9910,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 as 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 +14199,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 first location in
+your program that matches @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 +14505,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 +14544,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 +14583,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 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}} as location. 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 +17468,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 +18791,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 +19559,13 @@ These commands can be used to enable or disable type printers.
@kindex info scope
@cindex local variables
-@item info scope @var{location}
+@item info scope @var{locspec}
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:
+accepts a location specification 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 the first location in your
+program that matches @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 +20153,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 location that matches @var{locspec}.
+@xref{Location Specifications}, for a description of the different
+forms of @var{locspec}. If @var{locspec} matches more than one
+location, the command aborts before jumping to any location.
+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} matches a
+location 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 +25397,18 @@ use the @code{break-range} command.
@table @code
@kindex break-range
-@item break-range @var{start-location}, @var{end-location}
+@item break-range @var{start-locspec}, @var{end-locspec}
Set a breakpoint for an address range given by
-@var{start-location} and @var{end-location}, which can specify a function name,
+@var{start-locspec} and @var{end-locspec}, 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}.)
+location, or an address of an instruction (see @ref{Location Specifications},
+for a list of all the possible ways to specify a location spec).
+If either @var{start-locspec} or @var{end-locspec} match multiple
+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 within the specified range,
-(including @var{start-location} and @var{end-location}.)
+(including @var{start-locspec} and @var{end-locspec}.)
@kindex set powerpc
@item set powerpc soft-float
@@ -31192,11 +31227,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 +31270,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 +31355,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 +31370,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 +32586,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 +32905,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 a location that matches @var{locspec} 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}.
@subsubheading @value{GDBN} Command
@@ -34935,7 +34970,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}.
+Line specification is required as parameter. @xref{Location Specifications}.
Finds next trace frame that corresponds to a tracepoint at
the specified location.
@@ -39438,8 +39473,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 +39485,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
+locations that match @var{linespec} (@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
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-25 20:05 ` Pedro Alves
@ 2022-05-25 21:24 ` Philippe Waroquiers
2022-05-25 22:18 ` Pedro Alves
2022-05-26 12:56 ` Eli Zaretskii
1 sibling, 1 reply; 12+ messages in thread
From: Philippe Waroquiers @ 2022-05-25 21:24 UTC (permalink / raw)
To: Pedro Alves, Eli Zaretskii; +Cc: gdb-patches
On Wed, 2022-05-25 at 21:05 +0100, Pedro Alves wrote:
> On 2022-05-25 20:56, Eli Zaretskii wrote:
> > > From: Pedro Alves <pedro@palves.net>
> > > Date: Wed, 25 May 2022 20:31:26 +0100
> > >
> > > To clarify this, I propose we use the term "Location Specification",
> > > with shorthand "locspec", 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
> > > locations in the program, which are what GDB finds based on the
> > > user-specified locspec. Then use "locspec" thoughout instead of
> > > "location" when we're talking about the user input.
> >
> > Sorry, but I don't think this is a good idea. It is IMO okay to
> > introduce "location specification" into our terminology; it is even
> > okay to use "location spec" as its shorthand. But "locspec" is too
> > much: it's not a word, so it doesn't explain itself enough, and thus
> > cannot be used very far from where it is defined, because the reader
> > will likely not understand what it means.
>
> Yet, we have "linespec" and people understand it just fine, it's described
> once in a single spot in the manual. "locspec" just sounds novel now, but it won't be
> novel anymore once we start using it. It sounds like you are against any term that
> is new just because it is new. That just blocks progress forever. It is not reasonable.
> New shorthand names for for things that are referred very frequently should be fine
> to invent. Our users aren't dummies and they learn things.
IIUC, Eli would like to have location reserved for a breakpoint giving multiple resulting
locations.
Why not then use breakpoint specification/bkptspec for the first concept
and location for the second ?
Thanks
Philippe
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-25 21:24 ` Philippe Waroquiers
@ 2022-05-25 22:18 ` Pedro Alves
2022-05-26 6:51 ` Eli Zaretskii
0 siblings, 1 reply; 12+ messages in thread
From: Pedro Alves @ 2022-05-25 22:18 UTC (permalink / raw)
To: Philippe Waroquiers, Eli Zaretskii; +Cc: gdb-patches
On 2022-05-25 22:24, Philippe Waroquiers wrote:
> On Wed, 2022-05-25 at 21:05 +0100, Pedro Alves wrote:
>> On 2022-05-25 20:56, Eli Zaretskii wrote:
>>>> From: Pedro Alves <pedro@palves.net>
>>>> Date: Wed, 25 May 2022 20:31:26 +0100
>>>>
>>>> To clarify this, I propose we use the term "Location Specification",
>>>> with shorthand "locspec", 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
>>>> locations in the program, which are what GDB finds based on the
>>>> user-specified locspec. Then use "locspec" thoughout instead of
>>>> "location" when we're talking about the user input.
>>>
>>> Sorry, but I don't think this is a good idea. It is IMO okay to
>>> introduce "location specification" into our terminology; it is even
>>> okay to use "location spec" as its shorthand. But "locspec" is too
>>> much: it's not a word, so it doesn't explain itself enough, and thus
>>> cannot be used very far from where it is defined, because the reader
>>> will likely not understand what it means.
>>
>> Yet, we have "linespec" and people understand it just fine, it's described
>> once in a single spot in the manual. "locspec" just sounds novel now, but it won't be
>> novel anymore once we start using it. It sounds like you are against any term that
>> is new just because it is new. That just blocks progress forever. It is not reasonable.
>> New shorthand names for for things that are referred very frequently should be fine
>> to invent. Our users aren't dummies and they learn things.
> IIUC, Eli would like to have location reserved for a breakpoint giving multiple resulting
> locations.
No, he was saying he would prefer "location" to be reserved for location specifications,
and to find a different name for breakpoint locations. I would find that really odd -- a breakpoint
is passed a location specification, and then we plant a breakpoint instruction on
each of the program locations that matches the specification. Each breakpoint location
really represents a program location, with address, function, file and line all being important.
So it's natural to call each of those a different location. I don't see why would we even
bother to consider renaming breakpoint locations to something else.
>
> Why not then use breakpoint specification/bkptspec for the first concept
> and location for the second ?
"breakpoint specification" wouldn't work because we have many commands that take
a location spec as argument that have nothing to do with breakpoints. For example:
(top-gdb) info line main
Line 365 of "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/operators/char/2.cc" starts at address 0x86dee9 <selftests::string_view::operators_2::main()>
and ends at 0x86def1 <selftests::string_view::operators_2::main()+8>.
Line 73 of "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/operations/substr/char/1.cc" starts at address 0x86c097 <selftests::string_view::operations_substr_1::main()>
and ends at 0x86c09f <selftests::string_view::operations_substr_1::main()+8>.
Line 62 of "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/operations/rfind/char/3.cc" starts at address 0x86bd5a <selftests::string_view::operations_rfind_3::main()>
and ends at 0x86bd62 <selftests::string_view::operations_rfind_3::main()+8>.
Line 47 of "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/operations/rfind/char/2.cc" starts at address 0x86b9a6 <selftests::string_view::operations_rfind_2::main()>
and ends at 0x86b9ae <selftests::string_view::operations_rfind_2::main()+8>.
...
(top-gdb) list -function main
file: "/home/pedro/gdb/binutils-gdb/src/gdb/gdb.c", line number: 25, symbol: "main(int, char**)"
20 #include "main.h"
21 #include "interps.h"
22
23 int
24 main (int argc, char **argv)
25 {
26 struct captured_main_args args;
27
28 memset (&args, 0, sizeof args);
29 args.argc = argc;
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/capacity/1.cc", line number: 166, symbol: "selftests::string_view::capacity_1::main()"
161 VERIFY( sz03 >= sz04 );
162 }
163
164 static int
165 main()
166 {
167 test01();
168
169 return 0;
170 }
...
(top-gdb) edit main
Specified line is ambiguous:
file: "/home/pedro/gdb/binutils-gdb/src/gdb/gdb.c", line number: 25, symbol: "main(int, char**)"
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/capacity/1.cc", line number: 166, symbol: "selftests::string_view::capacity_1::main()"
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/1.cc", line number: 61, symbol: "selftests::string_view::cons_1::main()"
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/2.cc", line number: 40, symbol: "selftests::string_view::cons_2::main()"
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/3.cc", line number: 33, symbol: "selftests::string_view::cons_3::main()"
...
Etc.
Please take a look at the v2 patch I sent, and its description, where you'll
find plenty of examples more. If you look at the patch's diff itself, you'll
find I added text to several commands describing what they do when the spec
matches multiple locations.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH v2] gdb/manual: Introduce location specs
2022-05-25 21:02 ` [PATCH v2] gdb/manual: Introduce location specs Pedro Alves
@ 2022-05-26 6:50 ` Eli Zaretskii
2022-05-26 12:26 ` [PATCH v3] " Pedro Alves
0 siblings, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2022-05-26 6:50 UTC (permalink / raw)
To: Pedro Alves; +Cc: gdb-patches
> Date: Wed, 25 May 2022 22:02:04 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
>
> On 2022-05-25 20:56, Eli Zaretskii wrote:
>
> > Sorry, but I don't think this is a good idea. It is IMO okay to
> > introduce "location specification" into our terminology; it is even
> > okay to use "location spec" as its shorthand. But "locspec" is too
> > much: it's not a word, so it doesn't explain itself enough, and thus
> > cannot be used very far from where it is defined, because the reader
> > will likely not understand what it means. "Locspec" is fine to use in
> > the likes of @var{locspec}, where we describe commands that take a
> > location specification as an argument,
>
> Here's a version of the patch that does that. I went through all references
> to "locspec" that weren't a case of "@var{locspec} describing a comment argument",
> and replaced them with "location spec". I take it from your comments above
> that you would be OK with this.
Thanks. However, this new version does only part of the job: it still
uses "location" in an additional meaning: to mean "the actual place in
the program where the breakpoint will break". We must avoid the
confusion from using "location" in two quite different senses. I will
mostly use the term "address" in the rest of my comments below, but if
that term is not optimal for some reason, we could later replace it
with something else.
> Thus, is this version OK to apply?
Unfortunately, no. Please see the comments below.
> +@item break @var{locspec}
> +Set a breakpoint at all the locations the given @var{locspec} matches.
This should say something like
Set a breakpoint at all the program addresses that match the
@dfn{location specification} @var{locspec}.
We could also use "all the places in the program code" instead of "all
the program addresses". Or maybe you or someone else will be able to
propose other alternatives. But we should not use "location" to mean
the actual resolved address where the breakpoint will break.
> +@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 any of the code at any of the breakpoint's
> +locations.
^^^^^^^^^
"addresses", not "locations".
> +It is possible that a breakpoint corresponds to several locations in
> +your program. @xref{Location Specifications}, for examples.
I would rephrase:
It is possible that a breakpoint's location spec corresponds to
several places in your program.
> @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 find any location that
> +matches the location spec (@pxref{Location Specifications}):
This should say "...cannot resolve the breakpoint's location spec to
an address". IOW, the only problem in the original text was with
using "address specification", where we now want to use "location
specification" instead.
> @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 find any
> +location that matches the location spec, it queries you whether a
> +pending breakpoint should be created.
"When @value{GDBN} cannot resolve the breakpoint's location spec to an
address, it queries you whether..."
> @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 find any location that
> +matches the location spec, it should create a pending breakpoint
> +without asking for confirmation.
"This indicates that when @value{GDBN} cannot resolve a location spec,
it should create a @dfn{pending breakpoint} without asking for
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
> +This indicates that pending breakpoints are not to be created. If
> +@value{GDBN} cannot find any location that matches the location spec,
> +it aborts the breakpoint creation with an error. This setting does
> not affect any pending breakpoints previously created.
Similar rephrasing here.
> The settings above only affect the @code{break} command and its
> -variants. Once breakpoint is set, it will be automatically updated
> -as shared libraries are loaded and unloaded.
> +variants. Once a breakpoint is created, it will be automatically
> +updated as shared libraries are loaded and unloaded.
I don't necessarily object, but can you tell why "breakpoint is set"
was not good enough? After all the description of the "break" command
says "Set a breakpoint...", so the original text here was being
consistent with that.
> -@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 any breakpoints set at the locations that match @var{locspec}.
"Delete any breakpoints set at addresses that match the location spec
@var{locspec}."
> +Whenever execution reaches a location 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.
"Whenever execution reaches an address that matches @var{locspec}, ..."
> +@item until @var{locspec}
> +@itemx u @var{locspec}
> +Continue running your program until either a location that matches @var{locspec} is
> +reached, or the current stack frame returns. @var{locspec} is any of
> +the forms described in @ref{Location Specifications}.
"Continue running your program until it either reaches an address that
matches the location specification @var{locspec}, or the current stack
frame returns."
> +@kindex advance @var{locspec}
> +@item advance @var{locspec}
> +Continue running the program up to the location that matches
> +@var{locspec}. ^^^^^^^^^^^^
This should be "an address".
> Functions may be skipped by providing either a function name, linespec
^^^^^^^^^^^^^^^^^^^^^^^
Does "skip" support only some of the location specification formats? If
it supports all of them, we should just say "location specification"
there instead of using these two terms.
> +In general, the @code{list} command expects you to supply zero, one or
> +two location specs. The location specs specify source lines; there
> +are several ways of writing them (@pxref{Location Specifications}),
> +but the effect is always to specify some source line.
The last sentence should say
"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."
> +@item list @var{locspec}
> +Print lines centered around the line or lines for the locations that
> +match @var{locspec}.
"Print lines centered around the line or lines for the addresses that
match @var{linespec}."
> @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} match
> +more than one location in the program, then the list command will
> +print the list of ambiguous locations and does not print any source
> +lines.
The last sentence should say
"If either @var{first} or @var{last} match more than one source line
in the program, the @code{list} command will show the list of
ambiguous source lines, and will not print any source lines."
> +Likewise, if @var{last} matches more than one location in the program,
> +then the list command will print the list of ambiguous locations and
> +does not print any source lines.
Likewise here.
> +A location spec serves as a blueprint, and it may match more than one
> +actual location in your program. Examples of this situation are:
^^^^^^^^
"address".
> +@item edit @var{locspec}
> +Edit the source file specified by @code{locspec}. Editing starts at
> +the specified location, e.g., at the specified source line of the
> +specified file. @xref{Location Specifications}, for all the possible
> +forms of the @var{locspec} argument.
> +
> +If @code{locspec} matches more than one location in your program, then
^^^^^^^^
"source line"
> +the command prints the list of locations and does not proceed with the
^^^^^^^^^
"source lines"
> We can also inquire (using @code{*@var{addr}} as the form for
> -@var{location}) what source line covers a particular address:
> +@var{locspec}) what source line covers a particular address:
"You can also inquire (using @code{*@var{addr}} as the form for
@var{locspec}) what source line covers a particular address
@var{addr}:"
> +@item info macros @var{locspec}
> +Show all macro definitions that are in effect at the first location in
> +your program that matches @var{locspec}, and describe the source
> +location or compiler command-line where those definitions were
> +established.
"Show all macro definitions that are in effect at the first address in
your program that matches @var{locspec}, and describe the place in the
source code or compiler command-line where those definitions were
established."
> 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 locations that match
> +@var{locspec}. ^^^^^^^^^
"addresses"
> It may not be possible to set a static tracepoint at
> +the desired location, in which case the command will exit with an
"It may not be possible to set a static tracepoint at any address that
matches @var{locspec}, in which case..."
> @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}} as location. This probes the marker
"...the user can also specify @code{-m @var{marker}} instead of a
location spec."
> -@item info scope @var{location}
> +@item info scope @var{locspec}
> 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:
> +accepts a location specification 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 the first location in your
^^^^^^^^
"address" or "place".
> +@item jump @var{locspec}
> +@itemx j @var{locspec}
> +Resume execution at the location that matches @var{locspec}.
^^^^^^^^
"address"
> +@xref{Location Specifications}, for a description of the different
> +forms of @var{locspec}. If @var{locspec} matches more than one
> +location, the command aborts before jumping to any location.
^^^^^^^^
"address". And "to any location" at the end can be simply removed.
> 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} matches a
> +location in a different function from the one currently executing, the
^^^^^^^^
"address"
> +@item break-range @var{start-locspec}, @var{end-locspec}
> Set a breakpoint for an address range given by
> -@var{start-location} and @var{end-location}, which can specify a function name,
> +@var{start-locspec} and @var{end-locspec}, 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}.)
> +location, or an address of an instruction (see @ref{Location Specifications},
> +for a list of all the possible ways to specify a location spec).
> +If either @var{start-locspec} or @var{end-locspec} match multiple
> +locations in the program, then the command aborts with an error
^^^^^^^^^
"addresses"
> @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 a location that matches @var{locspec} is
> +reached.
"Executes the inferior until it reaches an address that matches
@var{locspec}."
> @item line
> -Line specification is required as parameter. @xref{Specify Location}.
> +Line specification is required as parameter. @xref{Location Specifications}.
^^^^^^^^^^^^^^^^^^
"Line specification" or "location specification"?
> -If @code{-at} is given, generate remote agent bytecode for @var{location}.
> +If @code{-at} is given, generate remote agent bytecode for all
> +locations that match @var{linespec} (@pxref{Linespec Locations}).
Same question here.
Thanks.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-25 22:18 ` Pedro Alves
@ 2022-05-26 6:51 ` Eli Zaretskii
2022-05-26 13:41 ` Simon Marchi
0 siblings, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2022-05-26 6:51 UTC (permalink / raw)
To: Pedro Alves; +Cc: philippe.waroquiers, gdb-patches
> Date: Wed, 25 May 2022 23:18:02 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
>
> > IIUC, Eli would like to have location reserved for a breakpoint giving multiple resulting
> > locations.
>
> No, he was saying he would prefer "location" to be reserved for location specifications,
> and to find a different name for breakpoint locations.
Yes.
> I don't see why would we even bother to consider renaming breakpoint
> locations to something else.
Because we want to use "location" for location specifications, and I
would like us to avoid a confusing ambiguity.
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v3] gdb/manual: Introduce location specs
2022-05-26 6:50 ` Eli Zaretskii
@ 2022-05-26 12:26 ` Pedro Alves
2022-05-26 13:52 ` Eli Zaretskii
0 siblings, 1 reply; 12+ messages in thread
From: Pedro Alves @ 2022-05-26 12:26 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
On 2022-05-26 07:50, Eli Zaretskii wrote:
>> Thus, is this version OK to apply?
>
> Unfortunately, no. Please see the comments below.
Thanks for the review. Much appreciated. Hopefully we're getting closer
to meeting in the middle.
>> +@item break @var{locspec}
>> +Set a breakpoint at all the locations the given @var{locspec} matches.
>
> This should say something like
>
> Set a breakpoint at all the program addresses that match the
> @dfn{location specification} @var{locspec}.
>
> We could also use "all the places in the program code" instead of "all
> the program addresses". Or maybe you or someone else will be able to
> propose other alternatives. But we should not use "location" to mean
> the actual resolved address where the breakpoint will break.
I like many of the suggestions you made in this direction for e.g.,
the "list" command and others. But not for breakpoints. (now, the following
few replies to your comments happen to all be in the area, but if you look further
below, I agree with your suggestions a lot more...)
Because what you suggest above is not equivalent: what really happens is that we do set
a breakpoint at each location {address, function name, filename, line} in the
program that matches the spec. Recall my inline functions example in the other thread.
If we think only in terms of addresses, GDB would behave differently in that inlines example.
It's not just the address that matters. Like in geography, you can think of locations
having coordinates (e.g., {x,y,z}), and address is just one of them.
Like below for example, you start with a locspec like "main", and the breakpoint is set at
..../gdb.c:25.
(top-gdb) b main
(top-gdb) info breakpoints
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
All the info in the "Address" and "What" columns above define the coordinates of the location
in the program, not just the address. The function name is important. The line number is important.
Etc.
The set breakpoint is then implemented by placing a breakpoint instruction at the address
of each of the breakpoint's locations.
This is what we need to convey. Just talking about addresses is only talking about
the implementation detail, not what the users see, and not all that matters about each
location.
I also would like the text to make sense once we make "info breakpoints"
display the breakpoint locations the same way regardless of how many locations
the breakpoint is set at.
>
>> +@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 any of the code at any of the breakpoint's
>> +locations.
> ^^^^^^^^^
> "addresses", not "locations".
I think it should be both. "breakpoint's locations' addresses".
I went with that.
>
>> +It is possible that a breakpoint corresponds to several locations in
>> +your program. @xref{Location Specifications}, for examples.
>
> I would rephrase:
>
> It is possible that a breakpoint's location spec corresponds to
> several places in your program.
IMO, it just adds to confusion. The cindex (just above) is called "multiple locations".
There's is nothing wrong with saying "locations". We have been saying "location" all
these years. Only the xref needs to change, which is what I was doing.
>
>> @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 find any location that
>> +matches the location spec (@pxref{Location Specifications}):
>
> This should say "...cannot resolve the breakpoint's location spec to
> an address". IOW, the only problem in the original text was with
> using "address specification", where we now want to use "location
> specification" instead.
Yes, but it's not as correct. If "break" didn't find any location {line number,
function name, etc.) that matches whatever was specified in the location
spec, then the breakpoint ends up with no breakpoint locations, and in
that particular case, the breakpoint is called a pending breakpoint.
If GDB manages to create a breakpoint location for the breakpoint later, when
new symbols are loaded, and _afterwards_ the code at that location goes away (due to
shared library unload, for example), the breakpoint doesn't go back to being a pending
breakpoint -- GDB will remember the location where the breakpoint location was set at,
with only the _address_ of the location being unresolved, not the breakpoint itself.
I had text about this in the "info breakpoints" patch.
Once we get to make "info breakpoints" always list the breakpoints
the same way whether they have 0, 1 or more locations, then it makes a
lot of sense to describe pending breakpoints like that -- they have 0 locations.
And if we use the same terminology here, everything is cohesive.
I've added "in the program" to make it a bit clearer.
>
>> @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 find any
>> +location that matches the location spec, it queries you whether a
>> +pending breakpoint should be created.
>
> "When @value{GDBN} cannot resolve the breakpoint's location spec to an
> address, it queries you whether..."
>
>> @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 find any location that
>> +matches the location spec, it should create a pending breakpoint
>> +without asking for confirmation.
>
> "This indicates that when @value{GDBN} cannot resolve a location spec,
> it should create a @dfn{pending breakpoint} without asking for
> confirmation."
Done.
>
>> @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
>> +This indicates that pending breakpoints are not to be created. If
>> +@value{GDBN} cannot find any location that matches the location spec,
>> +it aborts the breakpoint creation with an error. This setting does
>> not affect any pending breakpoints previously created.
>
> Similar rephrasing here.
Done.
>
>> The settings above only affect the @code{break} command and its
>> -variants. Once breakpoint is set, it will be automatically updated
>> -as shared libraries are loaded and unloaded.
>> +variants. Once a breakpoint is created, it will be automatically
>> +updated as shared libraries are loaded and unloaded.
>
> I don't necessarily object, but can you tell why "breakpoint is set"
> was not good enough? After all the description of the "break" command
> says "Set a breakpoint...", so the original text here was being
> consistent with that.
No good reason. Done.
>
>> -@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 any breakpoints set at the locations that match @var{locspec}.
>
> "Delete any breakpoints set at addresses that match the location spec
> @var{locspec}."
No, that is ambiguous, it kind of suggests that you can only pass
address location specs here.
The old text talked about "location", and I think we should continue doing
so. It is just that we can now be unambiguous with location vs location spec.
The command isn't driven by addresses solely. See clear_command.
If the locspec specifies a line, then the command matches breakpoint
locations by line, and when it specifies explicit addresses, it matches
locations by address. The algorithm is different.
The text goes on to say "the most useful ones are listed below:", and then
explain in more detail how it behaves with different locspecs.
So I think this should stay as I proposed.
>
>> +Whenever execution reaches a location 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.
>
> "Whenever execution reaches an address that matches @var{locspec}, ..."
>
Addresses only match location specs if you start with an address
location spec, like "dprintf *ADDRESS". The original text already said:
Whenever execution reaches @var{location}
So strip away the "@var" as it is lo longer a variable, and this is
already saying --
Whenever execution reaches location.
Since we now can distinguish between program location and the syntaxes
used to specify a location, it makes sense to extend that to say:
Whenever execution reaches the location that matches the @var{locspec}.
and since locspec can resolve to multiple locations, just like a breakpoint,
we just adjust to use plural form, like:
Whenever execution reaches a location that matches @var{locspec}.
If the locspec is a line number, this can by read as "whenever execution reaches
the line number that matches the line number specified by locspec. If
the locspec is a function name, this can be read as "whenever execution
read the function that matches the function specified by locspec." Etc.
It just makes sense that way. Please let's not shy away from "location" as
if it was a forbidden word.
>
>> Functions may be skipped by providing either a function name, linespec
> ^^^^^^^^^^^^^^^^^^^^^^^
> Does "skip" support only some of the location specification formats? If
> it supports all of them, we should just say "location specification"
> there instead of using these two terms.
It doesn't:
(top-gdb) skip *0x000000000086def1
Function *0x000000000086def1 will be skipped when stepping.
(top-gdb) info skip
Num Enb Glob File RE Function
1 y n <none> n *0x000000000086def1
(top-gdb) skip -line 10
Invalid skip option: -line
>
>> +In general, the @code{list} command expects you to supply zero, one or
>> +two location specs. The location specs specify source lines; there
>> +are several ways of writing them (@pxref{Location Specifications}),
>> +but the effect is always to specify some source line.
>
> The last sentence should say
>
> "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."
I like that. Done.
>
>> +@item list @var{locspec}
>> +Print lines centered around the line or lines for the locations that
>> +match @var{locspec}.
>
> "Print lines centered around the line or lines for the addresses that
> match @var{linespec}."
I take it you mean "for the lines". I went with:
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} match
>> +more than one location in the program, then the list command will
>> +print the list of ambiguous locations and does not print any source
>> +lines.
>
> The last sentence should say
>
> "If either @var{first} or @var{last} match more than one source line
> in the program, the @code{list} command will show the list of
> ambiguous source lines, and will not print any source lines."
I like the first part about matching lines, but I think "show the list of ambiguous source lines"
is worse, because it's ambiguous that way -- it ends up with "source lines" used twice to mean different
things. The first refers to the location in the program, the second refers to the contents
of source code at the lines. And, GDB prints more location coordinates than lines when ambiguous:
file: "/home/pedro/gdb/binutils-gdb/src/gdb/gdb.c", line number: 25, symbol: "main(int, char**)"
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/1.cc", line number: 61, symbol: "selftests::string_view::cons_1::main()"
file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/2.cc", line number: 40, symbol: "selftests::string_view::cons_2::main()"
...
So for now I changed the first part per your suggestion, and kept
"list of ambiguous locations".
>
>> +Likewise, if @var{last} matches more than one location in the program,
>> +then the list command will print the list of ambiguous locations and
>> +does not print any source lines.
>
> Likewise here.
Done.
>
>> +A location spec serves as a blueprint, and it may match more than one
>> +actual location in your program. Examples of this situation are:
> ^^^^^^^^
> "address".
>
We're defining a location spec here, so that would be an overcorrection. There's nothing
wrong with referring to "a location in the program". It's even exposed to C++ users in
the language itself: https://en.cppreference.com/w/cpp/utility/source_location
This should really say that specifications match actual locations. The "spec"
qualifier in "location spec" makes this unambiguous, and the point is really to
distinguish the "spec" from the actual "thing".
It is no different from saying:
"a cake specification serves as a blueprint, and it may match more than one
actual cake in the cake shop".
There is nothing ambiguous in this sentence using cakes. And I am saying the
exact same thing, but for locations.
I did notice that I forgot to add a @dfn{location specification}. I did that now,
in that paragraph quoted above.
>> +@item edit @var{locspec}
>> +Edit the source file specified by @code{locspec}. Editing starts at
>> +the specified location, e.g., at the specified source line of the
>> +specified file. @xref{Location Specifications}, for all the possible
>> +forms of the @var{locspec} argument.
>> +
>> +If @code{locspec} matches more than one location in your program, then
> ^^^^^^^^
> "source line"
>
>> +the command prints the list of locations and does not proceed with the
> ^^^^^^^^^
> "source lines"
Done.
>
>> We can also inquire (using @code{*@var{addr}} as the form for
>> -@var{location}) what source line covers a particular address:
>> +@var{locspec}) what source line covers a particular address:
>
> "You can also inquire (using @code{*@var{addr}} as the form for
> @var{locspec}) what source line covers a particular address
> @var{addr}:"
AFAICS, you're suggesting to add "@var{addr}".
I don't think that would be correct without other changes. Try reading the
sentence without the parenthesis, it wouldn't make sense then:
"You can also inquire what source line covers a particular address
@var{addr}:"
because "addr" is not referred to in the example that follows, it is only referring
to the addr in the parenthesized part. So I think that if you want to
add "addr" here, the sentence should be tweaked further.
I'm only after changing the name of the @var{location} variable, though.
>
>> +@item info macros @var{locspec}
>> +Show all macro definitions that are in effect at the first location in
>> +your program that matches @var{locspec}, and describe the source
>> +location or compiler command-line where those definitions were
>> +established.
>
> "Show all macro definitions that are in effect at the first address in
> your program that matches @var{locspec}, and describe the place in the
> source code or compiler command-line where those definitions were
> established."
What we had before is better -- referring to addresses here is confusing.
Macros is a source concept, while addresses are lower level.
Please let's keep using "location", just like we said before my change.
There is no ambiguity here.
>
>> 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 locations that match
>> +@var{locspec}. ^^^^^^^^^
>
> "addresses"
>
>> It may not be possible to set a static tracepoint at
>> +the desired location, in which case the command will exit with an
>
> "It may not be possible to set a static tracepoint at any address that
> matches @var{locspec}, in which case..."
>
>> @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}} as location. This probes the marker
>
> "...the user can also specify @code{-m @var{marker}} instead of a
> location spec."
I like this one, done.
>
>> -@item info scope @var{location}
>> +@item info scope @var{locspec}
>> 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:
>> +accepts a location specification 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 the first location in your
> ^^^^^^^^
> "address" or "place".
>
"address" here is confusing in the same way. There's nothing wrong with
using "location" here. "place" is just odd since we never define what it is.
Please, let's not avoid "location" just because. The text is not ambiguous with
it, as we distinguish "location spec" from "location". If we used "place"
instead of "location" throughout, then we should have a "place spec" instead of
a "location spec".
>> +@item jump @var{locspec}
>> +@itemx j @var{locspec}
>> +Resume execution at the location that matches @var{locspec}.
> ^^^^^^^^
> "address"
Since fine to say address in this case, but I think we should say "resolves to"
instead of matches, because using "matches" along with "address" kind of suggests
that you should pass down an address locspec. "Resolves to" removes that ambiguity.
>
>> +@xref{Location Specifications}, for a description of the different
>> +forms of @var{locspec}. If @var{locspec} matches more than one
>> +location, the command aborts before jumping to any location.
> ^^^^^^^^
> "address". And "to any location" at the end can be simply removed.
I went with "resolving" here too, like:
If @var{locspec} resolves to more than one address, the command aborts before jumping.
>
>> 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} matches a
>> +location in a different function from the one currently executing, the
> ^^^^^^^^
> "address"
Done.
>
>> +@item break-range @var{start-locspec}, @var{end-locspec}
>> Set a breakpoint for an address range given by
>> -@var{start-location} and @var{end-location}, which can specify a function name,
>> +@var{start-locspec} and @var{end-locspec}, 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}.)
>> +location, or an address of an instruction (see @ref{Location Specifications},
>> +for a list of all the possible ways to specify a location spec).
>> +If either @var{start-locspec} or @var{end-locspec} match multiple
>> +locations in the program, then the command aborts with an error
> ^^^^^^^^^
> "addresses"
Done.
>
>> @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 a location that matches @var{locspec} is
>> +reached.
>
> "Executes the inferior until it reaches an address that matches
> @var{locspec}."
I think that reads worse than before. It was good to say "location" before
my change, so it should still be good after. Please let's not overcorrect here.
Notice how the text talks about source lines in the following sentence. We
don't have to talk about lower level addresses. It's better for users to
think about reaching some location in the program, like a line number for
example.
>
>> @item line
>> -Line specification is required as parameter. @xref{Specify Location}.
>> +Line specification is required as parameter. @xref{Location Specifications}.
> ^^^^^^^^^^^^^^^^^^
> "Line specification" or "location specification"?
I looked now, and this really accepts any form, so should be changed to "location specification":
(top-gdb) interpreter-exec mi "-trace-find line \"-function foo\""
^done,found="0",frame={level="0",addr="0x000055555564106c",func="main",args=[{name="argc",value="1"},{name="argv",value="0x7fffffffdc48"}],file="/home/pedro/gdb/binutils-gdb/src/gdb/gdb.c",fullname="/net/cascais.nfs/brno/pedro/gdb/binutils-gdb/src/gdb/gdb.c",line="25",arch="i386:x86-64"}
(top-gdb) interpreter-exec mi "-trace-find line \"-foo\""
^error,msg="invalid explicit location argument, \"-foo\""
(top-gdb) interpreter-exec mi "-trace-find line *0x000055555564106c"
^done,found="0",frame={level="0",addr="0x000055555564106c",func="main",args=[{name="argc",value="1"},{name="argv",value="0x7fffffffdc48"}],file="/home/pedro/gdb/binutils-gdb/src/gdb/gdb.c",fullname="/net/cascais.nfs/brno/pedro/gdb/binutils-gdb/src/gdb/gdb.c",line="25",arch="i386:x86-64"}
So, done.
>
>> -If @code{-at} is given, generate remote agent bytecode for @var{location}.
>> +If @code{-at} is given, generate remote agent bytecode for all
>> +locations that match @var{linespec} (@pxref{Linespec Locations}).
>
> Same question here.
(I mentioned this one in the commit log.) This command only accepts the linespec
format, so "Line specification" is correct here.
if (check_for_argument (&exp, "-at", sizeof ("-at") - 1))
{
struct linespec_result canonical;
event_location_up location
= new_linespec_location (&exp, symbol_name_match_type::WILD);
^^^^^^^^^^^^^^^^^^^^^
Trying other formats gets you:
(top-gdb) maint agent -at *0x123
Function "*0x123" not defined.
(top-gdb) maint agent -at -function main
Function "-function main" not defined.
>
> Thanks.
>
Thank you.
Here's v3. I've also updated the commit log to match.
From 28700550b760519f6c49979a1d58b30aa9a2ceac Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 17 May 2022 13:12:04 +0100
Subject: [PATCH v3] 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 locations
(plural) in the program that match. For example, a "location"
specified like "-function func" will actually match all the 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 "-label lab"
matches all the addresses & source lines of where a C label name "lab"
is defined. 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 matched locations. In other cases, the command
aborts with an error if the location specification matches multiple
locations in the program. In other cases, GDB just arbitrarily and
silently picks whatever is the first location that matches (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 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 location in the program. It explains that a location
specification may match multiple locations in the program. It gives
examples of how that happens. 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 matches more than one
location in the program. 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 | 374 ++++++++++++++++++++++++--------------------
gdb/doc/guile.texi | 2 +-
gdb/doc/python.texi | 5 +-
3 files changed, 210 insertions(+), 171 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 68679982919..32797b16596 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 locations the given @var{locspec} matches.
+@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 any of the code at any of the breakpoint's
+locations' adresses.
-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,28 +4616,8 @@ 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 breakpoint corresponds to several 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
@@ -4711,31 +4693,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 find any location in the
+program that matches the location spec (@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 +5440,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 any breakpoints with 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 +5800,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 location 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 +6299,11 @@ 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 location 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 +6324,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 location that matches
+@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 +6428,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 +6465,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 +6498,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 +7127,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 location or locations in your program's
+code. @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 +8930,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 +8946,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 +8993,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} match
+more than one source line in the program, then the list command will
+show the list of ambiguous locations and does not print any source
+lines.
@item list ,@var{last}
Print lines ending with @var{last}.
+Likewise, if @var{last} matches more than one source line in the program,
+then the list command will print the list of ambiguous locations
+and does not print any source lines.
+
@item list @var{first},
Print lines starting with @var{first}.
@@ -9041,17 +9035,47 @@ 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
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 @dfn{location specification} (a.k.a.@: location spec) serves as a
+blueprint, and it may match more than one actual location in your
+program. Examples of this situation are:
+
+@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 +9294,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 specified location, e.g., at the specified source line of the
+specified file. @xref{Location Specifications}, for all the possible
+forms of the @var{locspec} argument.
+
+If @code{locspec} matches more than one source line in your program,
+then the command prints the list of 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 +9684,11 @@ 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 match @var{locspec}. You can specify source lines in any of
+the ways documented in @ref{Location Specifications}. 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
@@ -9675,7 +9704,7 @@ 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:
+@var{locspec}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
@@ -9883,10 +9912,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 as 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 +14201,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 first location in
+your program that matches @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 +14507,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 +14546,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 +14585,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 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 +17470,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 +18793,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 +19561,13 @@ These commands can be used to enable or disable type printers.
@kindex info scope
@cindex local variables
-@item info scope @var{location}
+@item info scope @var{locspec}
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:
+accepts a location specification 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 the first location in your
+program that matches @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 +20155,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 +25399,18 @@ use the @code{break-range} command.
@table @code
@kindex break-range
-@item break-range @var{start-location}, @var{end-location}
+@item break-range @var{start-locspec}, @var{end-locspec}
Set a breakpoint for an address range given by
-@var{start-location} and @var{end-location}, which can specify a function name,
+@var{start-locspec} and @var{end-locspec}, 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}.)
+location, or an address of an instruction (see @ref{Location Specifications},
+for a list of all the possible ways to specify a location spec).
+If either @var{start-locspec} or @var{end-locspec} resolves 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-location} and @var{end-location}.)
+(including @var{start-locspec} and @var{end-locspec}.)
@kindex set powerpc
@item set powerpc soft-float
@@ -31192,11 +31229,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 +31272,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 +31357,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 +31372,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 +32588,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 +32907,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 a location that matches @var{locspec} 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}.
@subsubheading @value{GDBN} Command
@@ -34935,7 +34972,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 +39475,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 +39487,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
+locations that match @var{linespec} (@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
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-25 20:05 ` Pedro Alves
2022-05-25 21:24 ` Philippe Waroquiers
@ 2022-05-26 12:56 ` Eli Zaretskii
1 sibling, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2022-05-26 12:56 UTC (permalink / raw)
To: Pedro Alves; +Cc: gdb-patches
> Date: Wed, 25 May 2022 21:05:13 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
>
> > Sorry, but I don't think this is a good idea. It is IMO okay to
> > introduce "location specification" into our terminology; it is even
> > okay to use "location spec" as its shorthand. But "locspec" is too
> > much: it's not a word, so it doesn't explain itself enough, and thus
> > cannot be used very far from where it is defined, because the reader
> > will likely not understand what it means.
>
> Yet, we have "linespec" and people understand it just fine, it's described
> once in a single spot in the manual.
"Linespec" is already bad enough, which I guess is one reason why you
want to replace it (and I don't object to such a replacement). Still,
"linespec" is better than "locspec", because its first part, "line",
is a word that has quite a clear meaning in this context, "spec" is a
widely-used shorthand for "specification". By contrast, "loc" is not
a word at all, and can be a shorthand for "lock" or "locale", as well
as "location". So its semantic significance is lower and its
confusion potential is higher.
> It sounds like you are against any term that
> is new just because it is new. That just blocks progress forever. It is not reasonable.
I'm not "against any term that is new". Please be fair, and don't
interpret what I say in the worst possible way.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH] gdb/manual: Introduce locspecs
2022-05-26 6:51 ` Eli Zaretskii
@ 2022-05-26 13:41 ` Simon Marchi
0 siblings, 0 replies; 12+ messages in thread
From: Simon Marchi @ 2022-05-26 13:41 UTC (permalink / raw)
To: Eli Zaretskii, Pedro Alves; +Cc: gdb-patches
On 2022-05-26 02:51, Eli Zaretskii via Gdb-patches wrote:
>> Date: Wed, 25 May 2022 23:18:02 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>> IIUC, Eli would like to have location reserved for a breakpoint giving multiple resulting
>>> locations.
>>
>> No, he was saying he would prefer "location" to be reserved for location specifications,
>> and to find a different name for breakpoint locations.
>
> Yes.
>
>> I don't see why would we even bother to consider renaming breakpoint
>> locations to something else.
>
> Because we want to use "location" for location specifications, and I
> would like us to avoid a confusing ambiguity.
FWIW, I also think that it's clearer to keep "location" for the
concrete, resolved locations in the program. "Location specification"
makes sense as a new term for what you pass to the "break" command (and
others).
Simon
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH v3] gdb/manual: Introduce location specs
2022-05-26 12:26 ` [PATCH v3] " Pedro Alves
@ 2022-05-26 13:52 ` Eli Zaretskii
0 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2022-05-26 13:52 UTC (permalink / raw)
To: Pedro Alves; +Cc: gdb-patches
> Date: Thu, 26 May 2022 13:26:07 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
>
> I like many of the suggestions you made in this direction for e.g.,
> the "list" command and others. But not for breakpoints. (now, the following
> few replies to your comments happen to all be in the area, but if you look further
> below, I agree with your suggestions a lot more...)
>
> Because what you suggest above is not equivalent: what really happens is that we do set
> a breakpoint at each location {address, function name, filename, line} in the
> program that matches the spec. Recall my inline functions example in the other thread.
> If we think only in terms of addresses, GDB would behave differently in that inlines example.
> It's not just the address that matters. Like in geography, you can think of locations
> having coordinates (e.g., {x,y,z}), and address is just one of them.
I already asked what does a "location" entail in your eyes, in
addition to the program address to which it eventually resolves. I
don't think we will arrive at a full agreement before we see this
spelled out and documented.
And I'm not saying that address is the only thing that matters, I'm
just saying that thinking about addresses is useful when describing
how GDB uses location specs for setting breakpoints or for other
related features.
> Like below for example, you start with a locspec like "main", and the breakpoint is set at
> ..../gdb.c:25.
>
> (top-gdb) b main
> (top-gdb) info breakpoints
> 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
>
> All the info in the "Address" and "What" columns above define the coordinates of the location
> in the program, not just the address. The function name is important. The line number is important.
I'm talking about terminology, not about the aspects that are
important. You seem to be interpreting "address" too literally, and
"location" too generally.
> The set breakpoint is then implemented by placing a breakpoint instruction at the address
> of each of the breakpoint's locations.
I would say "set breakpoint is implemented by arranging for the
program to stop at every address that matches the location
specification". ("Placing a breakpoint instruction" is inaccurate,
because we have hardware-assisted breakpoints.)
> This is what we need to convey. Just talking about addresses is only talking about
> the implementation detail, not what the users see, and not all that matters about each
> location.
I think users of GDB have a clear understanding about the equivalence
between source-level locations and breakpoint addresses. If this is
an implementation detail, then it had leaked to the GDB user level
long ago.
> >> +@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 any of the code at any of the breakpoint's
> >> +locations.
> > ^^^^^^^^^
> > "addresses", not "locations".
>
> I think it should be both. "breakpoint's locations' addresses".
> I went with that.
From the English POV, there should be only one "'s", the second one.
We could also make it less awkward (double construct state is
discouraged):
...at any of the location addresses of the breakpoint.
> >> +It is possible that a breakpoint corresponds to several locations in
> >> +your program. @xref{Location Specifications}, for examples.
> >
> > I would rephrase:
> >
> > It is possible that a breakpoint's location spec corresponds to
> > several places in your program.
>
> IMO, it just adds to confusion. The cindex (just above) is called "multiple locations".
> There's is nothing wrong with saying "locations". We have been saying "location" all
> these years. Only the xref needs to change, which is what I was doing.
The main problem with "location" is that it is too general a notion,
and can mean many similar but different things. As long as we use it
only in one sense, that is somewhat tolerable, but once we start using
it for more than one thing, and related things at that, it becomes a
source of confusion.
> >> @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 find any location that
> >> +matches the location spec (@pxref{Location Specifications}):
> >
> > This should say "...cannot resolve the breakpoint's location spec to
> > an address". IOW, the only problem in the original text was with
> > using "address specification", where we now want to use "location
> > specification" instead.
>
> Yes, but it's not as correct. If "break" didn't find any location {line number,
> function name, etc.) that matches whatever was specified in the location
> spec, then the breakpoint ends up with no breakpoint locations, and in
> that particular case, the breakpoint is called a pending breakpoint.
>
> If GDB manages to create a breakpoint location for the breakpoint later, when
> new symbols are loaded, and _afterwards_ the code at that location goes away (due to
> shared library unload, for example), the breakpoint doesn't go back to being a pending
> breakpoint -- GDB will remember the location where the breakpoint location was set at,
> with only the _address_ of the location being unresolved, not the breakpoint itself.
I understand, but I don't see how this invalidates my comment and the
rewording suggestion. What is described in that text refers to
something done when defining the breakpoint, so what happens
afterwards (and is not described there) cannot affect the clarity of
the text or its interpretation by the reader, who at that point wants
only to understand what happens with these specifications.
> >> -@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 any breakpoints set at the locations that match @var{locspec}.
> >
> > "Delete any breakpoints set at addresses that match the location spec
> > @var{locspec}."
>
> No, that is ambiguous, it kind of suggests that you can only pass
> address location specs here.
It does? It explicitly says "addresses that match", so doesn't imply
that addresses are passed.
> > "If either @var{first} or @var{last} match more than one source line
> > in the program, the @code{list} command will show the list of
> > ambiguous source lines, and will not print any source lines."
>
> I like the first part about matching lines, but I think "show the list of ambiguous source lines"
> is worse, because it's ambiguous that way -- it ends up with "source lines" used twice to mean different
> things. The first refers to the location in the program, the second refers to the contents
> of source code at the lines. And, GDB prints more location coordinates than lines when ambiguous:
>
> file: "/home/pedro/gdb/binutils-gdb/src/gdb/gdb.c", line number: 25, symbol: "main(int, char**)"
> file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/1.cc", line number: 61, symbol: "selftests::string_view::cons_1::main()"
> file: "/home/pedro/gdb/binutils-gdb/src/gdb/unittests/basic_string_view/cons/char/2.cc", line number: 40, symbol: "selftests::string_view::cons_2::main()"
> ...
You are saying that the above are locations? That's again different
from what we show in "info breakpoints", even under your latest patch.
> >> +A location spec serves as a blueprint, and it may match more than one
> >> +actual location in your program. Examples of this situation are:
> > ^^^^^^^^
> > "address".
> >
>
> We're defining a location spec here, so that would be an overcorrection. There's nothing
> wrong with referring to "a location in the program". It's even exposed to C++ users in
> the language itself: https://en.cppreference.com/w/cpp/utility/source_location
>
> This should really say that specifications match actual locations. The "spec"
> qualifier in "location spec" makes this unambiguous, and the point is really to
> distinguish the "spec" from the actual "thing".
>
> It is no different from saying:
>
> "a cake specification serves as a blueprint, and it may match more than one
> actual cake in the cake shop".
>
> There is nothing ambiguous in this sentence using cakes. And I am saying the
> exact same thing, but for locations.
This analogy doesn't really work. "Cake" is a real concrete object:
you can eat it and report its taste and nutritional values; "cake
specification" (people actually use "recipe") is something entirely
different: it's a text recorded on some media.
By contrast, "location" is not a tangible object, it's an abstraction.
So its difference from "location specification" more subtle, and thus
harder to grasp. Which makes the confusion easier.
The C++ URL you pointed to doesn't talk about "location" (which, as I
said above is too general, and thus problematic), it talks about
"source location", and clearly documents its attributes. If you are
okay with using "source location" instead, I could go with it,
provided that:
. we always use these two words, never just "location"
. we consider "source location" as the result of fully resolving
a "location specification", and describe it as such
. we clearly document what a "source location" entails, i.e. what
are its attributes
> > "You can also inquire (using @code{*@var{addr}} as the form for
> > @var{locspec}) what source line covers a particular address
> > @var{addr}:"
>
> AFAICS, you're suggesting to add "@var{addr}".
Yes.
> I don't think that would be correct without other changes. Try reading the
> sentence without the parenthesis, it wouldn't make sense then:
>
> "You can also inquire what source line covers a particular address
> @var{addr}:"
>
> because "addr" is not referred to in the example that follows, it is only referring
> to the addr in the parenthesized part. So I think that if you want to
> add "addr" here, the sentence should be tweaked further.
If we don't reference "addr", the text does not explain clearly
enough what is alluded to as "particular address".
> >> @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 a location that matches @var{locspec} is
> >> +reached.
> >
> > "Executes the inferior until it reaches an address that matches
> > @var{locspec}."
>
> I think that reads worse than before. It was good to say "location" before
> my change, so it should still be good after. Please let's not overcorrect here.
Why is it overcorrection? This is about program execution, so talking
about addresses is very natural.
But if we can agree about the "source location" variant, maybe most or
all of the remaining disagreements will go away.
Thanks.
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2022-05-26 13:52 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-05-25 19:31 [PATCH] gdb/manual: Introduce locspecs Pedro Alves
2022-05-25 19:56 ` Eli Zaretskii
2022-05-25 20:05 ` Pedro Alves
2022-05-25 21:24 ` Philippe Waroquiers
2022-05-25 22:18 ` Pedro Alves
2022-05-26 6:51 ` Eli Zaretskii
2022-05-26 13:41 ` Simon Marchi
2022-05-26 12:56 ` Eli Zaretskii
2022-05-25 21:02 ` [PATCH v2] gdb/manual: Introduce location specs Pedro Alves
2022-05-26 6:50 ` Eli Zaretskii
2022-05-26 12:26 ` [PATCH v3] " Pedro Alves
2022-05-26 13:52 ` Eli Zaretskii
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).