* [RFA 4/4 doc] Explicit locations
@ 2013-03-21 23:59 Keith Seitz
2013-03-22 1:00 ` Keith Seitz
0 siblings, 1 reply; 6+ messages in thread
From: Keith Seitz @ 2013-03-21 23:59 UTC (permalink / raw)
To: gdb-patches@sourceware.org ml
[-- Attachment #1: Type: text/plain, Size: 27354 bytes --]
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.*"
[-- Attachment #2: cvs-explicit-doc.patch --]
[-- Type: text/x-patch, Size: 24683 bytes --]
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.*"
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [RFA 4/4 doc] Explicit locations
2013-03-21 23:59 [RFA 4/4 doc] Explicit locations Keith Seitz
@ 2013-03-22 1:00 ` Keith Seitz
2013-03-22 9:46 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Keith Seitz @ 2013-03-22 1:00 UTC (permalink / raw)
To: gdb-patches@sourceware.org ml
On 03/21/2013 04:58 PM, Keith Seitz wrote:
> Anyway, let the fun begin.
Whoops. My apologies -- I didn't actually mean to send that out as an
attachment!
Keith
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.*"
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [RFA 4/4 doc] Explicit locations
2013-03-22 1:00 ` Keith Seitz
@ 2013-03-22 9:46 ` Eli Zaretskii
2013-06-20 0:11 ` Keith Seitz
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2013-03-22 9:46 UTC (permalink / raw)
To: Keith Seitz; +Cc: gdb-patches
> Date: Thu, 21 Mar 2013 17:06:39 -0700
> From: Keith Seitz <keiths@redhat.com>
>
> --- 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\
Why is it a good idea to remove the information about linespec and
address methods of specifying locations? I would suggest to leave
them alone, perhaps add a one-line summary for the new 'explicit'
method, and leave the details to the new "help locations" doc string.
You see, I think one of the nastiest annoyances in documentation is
excessive reliance on cross-references. This is BA-A-A-D because it
requires the reader to fish elsewhere for info necessary for what she
wants to do, instead of giving that info right there and then. It is
okay to use cross-references for _more_details_ on a subject, but the
bare necessities should not IMO be deferred to some other node in the
docs.
> 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\
Same comment here.
> 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\
And here.
> 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."));
And here.
> + add_com ("locations", help_class, NULL,
> + _("GDB supports several ways to specify locations. Any place\n\
The first line of a doc string should be a single full sentence,
suitable to serve as a summary of the feature. That line is shown by
commands like "apropos", so it should be legible by itself. I suggest
Different forms of specifying locations supported by GDB.
> + EXPLICIT LOCATIONS bypass the linespec parser, allowing the user to\n\
Why do we need to talk about the "linespec parser" in user
documentation? For that matter, how is it useful for the user to know
that EXPLICIT bypasses something? It's just an alternative method of
specifying a location, so it should be described as such, in the same
format you used for the other 2.
> + 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\
I suggest to make this user-oriented, something like
Explicit locations are useful when several functions, labels, or
file names have the same name (base name for files) in the program's
sources. In these cases, explicit locations point to the source
line you meant more accurately and unequivocally. Also, using
explicit locations might be faster in large programs. On the other
hand, using explicit locations means more typing.
On second thought, this whole merits/demerits thing probably belongs
to the manual, not to a doc string.
> 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,
These parts don't belong to documentation.
> @@ -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
Did you actually try to build the manual after these changes? I think
it won't build, because you introduced new nodes that don't appear in
any menu in their parent node, which makes them "orphans", and
makeinfo will barf.
Anyway, I don't think we want additional sub-nodes here. The "Specify
Location" node is not large; adding the new explicit locations to it
will still not make it much longer. Just add the new stuff there.
> +
> +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}.
I would omit the last sentence, it does not add any useful information
for GDB users.
> @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.
I don't necessarily object, but I see no special reason to put
"current source" in @dfn, as it is not some terminology that needs
explanation, nor is it actually explained in the text. (By contrast,
"current line" does need an explanation, which is given in the text.)
> +@dfn{Explict locations} bypass the linespec parser, allowing the user
> +to explicitly specify the source location's parameters.
As mentioned earlier, the issue of parsing and bypassing it does not
add any useful information here, so I'd omit it.
> +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.
I would reword this, similar to what I suggested above for the doc
string.
> +@table @code
> +@item -source
> +The value specifies the source file name. This option
> +requires the use of either @code{-function} or @code{-line}.
I think this should explain how to specify a file name unambiguously
(after all, this is what explicit locations are all about, right?).
For example, what if only a basename is specified? how to specify the
file name when several different files in the source tree have the
same basename?
> +@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.
^^^^^^
"Affect" or "specify" or "refer"? If the former, what does "affect"
mean?
> +@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.
The last sentence seems to describe an unexpected (for me) behavior:
usually, I'd expect "line +3" to specify an offset from the current
_line_, not current function.
> -Here @var{address} may be any expression valid in the current working
> +@var{address} may be any expression valid in the current working
That "Here" was there for a reason: "address" starts with a lower-case
letter, which is inappropriate in the first word of a sentence. (In
the Info manual, @var causes its argument be up-cased, but in the
printed manual @var switches to a slant typeface and does not up-case,
so the sentence will look incorrect.)
> +@item explicit location
> +An explicit location. @sc{gdb/mi} explicit locations are
> +analogous to @value{GDBN}'s explicit locations using the option names
I don't think we want to contrast GDB with GDB/MI, as the latter is
part of the former. I think you need to use CLI instead of
@value{GDBN} here.
> +listed below. @xref{Explicit Locations}.
^^
Two spaces here, please.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [RFA 4/4 doc] Explicit locations
2013-03-22 9:46 ` Eli Zaretskii
@ 2013-06-20 0:11 ` Keith Seitz
2013-06-21 9:53 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Keith Seitz @ 2013-06-20 0:11 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
[-- Attachment #1: Type: text/plain, Size: 33292 bytes --]
On 03/22/2013 02:43 AM, Eli Zaretskii wrote:
>> Date: Thu, 21 Mar 2013 17:06:39 -0700
>> From: Keith Seitz <keiths@redhat.com>
>>
>> --- 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\
>
> Why is it a good idea to remove the information about linespec and
> address methods of specifying locations? I would suggest to leave
> them alone, perhaps add a one-line summary for the new 'explicit'
> method, and leave the details to the new "help locations" doc string.
I removed that because it is actually misinformation. The break command
takes much more than just the three forms listed. [It currently accepts
twelve different forms of linespecs (and more are planned).]
The big problem I kept having is that any rewording I came up with which
maintained useful examples was getting far too verbose and introduced a
page break to some commands. So I opted to move these examples and
details to a separate help topic.
Currently, I've consolidated all the location help strings for all the
commands (BREAK_ARGS_HELP macro and dprintf, trace, strace, and clear
commands) into a new location help macro. These commands now use this macro.
While I may think it unfortunately verbose, I think the compromise
between usefulness -- users probably may never have to use "help
locations" -- and accuracy is better than what we have today.
Given this approach, it is no longer necessary (or probably even
desirable) to introduce "help locations", so I've removed all that, too.
> You see, I think one of the nastiest annoyances in documentation is
> excessive reliance on cross-references. This is BA-A-A-D because it
> requires the reader to fish elsewhere for info necessary for what she
> wants to do, instead of giving that info right there and then. It is
> okay to use cross-references for _more_details_ on a subject, but the
> bare necessities should not IMO be deferred to some other node in the
> docs.
I had actual reasons for doing it this way, but it is irrelevant in this
revision which has removed the cross reference entirely.
[snip commentary about (now withdrawn) "help locations"]
>> @@ -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
>
> Did you actually try to build the manual after these changes? I think
> it won't build, because you introduced new nodes that don't appear in
> any menu in their parent node, which makes them "orphans", and
> makeinfo will barf.
Yes, I did build the manual, but not the info files. I apologize. [I
never use info files. I don't like info.] I will double-check all my doc
patches from now on with info.
> Anyway, I don't think we want additional sub-nodes here. The "Specify
> Location" node is not large; adding the new explicit locations to it
> will still not make it much longer. Just add the new stuff there.
Done. I think what I really wanted was an @anchor to these portions so
that they could be referenced in the MI section of the manual.
>> +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}.
>
> I would omit the last sentence, it does not add any useful information
> for GDB users.
Done.
>> @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.
>
> I don't necessarily object, but I see no special reason to put
> "current source" in @dfn, as it is not some terminology that needs
> explanation, nor is it actually explained in the text. (By contrast,
> "current line" does need an explanation, which is given in the text.)
Understood, and I agree. In the vast majority of cases where "current
source" appears in the manual, it is not used this way. Fixed.
>> +@dfn{Explict locations} bypass the linespec parser, allowing the user
>> +to explicitly specify the source location's parameters.
>
> As mentioned earlier, the issue of parsing and bypassing it does not
> add any useful information here, so I'd omit it.
Fixed.
>> +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.
>
> I would reword this, similar to what I suggested above for the doc
> string.
Fixed.
>> +@table @code
>> +@item -source
>> +The value specifies the source file name. This option
>> +requires the use of either @code{-function} or @code{-line}.
>
> I think this should explain how to specify a file name unambiguously
> (after all, this is what explicit locations are all about, right?).
> For example, what if only a basename is specified? how to specify the
> file name when several different files in the source tree have the
> same basename?
I've made an attempt at this. It probably needs a little more work,
though, and the eyes of an outsider.
>> +@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.
> ^^^^^^
> "Affect" or "specify" or "refer"? If the former, what does "affect"
> mean?
I see what you mean. I've adopted "refer."
>> +@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.
>
> The last sentence seems to describe an unexpected (for me) behavior:
> usually, I'd expect "line +3" to specify an offset from the current
> _line_, not current function.
Doh! Yes, you are correct. I wrote that wrong. Fixed.
>> -Here @var{address} may be any expression valid in the current working
>> +@var{address} may be any expression valid in the current working
>
> That "Here" was there for a reason: "address" starts with a lower-case
> letter, which is inappropriate in the first word of a sentence. (In
> the Info manual, @var causes its argument be up-cased, but in the
> printed manual @var switches to a slant typeface and does not up-case,
> so the sentence will look incorrect.)
Fixed.
>> +@item explicit location
>> +An explicit location. @sc{gdb/mi} explicit locations are
>> +analogous to @value{GDBN}'s explicit locations using the option names
>
> I don't think we want to contrast GDB with GDB/MI, as the latter is
> part of the former. I think you need to use CLI instead of
> @value{GDBN} here.
Excellent point. Fixed.
>> +listed below. @xref{Explicit Locations}.
> ^^
> Two spaces here, please.
Well, not to make light of this, but I am glad I only missed that in one
place! :-)
Since the first incarnation of this patch, I've had to edit some new
places in the manual to cover new commands (like dprintf) that have been
recently introduced (and also work with explicit locations). I believe I
also mistakenly left out updates to the tracepoints section as well.
Keith
ChangeLog
2013-06-19 Keith Seitz <keiths@redhat.com>
* NEWS: Mention explicit locations.
* breakpoint.c [LOCATION_HELP_STRING]: New macro.
[BREAK_ARGS_HELP]: Use LOCATION_HELP_STRING.
(_initialize_breakpoint): Update documentation for
"clear", "break", "trace", "strace", "ftrace", and "dprintf".
doc/ChangeLog
2013-06-19 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. Add explanations for each
location type.
(Source and Machine Code): Use "location(s)" instead of
"linespec(s)".
(C Preprocessor Macros): Likewise.
(Create and Delete Tracepoints): 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 anchor.
Add reference to appropriate manual section discussing locations.
(The -dprintf-insert Command): Refer to -break-insert for
specification of `location'.
testsuite/ChangeLog
2013-06-19 Keith Seitz <keiths@redhat.com>
* gdb.base/help.exp: Update help_breakpoint_text.
diff --git a/gdb/NEWS b/gdb/NEWS
index eea9917..4d8ebdd 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -177,6 +177,10 @@ Tilera TILE-Gx GNU/Linux tilegx*-*-linux
* 'info proc' now works on some core files.
+* GDB now allows users to specify explicit locations, bypassing
+ the linespec parser. This feature is also available to GDB/MI
+ clients.
+
* Python scripting
** Vectors can be created with gdb.Type.vector.
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index 090f6cc..1ac054a 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15844,19 +15844,37 @@ all_tracepoints (void)
}
\f
+/* This help string is used to consolidate all the help string for
specifying
+ locations used by several commands. */
+#define LOCATION_HELP_STRING \
+"Linespecs are a colon-separated list of location parameters, such as\n\
+source filename, function name, label name, and line number.\n\
+Example: To specify the start of a label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use\n\
+\"factorial.c:fact:the_top\".\n\
+\n\
+Address locations begin with \"*\" and specify an exact address in the.\n\
+program. Example: To specify the fourth byte past the start function\n\
+\"main\",use \"*main + 4\".\n\
+\n\
+Explicit locations are similar to linespecs but use an option/argument\n\
+syntax to specify location parameters.\n\
+Example: To specify the start of the label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use \"-source factorial.c\n\
+-function fact -label the_top\".\n"
+
/* This help string is used for the break, hbreak, tbreak and thbreak
commands. It is defined as a macro to prevent duplication.
COMMAND should be a string constant containing the name of the
command. */
+
#define BREAK_ARGS_HELP(command) \
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, address, or explicit location.\n\
+\n" LOCATION_HELP_STRING "\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\
@@ -16382,12 +16400,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\
-\n\
+Clear breakpoint at specified location.\n\
+Argument may be a linespec, explicit, or address location.\n\
+\n" LOCATION_HELP_STRING "\n\
With no argument, clears all breakpoints in the line that the selected
frame\n\
is executing in.\n\
\n\
@@ -16395,7 +16410,7 @@ See also the \"delete\" command which clears
breakpoints by number."));
add_com_alias ("cl", "clear", class_breakpoint, 1);
c = add_com ("break", class_breakpoint, break_command, _("\
-Set breakpoint at specified line or function.\n"
+Set breakpoint at specified location.\n"
BREAK_ARGS_HELP ("break")));
set_cmd_completer (c, location_completer);
@@ -16588,7 +16603,7 @@ hardware.)"),
/* Tracepoint manipulation commands. */
c = add_com ("trace", class_breakpoint, trace_command, _("\
-Set a tracepoint at specified line or function.\n\
+Set a tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("trace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
@@ -16600,24 +16615,20 @@ Do \"help tracepoints\" for info on other
tracepoint commands."));
add_com_alias ("trac", "trace", class_alias, 1);
c = add_com ("ftrace", class_breakpoint, ftrace_command, _("\
-Set a fast tracepoint at specified line or function.\n\
+Set a fast tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("ftrace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
set_cmd_completer (c, location_completer);
c = add_com ("strace", class_breakpoint, strace_command, _("\
-Set a static tracepoint at specified line, function or marker.\n\
+Set a static tracepoint at location 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\
-with that name. With no LOCATION, uses current execution address of\n\
-the selected stack frame.\n\
+LOCATION may be a linespec, explicit, or address location or -m
MARKER_ID.\n"
+"\n" LOCATION_HELP_STRING "\n\
+If a marker id is specified, probe the marker with that name. With\n\
+no LOCATION, uses current execution address of the selected stack frame.\n\
Static tracepoints accept an extra collect action -- ``collect
$_sdata''.\n\
This collects arbitrary user data passed in the probe point call to the\n\
tracing library. You can inspect it when analyzing the trace buffer,\n\
@@ -16779,12 +16790,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.\n"
+"\n" LOCATION_HELP_STRING));
set_cmd_completer (c, location_completer);
add_setshow_enum_cmd ("dprintf-style", class_support,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e6ec4ff..304dee7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5838,9 +5838,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.
@@ -7166,21 +7166,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}.
@@ -7205,11 +7205,16 @@ 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:
+@subsection Linespec Locations
+@anchor{Linespec Locations}
+
+A @dfn{linespec} is a colon-separated list of source location
parameters such
+as file name, function name, etc. Here are all the different ways of
+specifying a linespec:
@table @code
@item @var{linenum}
@@ -7248,25 +7253,93 @@ 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
+
+@subsection Explicit Locations
+@cindex explicit locations
+@anchor{Explicit Locations}
+
+@dfn{Explict locations} allow the user to directly specify the source
+location's parameters using option-value pairs.
+
+Explicit locations are useful when several functions, labels, or
+file names have the same name (base name for files) in the program's
+sources. In these cases, explicit locations point to the source
+line you meant more accurately and unequivocally. Also, using
+explicit locations might be faster in large programs.
+
+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. To differentiate between
+files with the same base name, prepend as many directories as is necessary
+to uniquely identify the desired file, e.g., ``foo/bar/baz.c''. Otherwise
+@value{GDBN} will use the first file it finds with the given base
+name. This option requires the use of either @code{-function} or
@code{-line}.
+
+@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}) refer to 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 line.
+@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}.
+
+@subsection Address Locations
+@cindex address locations
+@anchor{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
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
@@ -7291,22 +7364,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
@@ -7624,9 +7681,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
@@ -7644,7 +7701,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.
@@ -7754,7 +7811,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}.
@@ -11093,9 +11150,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
@@ -11400,12 +11457,11 @@ conditions and actions.
@kindex trace
@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be a source line, a function name, or
-an address in the target program. @xref{Specify Location}. 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
+Its argument @var{location} can be any valid location.
+@xref{Specify Location}. 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
supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
in tracing}).
If remote stub doesn't support the @samp{InstallInTrace} feature, all
@@ -15240,14 +15296,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
@@ -16075,20 +16131,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
@@ -29723,28 +29776,49 @@ N.A.
@subheading The @code{-break-insert} Command
@findex -break-insert
+@anchor{-break-insert}
@subsubheading Synopsis
@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 the CLI'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
@@ -29836,17 +29910,8 @@ times="0"@}]@}
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
-
-@itemize @bullet
-@item @var{function}
-@c @item +offset
-@c @item -offset
-@c @item @var{linenum}
-@item @var{filename}:@var{linenum}
-@item @var{filename}:function
-@item *@var{address}
-@end itemize
+If supplied, @var{location} may be specified the same way as for
+the @code{-break-insert} command. @xref{-break-insert}.
The possible optional parameters of this command are:
diff --git a/gdb/testsuite/gdb.base/help.exp
b/gdb/testsuite/gdb.base/help.exp
index 86a02eb..2a9537e 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -58,7 +58,7 @@ test_class_help "user-defined" {
}
# Test help of an abbreviated command. "break" is picked at random.
-set help_breakpoint_text "Set breakpoint at specified line or function\..*"
+set help_breakpoint_text "Set breakpoint at specified location\..*"
# test help breakpoint "b" abbreviation
gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\"
abbreviation"
# test help breakpoint "br" abbreviation
[-- Attachment #2: explicit-doc.patch --]
[-- Type: text/x-patch, Size: 23036 bytes --]
diff --git a/gdb/NEWS b/gdb/NEWS
index eea9917..4d8ebdd 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -177,6 +177,10 @@ Tilera TILE-Gx GNU/Linux tilegx*-*-linux
* 'info proc' now works on some core files.
+* GDB now allows users to specify explicit locations, bypassing
+ the linespec parser. This feature is also available to GDB/MI
+ clients.
+
* Python scripting
** Vectors can be created with gdb.Type.vector.
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index 090f6cc..1ac054a 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15844,19 +15844,37 @@ all_tracepoints (void)
}
\f
+/* This help string is used to consolidate all the help string for specifying
+ locations used by several commands. */
+#define LOCATION_HELP_STRING \
+"Linespecs are a colon-separated list of location parameters, such as\n\
+source filename, function name, label name, and line number.\n\
+Example: To specify the start of a label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use\n\
+\"factorial.c:fact:the_top\".\n\
+\n\
+Address locations begin with \"*\" and specify an exact address in the.\n\
+program. Example: To specify the fourth byte past the start function\n\
+\"main\",use \"*main + 4\".\n\
+\n\
+Explicit locations are similar to linespecs but use an option/argument\n\
+syntax to specify location parameters.\n\
+Example: To specify the start of the label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use \"-source factorial.c\n\
+-function fact -label the_top\".\n"
+
/* This help string is used for the break, hbreak, tbreak and thbreak
commands. It is defined as a macro to prevent duplication.
COMMAND should be a string constant containing the name of the
command. */
+
#define BREAK_ARGS_HELP(command) \
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, address, or explicit location.\n\
+\n" LOCATION_HELP_STRING "\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\
@@ -16382,12 +16400,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\
-\n\
+Clear breakpoint at specified location.\n\
+Argument may be a linespec, explicit, or address location.\n\
+\n" LOCATION_HELP_STRING "\n\
With no argument, clears all breakpoints in the line that the selected frame\n\
is executing in.\n\
\n\
@@ -16395,7 +16410,7 @@ See also the \"delete\" command which clears breakpoints by number."));
add_com_alias ("cl", "clear", class_breakpoint, 1);
c = add_com ("break", class_breakpoint, break_command, _("\
-Set breakpoint at specified line or function.\n"
+Set breakpoint at specified location.\n"
BREAK_ARGS_HELP ("break")));
set_cmd_completer (c, location_completer);
@@ -16588,7 +16603,7 @@ hardware.)"),
/* Tracepoint manipulation commands. */
c = add_com ("trace", class_breakpoint, trace_command, _("\
-Set a tracepoint at specified line or function.\n\
+Set a tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("trace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
@@ -16600,24 +16615,20 @@ Do \"help tracepoints\" for info on other tracepoint commands."));
add_com_alias ("trac", "trace", class_alias, 1);
c = add_com ("ftrace", class_breakpoint, ftrace_command, _("\
-Set a fast tracepoint at specified line or function.\n\
+Set a fast tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("ftrace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
set_cmd_completer (c, location_completer);
c = add_com ("strace", class_breakpoint, strace_command, _("\
-Set a static tracepoint at specified line, function or marker.\n\
+Set a static tracepoint at location 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\
-with that name. With no LOCATION, uses current execution address of\n\
-the selected stack frame.\n\
+LOCATION may be a linespec, explicit, or address location or -m MARKER_ID.\n"
+"\n" LOCATION_HELP_STRING "\n\
+If a marker id is specified, probe the marker with that name. With\n\
+no LOCATION, uses current execution address of the selected stack frame.\n\
Static tracepoints accept an extra collect action -- ``collect $_sdata''.\n\
This collects arbitrary user data passed in the probe point call to the\n\
tracing library. You can inspect it when analyzing the trace buffer,\n\
@@ -16779,12 +16790,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.\n"
+"\n" LOCATION_HELP_STRING));
set_cmd_completer (c, location_completer);
add_setshow_enum_cmd ("dprintf-style", class_support,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e6ec4ff..304dee7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5838,9 +5838,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.
@@ -7166,21 +7166,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}.
@@ -7205,11 +7205,16 @@ 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:
+@subsection Linespec Locations
+@anchor{Linespec Locations}
+
+A @dfn{linespec} is a colon-separated list of source location parameters such
+as file name, function name, etc. Here are all the different ways of
+specifying a linespec:
@table @code
@item @var{linenum}
@@ -7248,25 +7253,93 @@ 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
+
+@subsection Explicit Locations
+@cindex explicit locations
+@anchor{Explicit Locations}
+
+@dfn{Explict locations} allow the user to directly specify the source
+location's parameters using option-value pairs.
+
+Explicit locations are useful when several functions, labels, or
+file names have the same name (base name for files) in the program's
+sources. In these cases, explicit locations point to the source
+line you meant more accurately and unequivocally. Also, using
+explicit locations might be faster in large programs.
+
+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. To differentiate between
+files with the same base name, prepend as many directories as is necessary
+to uniquely identify the desired file, e.g., ``foo/bar/baz.c''. Otherwise
+@value{GDBN} will use the first file it finds with the given base
+name. This option requires the use of either @code{-function} or @code{-line}.
+
+@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}) refer to 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 line.
+@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}.
+
+@subsection Address Locations
+@cindex address locations
+@anchor{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
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
@@ -7291,22 +7364,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
@@ -7624,9 +7681,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
@@ -7644,7 +7701,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.
@@ -7754,7 +7811,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}.
@@ -11093,9 +11150,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
@@ -11400,12 +11457,11 @@ conditions and actions.
@kindex trace
@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be a source line, a function name, or
-an address in the target program. @xref{Specify Location}. 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
+Its argument @var{location} can be any valid location.
+@xref{Specify Location}. 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
supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
in tracing}).
If remote stub doesn't support the @samp{InstallInTrace} feature, all
@@ -15240,14 +15296,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
@@ -16075,20 +16131,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
@@ -29723,28 +29776,49 @@ N.A.
@subheading The @code{-break-insert} Command
@findex -break-insert
+@anchor{-break-insert}
@subsubheading Synopsis
@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 the CLI'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
@@ -29836,17 +29910,8 @@ times="0"@}]@}
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
-
-@itemize @bullet
-@item @var{function}
-@c @item +offset
-@c @item -offset
-@c @item @var{linenum}
-@item @var{filename}:@var{linenum}
-@item @var{filename}:function
-@item *@var{address}
-@end itemize
+If supplied, @var{location} may be specified the same way as for
+the @code{-break-insert} command. @xref{-break-insert}.
The possible optional parameters of this command are:
diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index 86a02eb..2a9537e 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -58,7 +58,7 @@ test_class_help "user-defined" {
}
# Test help of an abbreviated command. "break" is picked at random.
-set help_breakpoint_text "Set breakpoint at specified line or function\..*"
+set help_breakpoint_text "Set breakpoint at specified location\..*"
# test help breakpoint "b" abbreviation
gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\" abbreviation"
# test help breakpoint "br" abbreviation
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [RFA 4/4 doc] Explicit locations
2013-06-20 0:11 ` Keith Seitz
@ 2013-06-21 9:53 ` Eli Zaretskii
2013-06-21 23:32 ` Keith Seitz
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2013-06-21 9:53 UTC (permalink / raw)
To: Keith Seitz; +Cc: gdb-patches
> Date: Wed, 19 Jun 2013 15:45:47 -0700
> From: Keith Seitz <keiths@redhat.com>
> CC: gdb-patches@sourceware.org
>
> >> +@table @code
> >> +@item -source
> >> +The value specifies the source file name. This option
> >> +requires the use of either @code{-function} or @code{-line}.
> >
> > I think this should explain how to specify a file name unambiguously
> > (after all, this is what explicit locations are all about, right?).
> > For example, what if only a basename is specified? how to specify the
> > file name when several different files in the source tree have the
> > same basename?
>
> I've made an attempt at this. It probably needs a little more work,
> though, and the eyes of an outsider.
It looks fine to me.
> +#define LOCATION_HELP_STRING \
> +"Linespecs are a colon-separated list of location parameters, such as\n\
"Linespecs are colon-separated lists", in plural.
> +Address locations begin with \"*\" and specify an exact address in the.\n\
^
That period should be removed.
> +program. Example: To specify the fourth byte past the start function\n\
> +\"main\",use \"*main + 4\".\n\
^
Space before the comma here.
> -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, address, or explicit location.\n\
> +\n" LOCATION_HELP_STRING "\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\
I would move the "With no LOCATION ..." part before
LOCATION_HELP_STRING, since the latter is long. You can add
"as described below" to the preceding sentence, to make the reference
more explicit.
> +Clear breakpoint at specified location.\n\
> +Argument may be a linespec, explicit, or address location.\n\
> +\n" LOCATION_HELP_STRING "\n\
> With no argument, clears all breakpoints in the line that the selected
> frame\n\
> is executing in.\n\
> \n\
Likewise here (and elsewhere).
> +Locations may be specified using three different formats,
> +linespec locations, explicit locations, or address locations.
I would put a colon after "Different formats", not a comma.
> +sources. In these cases, explicit locations point to the source
> +line you meant more accurately and unequivocally. Also, using
^^^^^^^^^^^^^
I would use "unambiguously" here.
> +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 markup here is incorrect. Drop the quotes, and use @file for file
names, @code for functions and labels, and @samp for everything else,
like @samp{foo:bar}.
> +@table @code
> +@item -source
> +The value specifies the source file name. To differentiate between
I would use a more explicit
@item -source @var{filename}
(and similarly for other options), like you did in the MI sections.
Otherwise, the only place where you hint on the format is the sentence
about "option-value pairs", and without an example this is not enough.
Btw, adding an example would be great.
> +to uniquely identify the desired file, e.g., ``foo/bar/baz.c''. Otherwise
^^^^^^^^^^^^^^^^^
Drop the quotes and use @file markup for file names.
> @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}
Is LOCATION no longer an optional parameter for -break-insert?
OK with those changes.
Thanks!
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [RFA 4/4 doc] Explicit locations
2013-06-21 9:53 ` Eli Zaretskii
@ 2013-06-21 23:32 ` Keith Seitz
0 siblings, 0 replies; 6+ messages in thread
From: Keith Seitz @ 2013-06-21 23:32 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
[-- Attachment #1: Type: text/plain, Size: 28278 bytes --]
On 06/21/2013 01:24 AM, Eli Zaretskii wrote:
>> I've made an attempt at this. It probably needs a little more work,
>> though, and the eyes of an outsider.
>
> It looks fine to me.
Thank you.
>> +#define LOCATION_HELP_STRING \
>> +"Linespecs are a colon-separated list of location parameters, such as\n\
>
> "Linespecs are colon-separated lists", in plural.
Done. [Grr. *How* on earth did I do that?]
>> +Address locations begin with \"*\" and specify an exact address in the.\n\
> ^
> That period should be removed.
Fixed.
>> +program. Example: To specify the fourth byte past the start function\n\
>> +\"main\",use \"*main + 4\".\n\
> ^
> Space before the comma here.
Fixed.
>> -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, address, or explicit location.\n\
>> +\n" LOCATION_HELP_STRING "\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\
>
> I would move the "With no LOCATION ..." part before
> LOCATION_HELP_STRING, since the latter is long. You can add
> "as described below" to the preceding sentence, to make the reference
> more explicit.
That's a good idea. In fact, I also thought it best to leave this
verbosity until after the other parameters are explained, too. All
instances changed.
>> +Locations may be specified using three different formats,
>> +linespec locations, explicit locations, or address locations.
>
> I would put a colon after "Different formats", not a comma.
Done.
>> +sources. In these cases, explicit locations point to the source
>> +line you meant more accurately and unequivocally. Also, using
> ^^^^^^^^^^^^^
> I would use "unambiguously" here.
Done.
>> +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 markup here is incorrect. Drop the quotes, and use @file for file
> names, @code for functions and labels, and @samp for everything else,
> like @samp{foo:bar}.
Fixed.
> I would use a more explicit
>
> @item -source @var{filename}
You know, now that you mention it, it's practically obvious! Fixed.
>> +to uniquely identify the desired file, e.g., ``foo/bar/baz.c''. Otherwise
> ^^^^^^^^^^^^^^^^^
> Drop the quotes and use @file markup for file names.
Fixed.
>
>> @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}
>
> Is LOCATION no longer an optional parameter for -break-insert?
Ha ha. I don't know how that happened, but, yes, you are correct.
LOCATION is still optional.
For the record, I'm reposting the whole patch. Thanks a million for the
review!
Keith
ChangeLog
2013-06-21 Keith Seitz <keiths@redhat.com>
* NEWS: Mention explicit locations.
* breakpoint.c [LOCATION_HELP_STRING]: New macro.
[BREAK_ARGS_HELP]: Use LOCATION_HELP_STRING.
(_initialize_breakpoint): Update documentation for
"clear", "break", "trace", "strace", "ftrace", and "dprintf".
doc/ChangeLog
2013-06-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. Add explanations for each
location type.
(Source and Machine Code): Use "location(s)" instead of
"linespec(s)".
(C Preprocessor Macros): Likewise.
(Create and Delete Tracepoints): 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 anchor.
Add reference to appropriate manual section discussing locations.
(The -dprintf-insert Command): Refer to -break-insert for
specification of `location'.
testsuite/ChangeLog
2013-06-21 Keith Seitz <keiths@redhat.com>
* gdb.base/help.exp: Update help_breakpoint_text.
diff --git a/gdb/NEWS b/gdb/NEWS
index ed1c32f..23f9a8b 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -181,6 +181,10 @@ Tilera TILE-Gx GNU/Linux tilegx*-*-linux
* 'info proc' now works on some core files.
+* GDB now allows users to specify explicit locations, bypassing
+ the linespec parser. This feature is also available to GDB/MI
+ clients.
+
* Python scripting
** Vectors can be created with gdb.Type.vector.
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index d7486e3..88a5024 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15842,25 +15842,44 @@ all_tracepoints (void)
}
\f
+/* This help string is used to consolidate all the help string for
specifying
+ locations used by several commands. */
+#define LOCATION_HELP_STRING \
+"Linespecs are colon-separated lists of location parameters, such as\n\
+source filename, function name, label name, and line number.\n\
+Example: To specify the start of a label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use\n\
+\"factorial.c:fact:the_top\".\n\
+\n\
+Address locations begin with \"*\" and specify an exact address in the\n\
+program. Example: To specify the fourth byte past the start function\n\
+\"main\", use \"*main + 4\".\n\
+\n\
+Explicit locations are similar to linespecs but use an option/argument\n\
+syntax to specify location parameters.\n\
+Example: To specify the start of the label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use \"-source factorial.c\n\
+-function fact -label the_top\".\n"
+
/* This help string is used for the break, hbreak, tbreak and thbreak
commands. It is defined as a macro to prevent duplication.
COMMAND should be a string constant containing the name of the
command. */
+
#define BREAK_ARGS_HELP(command) \
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, address, or explicit location as described\n\
+below.\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\
THREADNUM is the number from \"info threads\".\n\
CONDITION is a boolean expression.\n\
-\n\
+\n" LOCATION_HELP_STRING "\n\
Multiple breakpoints at one place are permitted, and useful if their\n\
conditions are different.\n\
\n\
@@ -16380,20 +16399,17 @@ 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 as described
below.\n\
\n\
With no argument, clears all breakpoints in the line that the selected
frame\n\
-is executing in.\n\
-\n\
+is executing in.\n"
+"\n" LOCATION_HELP_STRING "\n\
See also the \"delete\" command which clears breakpoints by number."));
add_com_alias ("cl", "clear", class_breakpoint, 1);
c = add_com ("break", class_breakpoint, break_command, _("\
-Set breakpoint at specified line or function.\n"
+Set breakpoint at specified location.\n"
BREAK_ARGS_HELP ("break")));
set_cmd_completer (c, location_completer);
@@ -16586,7 +16602,7 @@ hardware.)"),
/* Tracepoint manipulation commands. */
c = add_com ("trace", class_breakpoint, trace_command, _("\
-Set a tracepoint at specified line or function.\n\
+Set a tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("trace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
@@ -16598,31 +16614,27 @@ Do \"help tracepoints\" for info on other
tracepoint commands."));
add_com_alias ("trac", "trace", class_alias, 1);
c = add_com ("ftrace", class_breakpoint, ftrace_command, _("\
-Set a fast tracepoint at specified line or function.\n\
+Set a fast tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("ftrace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
set_cmd_completer (c, location_completer);
c = add_com ("strace", class_breakpoint, strace_command, _("\
-Set a static tracepoint at specified line, function or marker.\n\
+Set a static tracepoint at location 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\
-with that name. With no LOCATION, uses current execution address of\n\
-the selected stack frame.\n\
+LOCATION may be a linespec, explicit, or address location (described
below) \n\
+or -m MARKER_ID.\n\n\
+If a marker id is specified, probe the marker with that name. With\n\
+no LOCATION, uses current execution address of the selected stack frame.\n\
Static tracepoints accept an extra collect action -- ``collect
$_sdata''.\n\
This collects arbitrary user data passed in the probe point call to the\n\
tracing library. You can inspect it when analyzing the trace buffer,\n\
by printing the $_sdata variable like any other convenience variable.\n\
\n\
CONDITION is a boolean expression.\n\
-\n\
+\n" LOCATION_HELP_STRING "\n\
Multiple tracepoints at one place are permitted, and useful if their\n\
conditions are different.\n\
\n\
@@ -16777,11 +16789,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."));
+location may be a linespec, explicit, or address location.\n"
+"\n" LOCATION_HELP_STRING));
set_cmd_completer (c, location_completer);
add_setshow_enum_cmd ("dprintf-style", class_support,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d25cdae..736faa8 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5838,9 +5838,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.
@@ -7166,21 +7166,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}.
@@ -7205,11 +7205,16 @@ 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:
+@subsection Linespec Locations
+@anchor{Linespec Locations}
+
+A @dfn{linespec} is a colon-separated list of source location
parameters such
+as file name, function name, etc. Here are all the different ways of
+specifying a linespec:
@table @code
@item @var{linenum}
@@ -7248,25 +7253,93 @@ 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
+
+@subsection Explicit Locations
+@cindex explicit locations
+@anchor{Explicit Locations}
+
+@dfn{Explict locations} allow the user to directly specify the source
+location's parameters using option-value pairs.
+
+Explicit locations are useful when several functions, labels, or
+file names have the same name (base name for files) in the program's
+sources. In these cases, explicit locations point to the source
+line you meant more accurately and unambiguously. Also, using
+explicit locations might be faster in large programs.
+
+For example, the linespec @samp{foo:bar} may refer to a function @code{bar}
+defined in the file named @file{foo} or the label @code{bar} in a function
+named @code{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 @var{filename}
+The value specifies the source file name. To differentiate between
+files with the same base name, prepend as many directories as is necessary
+to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}.
Otherwise
+@value{GDBN} will use the first file it finds with the given base
+name. This option requires the use of either @code{-function} or
@code{-line}.
+
+@item -function @var{function}
+The value specifies the name of a function. Operations
+on function locations unmodified by other options (such as @code{-label}
+or @code{-line}) refer to the line that begins the body of the function.
+In C, for example, this is the line with the open brace.
+
+@item -label @var{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 @var{number}
+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 line.
+@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}.
+
+@subsection Address Locations
+@cindex address locations
+@anchor{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
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
@@ -7291,22 +7364,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
@@ -7624,9 +7681,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
@@ -7644,7 +7701,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.
@@ -7754,7 +7811,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}.
@@ -11093,9 +11150,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
@@ -11400,12 +11457,11 @@ conditions and actions.
@kindex trace
@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be a source line, a function name, or
-an address in the target program. @xref{Specify Location}. 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
+Its argument @var{location} can be any valid location.
+@xref{Specify Location}. 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
supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
in tracing}).
If remote stub doesn't support the @samp{InstallInTrace} feature, all
@@ -15240,14 +15296,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
@@ -16075,20 +16131,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
@@ -29723,6 +29776,7 @@ N.A.
@subheading The @code{-break-insert} Command
@findex -break-insert
+@anchor{-break-insert}
@subsubheading Synopsis
@@ -29730,21 +29784,41 @@ N.A.
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -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 the CLI'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
@@ -29836,17 +29910,8 @@ times="0"@}]@}
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
-
-@itemize @bullet
-@item @var{function}
-@c @item +offset
-@c @item -offset
-@c @item @var{linenum}
-@item @var{filename}:@var{linenum}
-@item @var{filename}:function
-@item *@var{address}
-@end itemize
+If supplied, @var{location} may be specified the same way as for
+the @code{-break-insert} command. @xref{-break-insert}.
The possible optional parameters of this command are:
diff --git a/gdb/testsuite/gdb.base/help.exp
b/gdb/testsuite/gdb.base/help.exp
index 86a02eb..2a9537e 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -58,7 +58,7 @@ test_class_help "user-defined" {
}
# Test help of an abbreviated command. "break" is picked at random.
-set help_breakpoint_text "Set breakpoint at specified line or function\..*"
+set help_breakpoint_text "Set breakpoint at specified location\..*"
# test help breakpoint "b" abbreviation
gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\"
abbreviation"
# test help breakpoint "br" abbreviation
[-- Attachment #2: explicit-doc.patch --]
[-- Type: text/x-patch, Size: 23579 bytes --]
diff --git a/gdb/NEWS b/gdb/NEWS
index ed1c32f..23f9a8b 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -181,6 +181,10 @@ Tilera TILE-Gx GNU/Linux tilegx*-*-linux
* 'info proc' now works on some core files.
+* GDB now allows users to specify explicit locations, bypassing
+ the linespec parser. This feature is also available to GDB/MI
+ clients.
+
* Python scripting
** Vectors can be created with gdb.Type.vector.
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index d7486e3..88a5024 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15842,25 +15842,44 @@ all_tracepoints (void)
}
\f
+/* This help string is used to consolidate all the help string for specifying
+ locations used by several commands. */
+#define LOCATION_HELP_STRING \
+"Linespecs are colon-separated lists of location parameters, such as\n\
+source filename, function name, label name, and line number.\n\
+Example: To specify the start of a label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use\n\
+\"factorial.c:fact:the_top\".\n\
+\n\
+Address locations begin with \"*\" and specify an exact address in the\n\
+program. Example: To specify the fourth byte past the start function\n\
+\"main\", use \"*main + 4\".\n\
+\n\
+Explicit locations are similar to linespecs but use an option/argument\n\
+syntax to specify location parameters.\n\
+Example: To specify the start of the label named \"the_top\" in the\n\
+function \"fact\" in the file \"factorial.c\", use \"-source factorial.c\n\
+-function fact -label the_top\".\n"
+
/* This help string is used for the break, hbreak, tbreak and thbreak
commands. It is defined as a macro to prevent duplication.
COMMAND should be a string constant containing the name of the
command. */
+
#define BREAK_ARGS_HELP(command) \
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, address, or explicit location as described\n\
+below.\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\
THREADNUM is the number from \"info threads\".\n\
CONDITION is a boolean expression.\n\
-\n\
+\n" LOCATION_HELP_STRING "\n\
Multiple breakpoints at one place are permitted, and useful if their\n\
conditions are different.\n\
\n\
@@ -16380,20 +16399,17 @@ 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 as described below.\n\
\n\
With no argument, clears all breakpoints in the line that the selected frame\n\
-is executing in.\n\
-\n\
+is executing in.\n"
+"\n" LOCATION_HELP_STRING "\n\
See also the \"delete\" command which clears breakpoints by number."));
add_com_alias ("cl", "clear", class_breakpoint, 1);
c = add_com ("break", class_breakpoint, break_command, _("\
-Set breakpoint at specified line or function.\n"
+Set breakpoint at specified location.\n"
BREAK_ARGS_HELP ("break")));
set_cmd_completer (c, location_completer);
@@ -16586,7 +16602,7 @@ hardware.)"),
/* Tracepoint manipulation commands. */
c = add_com ("trace", class_breakpoint, trace_command, _("\
-Set a tracepoint at specified line or function.\n\
+Set a tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("trace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
@@ -16598,31 +16614,27 @@ Do \"help tracepoints\" for info on other tracepoint commands."));
add_com_alias ("trac", "trace", class_alias, 1);
c = add_com ("ftrace", class_breakpoint, ftrace_command, _("\
-Set a fast tracepoint at specified line or function.\n\
+Set a fast tracepoint at specified location.\n\
\n"
BREAK_ARGS_HELP ("ftrace") "\n\
Do \"help tracepoints\" for info on other tracepoint commands."));
set_cmd_completer (c, location_completer);
c = add_com ("strace", class_breakpoint, strace_command, _("\
-Set a static tracepoint at specified line, function or marker.\n\
+Set a static tracepoint at location 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\
-with that name. With no LOCATION, uses current execution address of\n\
-the selected stack frame.\n\
+LOCATION may be a linespec, explicit, or address location (described below) \n\
+or -m MARKER_ID.\n\n\
+If a marker id is specified, probe the marker with that name. With\n\
+no LOCATION, uses current execution address of the selected stack frame.\n\
Static tracepoints accept an extra collect action -- ``collect $_sdata''.\n\
This collects arbitrary user data passed in the probe point call to the\n\
tracing library. You can inspect it when analyzing the trace buffer,\n\
by printing the $_sdata variable like any other convenience variable.\n\
\n\
CONDITION is a boolean expression.\n\
-\n\
+\n" LOCATION_HELP_STRING "\n\
Multiple tracepoints at one place are permitted, and useful if their\n\
conditions are different.\n\
\n\
@@ -16777,11 +16789,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."));
+location may be a linespec, explicit, or address location.\n"
+"\n" LOCATION_HELP_STRING));
set_cmd_completer (c, location_completer);
add_setshow_enum_cmd ("dprintf-style", class_support,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d25cdae..736faa8 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5838,9 +5838,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.
@@ -7166,21 +7166,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}.
@@ -7205,11 +7205,16 @@ 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:
+@subsection Linespec Locations
+@anchor{Linespec Locations}
+
+A @dfn{linespec} is a colon-separated list of source location parameters such
+as file name, function name, etc. Here are all the different ways of
+specifying a linespec:
@table @code
@item @var{linenum}
@@ -7248,25 +7253,93 @@ 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
+
+@subsection Explicit Locations
+@cindex explicit locations
+@anchor{Explicit Locations}
+
+@dfn{Explict locations} allow the user to directly specify the source
+location's parameters using option-value pairs.
+
+Explicit locations are useful when several functions, labels, or
+file names have the same name (base name for files) in the program's
+sources. In these cases, explicit locations point to the source
+line you meant more accurately and unambiguously. Also, using
+explicit locations might be faster in large programs.
+
+For example, the linespec @samp{foo:bar} may refer to a function @code{bar}
+defined in the file named @file{foo} or the label @code{bar} in a function
+named @code{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 @var{filename}
+The value specifies the source file name. To differentiate between
+files with the same base name, prepend as many directories as is necessary
+to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise
+@value{GDBN} will use the first file it finds with the given base
+name. This option requires the use of either @code{-function} or @code{-line}.
+
+@item -function @var{function}
+The value specifies the name of a function. Operations
+on function locations unmodified by other options (such as @code{-label}
+or @code{-line}) refer to the line that begins the body of the function.
+In C, for example, this is the line with the open brace.
+
+@item -label @var{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 @var{number}
+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 line.
+@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}.
+
+@subsection Address Locations
+@cindex address locations
+@anchor{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
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
@@ -7291,22 +7364,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
@@ -7624,9 +7681,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
@@ -7644,7 +7701,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.
@@ -7754,7 +7811,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}.
@@ -11093,9 +11150,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
@@ -11400,12 +11457,11 @@ conditions and actions.
@kindex trace
@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be a source line, a function name, or
-an address in the target program. @xref{Specify Location}. 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
+Its argument @var{location} can be any valid location.
+@xref{Specify Location}. 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
supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
in tracing}).
If remote stub doesn't support the @samp{InstallInTrace} feature, all
@@ -15240,14 +15296,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
@@ -16075,20 +16131,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
@@ -29723,6 +29776,7 @@ N.A.
@subheading The @code{-break-insert} Command
@findex -break-insert
+@anchor{-break-insert}
@subsubheading Synopsis
@@ -29730,21 +29784,41 @@ N.A.
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -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 the CLI'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
@@ -29836,17 +29910,8 @@ times="0"@}]@}
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
-
-@itemize @bullet
-@item @var{function}
-@c @item +offset
-@c @item -offset
-@c @item @var{linenum}
-@item @var{filename}:@var{linenum}
-@item @var{filename}:function
-@item *@var{address}
-@end itemize
+If supplied, @var{location} may be specified the same way as for
+the @code{-break-insert} command. @xref{-break-insert}.
The possible optional parameters of this command are:
diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index 86a02eb..2a9537e 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -58,7 +58,7 @@ test_class_help "user-defined" {
}
# Test help of an abbreviated command. "break" is picked at random.
-set help_breakpoint_text "Set breakpoint at specified line or function\..*"
+set help_breakpoint_text "Set breakpoint at specified location\..*"
# test help breakpoint "b" abbreviation
gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\" abbreviation"
# test help breakpoint "br" abbreviation
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2013-06-21 21:21 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-03-21 23:59 [RFA 4/4 doc] Explicit locations Keith Seitz
2013-03-22 1:00 ` Keith Seitz
2013-03-22 9:46 ` Eli Zaretskii
2013-06-20 0:11 ` Keith Seitz
2013-06-21 9:53 ` Eli Zaretskii
2013-06-21 23:32 ` Keith Seitz
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox