This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]