Re: [RFA 4/4 doc] Explicit locations

[Keith Seitz <keiths at redhat dot com>]

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