FreeChainXenon/binutils-gdb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gdb/manual: Introduce location specs

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

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

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

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

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

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

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

Thus, this commit does the following:

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

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

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

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

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

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

Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b
This commit is contained in:
Pedro Alves 2022-05-17 13:12:04 +01:00
parent 09cb5e2312
commit 5541bfdc97
3 changed files with 304 additions and 190 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

487
gdb/doc/gdb.texinfo
View file

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

2
gdb/doc/guile.texi
View file

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

5
gdb/doc/python.texi
View file

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