This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[RFA 4/4 doc] Explicit locations
- From: Keith Seitz <keiths at redhat dot com>
- To: "gdb-patches at sourceware dot org ml" <gdb-patches at sourceware dot org>
- Date: Thu, 21 Mar 2013 16:58:58 -0700
- Subject: [RFA 4/4 doc] Explicit locations
Hi,
This patch includes all of the documentation changes for the explicit
location feature. This includes both online and manual updates.
I have chosen to depart with "the norm" while updating the online help
strings. In those commands which take locations, I've pretty much punted
describing what a "location" is to another help command, opting to keep
"help XXX" to specifically describe the command XXX. I essentially add a
cross-reference to explain what a location is. ['See "help locations"
for more help with specifying locations.']
Traditionally, we have (sort of) explicitly listed acceptable forms of
input. However, the majority of location-accepting commands simply say,
"Argument may be line number, function name, or \"*\" and an address."
IMO that is just downright misleading the user (if not worse).
As a result, I've introduced a new command class (help_class) and added
(almost verbatim) verbiage from the User Manual to explain locations. I
have written all this documentation from the standpoint that (majority
of) gdb users are professionals, i.e,. they don't need specific examples
of every possible permitted permutation.
Anyway, let the fun begin.
Keith
ChangeLog
2013-03-21 Keith Seitz <keiths@redhat.com>
* NEWS: Mention explicit locations.
* cli/cli-decode.c (help_cmd): Do not print subtopic help
for help_class.
(help_cmd_list): Likewise.
* command.h (enum command_class): Add special help-only class,
help_class.
* breakpoint.c (BREAK_ARGS_HELP): Update documentation.
(_initialize_breakpoint): Update documentation for
"clear", "strace", and "dprintf".
Add special help topic "locations".
doc/ChangeLog
2013-03-21 Keith Seitz <keiths@redhat.com>
* gdb.texinfo (Thread-Specific Breakpoints): Use "location(s)"
instead of "linespec(s)".
(Printing Source Lines): Likewise.
(Specifying a Location): Rewrite. Re-organize into separate
subections for each location type.
(Source and Machine Code): Use "location(s)" instead of
"linespec(s)".
(C Preprocessor Macros): Likewise.
(Extensions for Ada Tasks): Likewise.
(Continuing at a Different Address): Remove "linespec" examples.
Add reference to "Specify a Location"
(The -break-insert Command): Rewrite.
Add reference to appropriate manual section discussing locations.
testsuite/ChangeLog
2013-03-21 Keith Seitz <keiths@redhat.com>
* gdb.base/help.exp: Add test for "help locations".
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index 8c536c8..279c8da 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15975,10 +15975,9 @@ command" [PROBE_MODIFIER] [LOCATION] [thread
THREADNUM] [if CONDITION]\n\
PROBE_MODIFIER shall be present if the command is to be placed in a\n\
probe point. Accepted values are `-probe' (for a generic,
automatically\n\
guessed probe type) or `-probe-stap' (for a SystemTap probe).\n\
-LOCATION may be a line number, function name, or \"*\" and an address.\n\
-If a line number is specified, break at start of code for that line.\n\
-If a function is specified, break at start of code for that function.\n\
-If an address is specified, break at that exact address.\n\
+LOCATION may be a linespec, explicit, or address location. See \"help\n\
+locations\" for more help with specifying locations.\n\
+\n\
With no LOCATION, uses current execution address of the selected\n\
stack frame. This is useful for breaking on return to a stack frame.\n\
\n\
@@ -16511,11 +16510,9 @@ This command may be abbreviated \"delete\"."),
&deletelist);
add_com ("clear", class_breakpoint, clear_command, _("\
-Clear breakpoint at specified line or function.\n\
-Argument may be line number, function name, or \"*\" and an address.\n\
-If line number is specified, all breakpoints in that line are cleared.\n\
-If function is specified, breakpoints at beginning of function are
cleared.\n\
-If an address is specified, breakpoints at that address are cleared.\n\
+Clear breakpoint at specified location.\n\
+Argument may be a linespec, explicit, or address location. Seen\n\
+\"help locations\" for more help with specifying locations.\n\
\n\
With no argument, clears all breakpoints in the line that the
selected frame\n\
is executing in.\n\
@@ -16752,12 +16749,10 @@ Do \"help tracepoints\" for info on other
tracepoint commands."));
Set a static tracepoint at specified line, function or marker.\n\
\n\
strace [LOCATION] [if CONDITION]\n\
-LOCATION may be a line number, function name, \"*\" and an address,\n\
-or -m MARKER_ID.\n\
-If a line number is specified, probe the marker at start of code\n\
-for that line. If a function is specified, probe the marker at start\n\
-of code for that function. If an address is specified, probe the marker\n\
-at that exact address. If a marker id is specified, probe the marker\n\
+LOCATION may be a linespec, explicit, or address location or\n\
+or -m MARKER_ID. See \"help locations\" for more help with specifying\n\
+locations.\n\
+If a marker id is specified, probe the marker\n\
with that name. With no LOCATION, uses current execution address of\n\
the selected stack frame.\n\
Static tracepoints accept an extra collect action -- ``collect
$_sdata''.\n\
@@ -16921,12 +16916,10 @@ an instruction at any address within the
[START-LOCATION, END-LOCATION]\n\
range (including START-LOCATION and END-LOCATION)."));
c = add_com ("dprintf", class_breakpoint, dprintf_command, _("\
-Set a dynamic printf at specified line or function.\n\
+Set a dynamic printf at specified location.\n\
dprintf location,format string,arg1,arg2,...\n\
-location may be a line number, function name, or \"*\" and an address.\n\
-If a line number is specified, break at start of code for that line.\n\
-If a function is specified, break at start of code for that function.\n\
-"));
+location may be a linespec, explicit, or address location. See \"help\n\
+locations\" for more help with specifying locations."));
set_cmd_completer (c, location_completer);
add_setshow_enum_cmd ("dprintf-style", class_support,
@@ -16975,4 +16968,108 @@ agent-printf \"printf format string\", arg1,
arg2, arg3, ..., argn\n\
automatic_hardware_breakpoints = 1;
observer_attach_about_to_proceed (breakpoint_about_to_proceed);
+
+ add_com ("locations", help_class, NULL,
+ _("GDB supports several ways to specify locations. Any place\n\
+a location is required, any of the following forms is permissible.\n\
+\n\
+ A LINESPEC is a colon-separated list of source location parameters\n\
+ such as file name, function name, etc. Acceptable forms of linespecs\n\
+ include:\n\
+\n\
+ LINENUM\n\
+ Specifies the line number LINENUM of the current source file.\n\
+\n\
+ -OFFSET\n\
+ +OFFSET\n\
+ Specifies the line OFFSET lines before or after the current line.\n\
+\n\
+ FILE:LINENUM\n\
+ Specifies the line LINENUM in the source file FILE. If FILE\n\
+ is a relative file name, then it will match any source file name\n\
+ with the same trailing components.\n\
+\n\
+ FUNCTION\n\
+ Specifies the line that begins the body of the function FUNCTION.\n\
+ For example, in C, this is the line with the open brace.\n\
+\n\
+ FUNCTION:LABEL\n\
+ Specifies the line where LABEL appears in FUNCTION.\n\
+\n\
+ FILE:FUNCTION\n\
+ Specifies the line that begins the body of the function FUNCTION\n\
+ in the file FILE. You only need the file name with a function\n\
+ name to avoid ambiguity when there are identically named functions\n\
+ in different source files.\n\
+\n\
+ LABEL\n\
+ Specifies the line at which the label named LABEL appears in the\n\
+ function corresponding to the current stack frame. If there is\n\
+ no current selected frame (for instance, if the inferior is not\n\
+ running), then GDB will not search for a label.\n\
+\n\
+ EXPLICIT LOCATIONS bypass the linespec parser, allowing the user to\n\
+ explicitly specify the source location's parameters. They are
specified\n\
+ using option-value pairs listed in the table below.\n\
+\n\
+ Parsing linespecs often involves multiple searches through the
program's\n\
+ symbol table or the file system. For large programs, this may be\n\
+ extremely time-consuming. Explicit locations may help avoid a lot of\n\
+ this unnecessary searching.\n\
+\n\
+ The list of valid explicit location options is summarized in the\n\
+ following table:\n\
+\n\
+ -source\n\
+ The value specifies the source file name. This option\n\
+ requires the use of either -function or -line.\n\
+\n\
+ -function\n\
+ The value specifies the name of a function. Operations\n\
+ on function locations unmodified by other options (such as\n\
+ -label or -line) affect the line that begins the body of the\n\
+ function. In C, for example, this is the line with the open
brace.\n\
+\n\
+ -label\n\
+ The value specifies a line offset for that location. The offset\n\
+ may either be absolute (-line 3) or relative (-line +3), depending\n\
+ on the command. When specified without any other options, the\n\
+ line offset is relative to the current function.\n\
+\n\
+ Explicit location options may be abbreviated by omitting any
non-unique\n\
+ trailing characters from the option name, e.g.,\n\
+ \"break -s main.c -li 3\".\n\
+\n\
+ ADDRESS LOCATIONS indicate a specific program address. They have the\n\
+ generalized form *ADDRESS.\n\
+\n\
+ For line-oriented commands, such as list and edit, this specifies\n\
+ a source line that contains ADDRESS. For break and other breakpoint-\n\
+ oriented commands, this can be used to set breakpoints in parts of\n\
+ your program which do not have debugging information or source files.\n\
+\n\
+ ADDRESS may be any expression valid in the current working language\n\
+ that specifies a code address. In addition, as a convenience, GDB\n\
+ extends the semantics of expressions used in locations to cover
several\n\
+ situations that frequently occur during debugging. Here are the
various\n\
+ forms of ADDRESS:\n\
+\n\
+ EXPRESSION\n\
+ Any expression valid in the current working language.\n\
+\n\
+ FUNCADDR\n\
+ An address of a function or procedure derived from its name. In C,\n\
+ C++, Java, Objective-C, Fortran, minimal, and assembly, this is\n\
+ simply the function's name FUNCTION (and actually a special case
of\n\
+ a valid expression). In Ada, this is FUNCTION'Address (although\n\
+ the Pascal form also works).\n\
+\n\
+ This form specifies the address of the function's first
instruction,\n\
+ before the stack frame and arguments have been set up.\n\
+\n\
+ 'FILE'::FUNCADDR\n\
+ Like FUNCADDR above, but also specifies the name of the source\n\
+ file explicitly. This is useful if the name of the function does\n\
+ not specify the function unambiguously, e.g., if there are several\n\
+ functions with identical names in different source files."));
}
diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
index 61a7b5a..95b55c1 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -948,7 +948,8 @@ help_cmd (char *arg, struct ui_file *stream)
fputs_filtered (c->doc, stream);
fputs_filtered ("\n", stream);
- if (c->prefixlist == 0 && c->func != NULL)
+ if ((c->prefixlist == 0 && c->func != NULL)
+ || c->class == help_class)
return;
fprintf_filtered (stream, "\n");
@@ -1161,7 +1162,8 @@ help_cmd_list (struct cmd_list_element *list, enum
command_class class,
for (c = list; c; c = c->next)
{
- if (c->abbrev_flag == 0
+ if (c->class != help_class
+ && c->abbrev_flag == 0
&& (class == all_commands
|| (class == all_classes && c->func == NULL)
|| (class == c->class && c->func != NULL)))
diff --git a/gdb/command.h b/gdb/command.h
index 81edc43..777e847 100644
--- a/gdb/command.h
+++ b/gdb/command.h
@@ -33,7 +33,8 @@
enum command_class
{
/* Special args to help_list */
- class_deprecated = -3, all_classes = -2, all_commands = -1,
+ class_deprecated = -4, help_class = -3, all_classes = -2,
+ all_commands = -1,
/* Classes of commands */
no_class = -1, class_run = 0, class_vars, class_stack, class_files,
class_support, class_info, class_breakpoint, class_trace,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4ac28bb..0c2e04a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5784,9 +5784,9 @@ breakpoints on all threads, or on a particular thread.
@cindex breakpoints and threads
@cindex thread breakpoints
@kindex break @dots{} thread @var{threadno}
-@item break @var{linespec} thread @var{threadno}
-@itemx break @var{linespec} thread @var{threadno} if @dots{}
-@var{linespec} specifies source lines; there are several ways of
+@item break @var{location} thread @var{threadno}
+@itemx break @var{location} thread @var{threadno} 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.
@@ -6931,21 +6931,21 @@ 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{linespecs}. Linespecs specify source lines; there are several ways
+@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.
Here is a complete description of the possible arguments for @code{list}:
@table @code
-@item list @var{linespec}
-Print lines centered around the line specified by @var{linespec}.
+@item list @var{location}
+Print lines centered around the line specified by @var{location}.
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs. When a @code{list} command has two linespecs, and the
-source file of the second linespec is omitted, this refers to
-the same source file as the first linespec.
+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.
@item list ,@var{last}
Print lines ending with @var{last}.
@@ -6970,15 +6970,21 @@ As described in the preceding table.
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;
-for that reason, locations are also known as @dfn{linespecs}.
+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.
-Here are all the different ways of specifying a code location that
-@value{GDBN} understands:
+@node Linespec Locations
+@subsection Linespec Locations
+
+A @dfn{linespec} is a colon-separated list of source location
parameters such
+as file name, function name, etc. They are parsed and converted into an
+internal representation used by @value{GDBN}. Here are all the
+different ways of specifying a linespec:
@table @code
@item @var{linenum}
-Specifies the line number @var{linenum} of the current source file.
+Specifies the line number @var{linenum} of the @dfn{current source} file.
@item -@var{offset}
@itemx +@var{offset}
@@ -7013,25 +7019,90 @@ function name to avoid ambiguity when there are
identically named
functions in different source files.
@item @var{label}
-Specifies the line at which the label named @var{label} appears.
-@value{GDBN} searches for the label in the function corresponding to
-the currently selected stack frame. If there is no current selected
-stack frame (for instance, if the inferior is not running), then
-@value{GDBN} will not search for a label.
-
-@item *@var{address}
-Specifies the program address @var{address}. For line-oriented
-commands, such as @code{list} and @code{edit}, this specifies a source
-line that contains @var{address}. For @code{break} and other
-breakpoint oriented commands, this can be used to set breakpoints in
+Specifies the line at which the label named @var{label} appears
+in the function corresponding to the currently selected stack frame.
+If there is no current selected stack frame (for instance, if the inferior
+is not running), then @value{GDBN} will not search for a label.
+
+@cindex breakpoint at static probe point
+@item -pstap|-probe-stap
@r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes. @xref{Static Probe Points}, for more
+information on finding and using static probes. This form of linespec
+specifies the location of such a static probe.
+
+If @var{objfile} is given, only probes coming from that shared library
+or executable matching @var{objfile} as a regular expression are
considered.
+If @var{provider} is given, then only probes from that provider are
considered.
+If several probes match the spec, @value{GDBN} will insert a breakpoint at
+each one of those probes.
+@end table
+
+@node Explicit Locations
+@subsection Explicit Locations
+@cindex explicit locations
+
+@dfn{Explict locations} bypass the linespec parser, allowing the user
+to explicitly specify the source location's parameters. They are specified
+using option-value pairs listed in the table below.
+
+Parsing linespecs often involves multiple searches through the program's
+symbol table or the file system. For large programs, this may be extremely
+time-consuming. Explicit locations may help avoid a lot of this
+unnecessary searching.
+
+For example, the linespec ``foo:bar'' may refer to a function ``bar''
+defined in the file named ``foo'' or the label ``bar'' in a function
+named ``foo''. @value{GDBN} must search either the file system or
+the symbol table to know.
+
+The list of valid explicit location options is summarized in the
+following table:
+
+@table @code
+@item -source
+The value specifies the source file name. This option
+requires the use of either @code{-function} or @code{-line}.
+
+@item -function
+The value specifies the name of a function. Operations
+on function locations unmodified by other options (such as @code{-label}
+or @code{-line}) affect the line that begins the body of the function.
+In C, for example, this is the line with the open brace.
+
+@item -label
+The value specifies the name of a label. When the function
+name is not specified, the label is searched in the function of the
currently
+selected stack frame.
+
+@item -line
+The value specifies a line offset for the location. The offset may either
+be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on
+the command. When specified without any other options, the line offset is
+relative to the current function.
+@end table
+
+Explicit location options may be abbreviated by omitting any non-unique
+trailing characters from the option name, e.g., @code{break -s main.c
-li 3}.
+
+@node Address Locations
+@subsection Address Locations
+@cindex address locations
+
+@dfn{Address locations} indicate a specific program address. They have
+the generalized form *@var{address}.
+
+For line-oriented commands, such as @code{list} and @code{edit}, this
+specifies a source line that contains @var{address}. For @code{break} and
+other breakpoint-oriented commands, this can be used to set breakpoints in
parts of your program which do not have debugging information or
source files.
-Here @var{address} may be any expression valid in the current working
+@var{address} may be any expression valid in the current working
language (@pxref{Languages, working language}) that specifies a code
address. In addition, as a convenience, @value{GDBN} extends the
-semantics of expressions used in locations to cover the situations
-that frequently happen during debugging. Here are the various forms
+semantics of expressions used in locations to cover several situations
+that frequently occur during debugging. Here are the various forms
of @var{address}:
@table @code
@@ -7056,22 +7127,6 @@ specify the function unambiguously, e.g., if
there are several
functions with identical names in different source files.
@end table
-@cindex breakpoint at static probe point
-@item -pstap|-probe-stap
@r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
-The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
-applications to embed static probes. @xref{Static Probe Points}, for more
-information on finding and using static probes. This form of linespec
-specifies the location of such a static probe.
-
-If @var{objfile} is given, only probes coming from that shared library
-or executable matching @var{objfile} as a regular expression are
considered.
-If @var{provider} is given, then only probes from that provider are
considered.
-If several probes match the spec, @value{GDBN} will insert a breakpoint at
-each one of those probes.
-
-@end table
-
-
@node Edit
@section Editing Source Files
@cindex editing source files
@@ -7389,9 +7444,9 @@ well as hex.
@table @code
@kindex info line
-@item info line @var{linespec}
+@item info line @var{location}
Print the starting and ending addresses of the compiled code for
-source line @var{linespec}. You can specify source lines in any of
+source line @var{location}. You can specify source lines in any of
the ways documented in @ref{Specify Location}.
@end table
@@ -7409,7 +7464,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and
ends at 0x6350.
@noindent
@cindex code address and its source line
We can also inquire (using @code{*@var{addr}} as the form for
-@var{linespec}) what source line covers a particular address:
+@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
@@ -7519,7 +7574,7 @@ Dump of assembler code from 0x400281 to 0x40028b:
End of assembler dump.
@end smallexample
-Addresses cannot be specified as a linespec (@pxref{Specify Location}).
+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}.
@@ -10848,9 +10903,9 @@ 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{linespec}
+@item info macros @var{location}
Show all macro definitions that are in effect at the location specified
-by @var{linespec}, and describe the source location or compiler
+by @var{location}, and describe the source location or compiler
command-line where those definitions were established.
@kindex macro define
@@ -14973,14 +15028,14 @@ from the current task to the given task.
#4 0x804aacc in un () at un.adb:5
@end smallexample
-@item break @var{linespec} task @var{taskno}
-@itemx break @var{linespec} task @var{taskno} if @dots{}
+@item break @var{location} task @var{taskno}
+@itemx break @var{location} 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}).
-@var{linespec} specifies source lines, as described
+@var{location} specifies source lines, as described
in @ref{Specify Location}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
@@ -15806,20 +15861,17 @@ an address of your own choosing, with the
following commands:
@table @code
@kindex jump
@kindex j @r{(@code{jump})}
-@item jump @var{linespec}
-@itemx j @var{linespec}
-@itemx jump @var{location}
+@item jump @var{location}
@itemx j @var{location}
-Resume execution at line @var{linespec} or at address given by
-@var{location}. Execution stops again immediately if there is a
-breakpoint there. @xref{Specify Location}, for a description of the
-different forms of @var{linespec} and @var{location}. It is common
+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}.
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 line @var{linespec} is in
+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
@@ -28784,22 +28836,42 @@ N.A.
@smallexample
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
- [ -p @var{thread-id} ] [ @var{location} ]
+ [ -p @var{thread-id} ] @var{location}
+
@end smallexample
@noindent
If specified, @var{location}, can be one of:
-@itemize @bullet
-@item function
-@c @item +offset
-@c @item -offset
-@c @item linenum
-@item filename:linenum
-@item filename:function
-@item *address
-@end itemize
+@table @var
+@item linespec location
+A linespec location. @xref{Linespec Locations}.
+
+@item explicit location
+An explicit location. @sc{gdb/mi} explicit locations are
+analogous to @value{GDBN}'s explicit locations using the option names
+listed below. @xref{Explicit Locations}.
+
+@table @samp
+@item -s @var{filename}
+The source file name of the location. This option requires the use
+of either @samp{-m} or @samp{-o}.
+@item -m @var{function}
+The name of a function or method.
+
+@item -l @var{label}
+The name of a label.
+
+@item -o @var{lineoffset}
+An absolute or relative offset from the start of the location.
+@end table
+
+@item address location
+An address location, *@var{address}. @xref{Address Locations}.
+@end table
+
+@noindent
The possible optional parameters of this command are:
@table @samp
diff --git a/gdb/testsuite/gdb.base/help.exp
b/gdb/testsuite/gdb.base/help.exp
index 86a02eb..095c97a 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -125,3 +125,6 @@ gdb_test "apropos \\\(print\[\^ bsiedf\\\".-\]\\\)"
"handle -- Specify how to ha
gdb_test "apropos handle signal" "handle -- Specify how to handle
signals"
# test apropos apropos
gdb_test "apropos apropos" "apropos -- Search for commands matching a
REGEXP"
+
+# Test help class commands
+gdb_test "help locations" "GDB supports several.*"
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index b885708..16ddadc 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15975,10 +15975,9 @@ command" [PROBE_MODIFIER] [LOCATION] [thread THREADNUM] [if CONDITION]\n\
PROBE_MODIFIER shall be present if the command is to be placed in a\n\
probe point. Accepted values are `-probe' (for a generic, automatically\n\
guessed probe type) or `-probe-stap' (for a SystemTap probe).\n\
-LOCATION may be a line number, function name, or \"*\" and an address.\n\
-If a line number is specified, break at start of code for that line.\n\
-If a function is specified, break at start of code for that function.\n\
-If an address is specified, break at that exact address.\n\
+LOCATION may be a linespec, explicit, or address location. See \"help\n\
+locations\" for more help with specifying locations.\n\
+\n\
With no LOCATION, uses current execution address of the selected\n\
stack frame. This is useful for breaking on return to a stack frame.\n\
\n\
@@ -16511,11 +16510,9 @@ This command may be abbreviated \"delete\"."),
&deletelist);
add_com ("clear", class_breakpoint, clear_command, _("\
-Clear breakpoint at specified line or function.\n\
-Argument may be line number, function name, or \"*\" and an address.\n\
-If line number is specified, all breakpoints in that line are cleared.\n\
-If function is specified, breakpoints at beginning of function are cleared.\n\
-If an address is specified, breakpoints at that address are cleared.\n\
+Clear breakpoint at specified location.\n\
+Argument may be a linespec, explicit, or address location. Seen\n\
+\"help locations\" for more help with specifying locations.\n\
\n\
With no argument, clears all breakpoints in the line that the selected frame\n\
is executing in.\n\
@@ -16752,12 +16749,10 @@ Do \"help tracepoints\" for info on other tracepoint commands."));
Set a static tracepoint at specified line, function or marker.\n\
\n\
strace [LOCATION] [if CONDITION]\n\
-LOCATION may be a line number, function name, \"*\" and an address,\n\
-or -m MARKER_ID.\n\
-If a line number is specified, probe the marker at start of code\n\
-for that line. If a function is specified, probe the marker at start\n\
-of code for that function. If an address is specified, probe the marker\n\
-at that exact address. If a marker id is specified, probe the marker\n\
+LOCATION may be a linespec, explicit, or address location or\n\
+or -m MARKER_ID. See \"help locations\" for more help with specifying\n\
+locations.\n\
+If a marker id is specified, probe the marker\n\
with that name. With no LOCATION, uses current execution address of\n\
the selected stack frame.\n\
Static tracepoints accept an extra collect action -- ``collect $_sdata''.\n\
@@ -16921,12 +16916,10 @@ an instruction at any address within the [START-LOCATION, END-LOCATION]\n\
range (including START-LOCATION and END-LOCATION)."));
c = add_com ("dprintf", class_breakpoint, dprintf_command, _("\
-Set a dynamic printf at specified line or function.\n\
+Set a dynamic printf at specified location.\n\
dprintf location,format string,arg1,arg2,...\n\
-location may be a line number, function name, or \"*\" and an address.\n\
-If a line number is specified, break at start of code for that line.\n\
-If a function is specified, break at start of code for that function.\n\
-"));
+location may be a linespec, explicit, or address location. See \"help\n\
+locations\" for more help with specifying locations."));
set_cmd_completer (c, location_completer);
add_setshow_enum_cmd ("dprintf-style", class_support,
@@ -16975,4 +16968,108 @@ agent-printf \"printf format string\", arg1, arg2, arg3, ..., argn\n\
automatic_hardware_breakpoints = 1;
observer_attach_about_to_proceed (breakpoint_about_to_proceed);
+
+ add_com ("locations", help_class, NULL,
+ _("GDB supports several ways to specify locations. Any place\n\
+a location is required, any of the following forms is permissible.\n\
+\n\
+ A LINESPEC is a colon-separated list of source location parameters\n\
+ such as file name, function name, etc. Acceptable forms of linespecs\n\
+ include:\n\
+\n\
+ LINENUM\n\
+ Specifies the line number LINENUM of the current source file.\n\
+\n\
+ -OFFSET\n\
+ +OFFSET\n\
+ Specifies the line OFFSET lines before or after the current line.\n\
+\n\
+ FILE:LINENUM\n\
+ Specifies the line LINENUM in the source file FILE. If FILE\n\
+ is a relative file name, then it will match any source file name\n\
+ with the same trailing components.\n\
+\n\
+ FUNCTION\n\
+ Specifies the line that begins the body of the function FUNCTION.\n\
+ For example, in C, this is the line with the open brace.\n\
+\n\
+ FUNCTION:LABEL\n\
+ Specifies the line where LABEL appears in FUNCTION.\n\
+\n\
+ FILE:FUNCTION\n\
+ Specifies the line that begins the body of the function FUNCTION\n\
+ in the file FILE. You only need the file name with a function\n\
+ name to avoid ambiguity when there are identically named functions\n\
+ in different source files.\n\
+\n\
+ LABEL\n\
+ Specifies the line at which the label named LABEL appears in the\n\
+ function corresponding to the current stack frame. If there is\n\
+ no current selected frame (for instance, if the inferior is not\n\
+ running), then GDB will not search for a label.\n\
+\n\
+ EXPLICIT LOCATIONS bypass the linespec parser, allowing the user to\n\
+ explicitly specify the source location's parameters. They are specified\n\
+ using option-value pairs listed in the table below.\n\
+\n\
+ Parsing linespecs often involves multiple searches through the program's\n\
+ symbol table or the file system. For large programs, this may be\n\
+ extremely time-consuming. Explicit locations may help avoid a lot of\n\
+ this unnecessary searching.\n\
+\n\
+ The list of valid explicit location options is summarized in the\n\
+ following table:\n\
+\n\
+ -source\n\
+ The value specifies the source file name. This option\n\
+ requires the use of either -function or -line.\n\
+\n\
+ -function\n\
+ The value specifies the name of a function. Operations\n\
+ on function locations unmodified by other options (such as\n\
+ -label or -line) affect the line that begins the body of the\n\
+ function. In C, for example, this is the line with the open brace.\n\
+\n\
+ -label\n\
+ The value specifies a line offset for that location. The offset\n\
+ may either be absolute (-line 3) or relative (-line +3), depending\n\
+ on the command. When specified without any other options, the\n\
+ line offset is relative to the current function.\n\
+\n\
+ Explicit location options may be abbreviated by omitting any non-unique\n\
+ trailing characters from the option name, e.g.,\n\
+ \"break -s main.c -li 3\".\n\
+\n\
+ ADDRESS LOCATIONS indicate a specific program address. They have the\n\
+ generalized form *ADDRESS.\n\
+\n\
+ For line-oriented commands, such as list and edit, this specifies\n\
+ a source line that contains ADDRESS. For break and other breakpoint-\n\
+ oriented commands, this can be used to set breakpoints in parts of\n\
+ your program which do not have debugging information or source files.\n\
+\n\
+ ADDRESS may be any expression valid in the current working language\n\
+ that specifies a code address. In addition, as a convenience, GDB\n\
+ extends the semantics of expressions used in locations to cover several\n\
+ situations that frequently occur during debugging. Here are the various\n\
+ forms of ADDRESS:\n\
+\n\
+ EXPRESSION\n\
+ Any expression valid in the current working language.\n\
+\n\
+ FUNCADDR\n\
+ An address of a function or procedure derived from its name. In C,\n\
+ C++, Java, Objective-C, Fortran, minimal, and assembly, this is\n\
+ simply the function's name FUNCTION (and actually a special case of\n\
+ a valid expression). In Ada, this is FUNCTION'Address (although\n\
+ the Pascal form also works).\n\
+\n\
+ This form specifies the address of the function's first instruction,\n\
+ before the stack frame and arguments have been set up.\n\
+\n\
+ 'FILE'::FUNCADDR\n\
+ Like FUNCADDR above, but also specifies the name of the source\n\
+ file explicitly. This is useful if the name of the function does\n\
+ not specify the function unambiguously, e.g., if there are several\n\
+ functions with identical names in different source files."));
}
diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
index 61a7b5a..95b55c1 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -948,7 +948,8 @@ help_cmd (char *arg, struct ui_file *stream)
fputs_filtered (c->doc, stream);
fputs_filtered ("\n", stream);
- if (c->prefixlist == 0 && c->func != NULL)
+ if ((c->prefixlist == 0 && c->func != NULL)
+ || c->class == help_class)
return;
fprintf_filtered (stream, "\n");
@@ -1161,7 +1162,8 @@ help_cmd_list (struct cmd_list_element *list, enum command_class class,
for (c = list; c; c = c->next)
{
- if (c->abbrev_flag == 0
+ if (c->class != help_class
+ && c->abbrev_flag == 0
&& (class == all_commands
|| (class == all_classes && c->func == NULL)
|| (class == c->class && c->func != NULL)))
diff --git a/gdb/command.h b/gdb/command.h
index 81edc43..777e847 100644
--- a/gdb/command.h
+++ b/gdb/command.h
@@ -33,7 +33,8 @@
enum command_class
{
/* Special args to help_list */
- class_deprecated = -3, all_classes = -2, all_commands = -1,
+ class_deprecated = -4, help_class = -3, all_classes = -2,
+ all_commands = -1,
/* Classes of commands */
no_class = -1, class_run = 0, class_vars, class_stack, class_files,
class_support, class_info, class_breakpoint, class_trace,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4ac28bb..0c2e04a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5784,9 +5784,9 @@ breakpoints on all threads, or on a particular thread.
@cindex breakpoints and threads
@cindex thread breakpoints
@kindex break @dots{} thread @var{threadno}
-@item break @var{linespec} thread @var{threadno}
-@itemx break @var{linespec} thread @var{threadno} if @dots{}
-@var{linespec} specifies source lines; there are several ways of
+@item break @var{location} thread @var{threadno}
+@itemx break @var{location} thread @var{threadno} 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.
@@ -6931,21 +6931,21 @@ 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{linespecs}. Linespecs specify source lines; there are several ways
+@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.
Here is a complete description of the possible arguments for @code{list}:
@table @code
-@item list @var{linespec}
-Print lines centered around the line specified by @var{linespec}.
+@item list @var{location}
+Print lines centered around the line specified by @var{location}.
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs. When a @code{list} command has two linespecs, and the
-source file of the second linespec is omitted, this refers to
-the same source file as the first linespec.
+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.
@item list ,@var{last}
Print lines ending with @var{last}.
@@ -6970,15 +6970,21 @@ As described in the preceding table.
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;
-for that reason, locations are also known as @dfn{linespecs}.
+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.
-Here are all the different ways of specifying a code location that
-@value{GDBN} understands:
+@node Linespec Locations
+@subsection Linespec Locations
+
+A @dfn{linespec} is a colon-separated list of source location parameters such
+as file name, function name, etc. They are parsed and converted into an
+internal representation used by @value{GDBN}. Here are all the
+different ways of specifying a linespec:
@table @code
@item @var{linenum}
-Specifies the line number @var{linenum} of the current source file.
+Specifies the line number @var{linenum} of the @dfn{current source} file.
@item -@var{offset}
@itemx +@var{offset}
@@ -7013,25 +7019,90 @@ function name to avoid ambiguity when there are identically named
functions in different source files.
@item @var{label}
-Specifies the line at which the label named @var{label} appears.
-@value{GDBN} searches for the label in the function corresponding to
-the currently selected stack frame. If there is no current selected
-stack frame (for instance, if the inferior is not running), then
-@value{GDBN} will not search for a label.
-
-@item *@var{address}
-Specifies the program address @var{address}. For line-oriented
-commands, such as @code{list} and @code{edit}, this specifies a source
-line that contains @var{address}. For @code{break} and other
-breakpoint oriented commands, this can be used to set breakpoints in
+Specifies the line at which the label named @var{label} appears
+in the function corresponding to the currently selected stack frame.
+If there is no current selected stack frame (for instance, if the inferior
+is not running), then @value{GDBN} will not search for a label.
+
+@cindex breakpoint at static probe point
+@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes. @xref{Static Probe Points}, for more
+information on finding and using static probes. This form of linespec
+specifies the location of such a static probe.
+
+If @var{objfile} is given, only probes coming from that shared library
+or executable matching @var{objfile} as a regular expression are considered.
+If @var{provider} is given, then only probes from that provider are considered.
+If several probes match the spec, @value{GDBN} will insert a breakpoint at
+each one of those probes.
+@end table
+
+@node Explicit Locations
+@subsection Explicit Locations
+@cindex explicit locations
+
+@dfn{Explict locations} bypass the linespec parser, allowing the user
+to explicitly specify the source location's parameters. They are specified
+using option-value pairs listed in the table below.
+
+Parsing linespecs often involves multiple searches through the program's
+symbol table or the file system. For large programs, this may be extremely
+time-consuming. Explicit locations may help avoid a lot of this
+unnecessary searching.
+
+For example, the linespec ``foo:bar'' may refer to a function ``bar''
+defined in the file named ``foo'' or the label ``bar'' in a function
+named ``foo''. @value{GDBN} must search either the file system or
+the symbol table to know.
+
+The list of valid explicit location options is summarized in the
+following table:
+
+@table @code
+@item -source
+The value specifies the source file name. This option
+requires the use of either @code{-function} or @code{-line}.
+
+@item -function
+The value specifies the name of a function. Operations
+on function locations unmodified by other options (such as @code{-label}
+or @code{-line}) affect the line that begins the body of the function.
+In C, for example, this is the line with the open brace.
+
+@item -label
+The value specifies the name of a label. When the function
+name is not specified, the label is searched in the function of the currently
+selected stack frame.
+
+@item -line
+The value specifies a line offset for the location. The offset may either
+be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on
+the command. When specified without any other options, the line offset is
+relative to the current function.
+@end table
+
+Explicit location options may be abbreviated by omitting any non-unique
+trailing characters from the option name, e.g., @code{break -s main.c -li 3}.
+
+@node Address Locations
+@subsection Address Locations
+@cindex address locations
+
+@dfn{Address locations} indicate a specific program address. They have
+the generalized form *@var{address}.
+
+For line-oriented commands, such as @code{list} and @code{edit}, this
+specifies a source line that contains @var{address}. For @code{break} and
+other breakpoint-oriented commands, this can be used to set breakpoints in
parts of your program which do not have debugging information or
source files.
-Here @var{address} may be any expression valid in the current working
+@var{address} may be any expression valid in the current working
language (@pxref{Languages, working language}) that specifies a code
address. In addition, as a convenience, @value{GDBN} extends the
-semantics of expressions used in locations to cover the situations
-that frequently happen during debugging. Here are the various forms
+semantics of expressions used in locations to cover several situations
+that frequently occur during debugging. Here are the various forms
of @var{address}:
@table @code
@@ -7056,22 +7127,6 @@ specify the function unambiguously, e.g., if there are several
functions with identical names in different source files.
@end table
-@cindex breakpoint at static probe point
-@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
-The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
-applications to embed static probes. @xref{Static Probe Points}, for more
-information on finding and using static probes. This form of linespec
-specifies the location of such a static probe.
-
-If @var{objfile} is given, only probes coming from that shared library
-or executable matching @var{objfile} as a regular expression are considered.
-If @var{provider} is given, then only probes from that provider are considered.
-If several probes match the spec, @value{GDBN} will insert a breakpoint at
-each one of those probes.
-
-@end table
-
-
@node Edit
@section Editing Source Files
@cindex editing source files
@@ -7389,9 +7444,9 @@ well as hex.
@table @code
@kindex info line
-@item info line @var{linespec}
+@item info line @var{location}
Print the starting and ending addresses of the compiled code for
-source line @var{linespec}. You can specify source lines in any of
+source line @var{location}. You can specify source lines in any of
the ways documented in @ref{Specify Location}.
@end table
@@ -7409,7 +7464,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
@noindent
@cindex code address and its source line
We can also inquire (using @code{*@var{addr}} as the form for
-@var{linespec}) what source line covers a particular address:
+@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
@@ -7519,7 +7574,7 @@ Dump of assembler code from 0x400281 to 0x40028b:
End of assembler dump.
@end smallexample
-Addresses cannot be specified as a linespec (@pxref{Specify Location}).
+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}.
@@ -10848,9 +10903,9 @@ 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{linespec}
+@item info macros @var{location}
Show all macro definitions that are in effect at the location specified
-by @var{linespec}, and describe the source location or compiler
+by @var{location}, and describe the source location or compiler
command-line where those definitions were established.
@kindex macro define
@@ -14973,14 +15028,14 @@ from the current task to the given task.
#4 0x804aacc in un () at un.adb:5
@end smallexample
-@item break @var{linespec} task @var{taskno}
-@itemx break @var{linespec} task @var{taskno} if @dots{}
+@item break @var{location} task @var{taskno}
+@itemx break @var{location} 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}).
-@var{linespec} specifies source lines, as described
+@var{location} specifies source lines, as described
in @ref{Specify Location}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
@@ -15806,20 +15861,17 @@ an address of your own choosing, with the following commands:
@table @code
@kindex jump
@kindex j @r{(@code{jump})}
-@item jump @var{linespec}
-@itemx j @var{linespec}
-@itemx jump @var{location}
+@item jump @var{location}
@itemx j @var{location}
-Resume execution at line @var{linespec} or at address given by
-@var{location}. Execution stops again immediately if there is a
-breakpoint there. @xref{Specify Location}, for a description of the
-different forms of @var{linespec} and @var{location}. It is common
+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}.
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 line @var{linespec} is in
+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
@@ -28784,22 +28836,42 @@ N.A.
@smallexample
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
- [ -p @var{thread-id} ] [ @var{location} ]
+ [ -p @var{thread-id} ] @var{location}
+
@end smallexample
@noindent
If specified, @var{location}, can be one of:
-@itemize @bullet
-@item function
-@c @item +offset
-@c @item -offset
-@c @item linenum
-@item filename:linenum
-@item filename:function
-@item *address
-@end itemize
+@table @var
+@item linespec location
+A linespec location. @xref{Linespec Locations}.
+
+@item explicit location
+An explicit location. @sc{gdb/mi} explicit locations are
+analogous to @value{GDBN}'s explicit locations using the option names
+listed below. @xref{Explicit Locations}.
+
+@table @samp
+@item -s @var{filename}
+The source file name of the location. This option requires the use
+of either @samp{-m} or @samp{-o}.
+@item -m @var{function}
+The name of a function or method.
+
+@item -l @var{label}
+The name of a label.
+
+@item -o @var{lineoffset}
+An absolute or relative offset from the start of the location.
+@end table
+
+@item address location
+An address location, *@var{address}. @xref{Address Locations}.
+@end table
+
+@noindent
The possible optional parameters of this command are:
@table @samp
diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index 86a02eb..095c97a 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -125,3 +125,6 @@ gdb_test "apropos \\\(print\[\^ bsiedf\\\".-\]\\\)" "handle -- Specify how to ha
gdb_test "apropos handle signal" "handle -- Specify how to handle signals"
# test apropos apropos
gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP"
+
+# Test help class commands
+gdb_test "help locations" "GDB supports several.*"