This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[RFA 5/5] Explicit linespecs - documentation
- From: Keith Seitz <keiths at redhat dot com>
- To: "gdb-patches at sourceware dot org ml" <gdb-patches at sourceware dot org>
- Date: Thu, 26 Jul 2012 20:49:59 -0700
- Subject: [RFA 5/5] Explicit linespecs - documentation
Hi,
The patch below adds documentation for explicit linespecs for both MI
and "Locations" chapters of the manual.
Questions/comments/concerns?
Keith
ChangeLog
2012-07-26 Keith Seitz <keiths@redhat.com>
* NEWS: Mention new explicit linespec feature.
doc/ChangeLog
2012-07-26 Keith Seitz <keiths@redhat.com>
* gdb.texinfo (Specifying a Location): Describe explicit
linespecs.
(GDB/MI Breakpoint Commands): Likewise for -break-insert.
diff --git a/gdb/NEWS b/gdb/NEWS
index a590bee..09c2403 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -19,6 +19,9 @@ maint info bfds
*** Changes in GDB 7.5
+* GDB now allows users to specify explicit locations, bypassing
+ the linespec parser. Feature also accessible from GDB/MI.
+
* GDB now supports x32 ABI. Visit <http://sites.google.com/site/x32abi/>
for more x32 ABI info.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index facca8f..e0c3792 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6760,7 +6760,16 @@ 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}.
-Here are all the different ways of specifying a code location that
+Linespecs may be specified implicitly or explicitly. Implicit linespecs
+are parsed by the linespec parser and converted into a location.
+This often involves multiple searches through the program's symbol
+table. For large programs, this may be extremely time-consuming.
+
+Explicit linespecs avoid a lot of this searching by allowing the direct
+specification of file name, function, and/or other source location
+attributes.
+
+Here are all the different ways of specifying an implicit code location
that
@value{GDBN} understands:
@table @code
@@ -6858,6 +6867,32 @@ each one of those probes.
@end table
+Explicit linespecs maybe be specified using the generalized form
+@samp{-option value}. The list of valid options is summarized in the
+following table:
+
+@table @code
+@item @var{-source}
+The value specifies the source filename for the location. This option
+requires the use of at least one other explicit linespec option.
+
+@item @var{-function}
+The value specifies the name of a function for the location.
+
+@item @var{-label}
+The value specifies the name of a label for the location.
+
+@item @var{-offset}
+The value specifies an offset for the location. This option may either be
+an absolute (@var{-offset 3}) or relative (@var{-offset +3}) offset.
+
+@item @var{-address}
+The value specifies any valid code address in the program. This option
+may not be used with any other option.
+@end table
+
+Explicit linespec options may be abbreviated by omitting any non-unique
+trailing characters from the option name, e.g., @code{break -func main
-o 3}.
@node Edit
@section Editing Source Files
@@ -28088,7 +28123,8 @@ 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} | @var{explicit_location}]
+
@end smallexample
@noindent
@@ -28104,6 +28140,28 @@ If specified, @var{location}, can be one of:
@item *address
@end itemize
+@noindent
+An @var{explicit_location} may be used instead of a @var{location}
+by supplying at least one of the following options:
+
+@table @samp
+@item -s @var{filename}
+The source file name of the location. This option requires the use
+of at least one other explicit linespec option.
+
+@item -m @var{function}
+The name of a function.
+
+@item -l @var{label}
+The name of a label.
+
+@item -o @var{offset}
+An absolute or relative offset from the start of the location.
+
+@item -e @var{address}
+A code address of the program.
+@end table
+
The possible optional parameters of this command are:
@table @samp