public inbox for archer-commits@sourceware.org
help / color / mirror / Atom feed
* [SCM] archer-tromey-python: * gdb.texinfo (Basic Python): Document gdb.get_objfiles and
@ 2008-11-13 20:58 tromey
0 siblings, 0 replies; only message in thread
From: tromey @ 2008-11-13 20:58 UTC (permalink / raw)
To: archer-commits
The branch, archer-tromey-python has been updated
via 2186d22ef00b023f4dfd6c84f104b23797c08558 (commit)
from c72d8bd86890c414f264984a8e63f8d16a08df94 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email.
- Log -----------------------------------------------------------------
commit 2186d22ef00b023f4dfd6c84f104b23797c08558
Author: Tom Tromey <tromey@redhat.com>
Date: Thu Nov 13 13:58:38 2008 -0700
* gdb.texinfo (Basic Python): Document gdb.get_objfiles and
gdb.get_current_objfile.
(Objfiles in Python): New node.
(Auto-loading): Change to -gdb.py convention.
(Pretty Printing): Update example. Document objfile search.
-----------------------------------------------------------------------
Summary of changes:
gdb/doc/ChangeLog | 8 ++++
gdb/doc/gdb.texinfo | 89 +++++++++++++++++++++++++++++++++++++++++---------
2 files changed, 81 insertions(+), 16 deletions(-)
First 500 lines of diff:
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index a25df37..6dad6d3 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,11 @@
+2008-11-13 Tom Tromey <tromey@redhat.com>
+
+ * gdb.texinfo (Basic Python): Document gdb.get_objfiles and
+ gdb.get_current_objfile.
+ (Objfiles in Python): New node.
+ (Auto-loading): Change to -gdb.py convention.
+ (Pretty Printing): Update example. Document objfile search.
+
2008-11-06 Tom Tromey <tromey@redhat.com>
* gdb.texinfo (File Options): Document -x on .py files.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a7038b5..42ed962 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -17712,6 +17712,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
* Threads In Python:: Accessing inferior threads from Python.
* Commands In Python:: Implementing new commands in Python.
* Parameters In Python:: Adding new @value{GDBN} parameters.
+* Objfiles in Python:: Object files.
@end menu
@node Basic Python
@@ -17737,6 +17738,20 @@ command as having originated from the user invoking it interactively.
It must be a boolean value. If omitted, it defaults to @code{False}.
@end defun
+@findex gdb.get_current_objfile
+@defun get_current_objfile
+When auto-loading a Python script (@pxref{Auto-loading}), @var{GDBN}
+sets the ``current objfile'' to the corresponding objfile. This
+function returns the current objfile. If there is no current objfile,
+this function returns @code{None}.
+@end defun
+
+@findex gdb.get_objfiles
+@defun get_objfiles
+Return a sequence of all the objfiles current known to @var{GDBN}.
+@xref{Objfiles in Python}.
+@end defun
+
@findex gdb.get_parameter
@defun get_parameter parameter
Return the value of a @value{GDBN} parameter. @var{parameter} is a
@@ -17797,21 +17812,26 @@ traceback.
@node Auto-loading
@subsubsection Auto-loading
-When a new object file is read (for example, due to the @code{file}
-command, or because the inferior has loaded a shared library),
-@value{GDBN} will look for a file named @file{.gdb.py} in the
-directory holding the object file. If this file exists and is
-readable, @value{GDBN} will evaluate it as a Python script. Note
-that, if a separate debug file is used, @value{GDBN} will look for
-@file{.gdb.py} both in the directory associated with the application
-and the directory associated with the separate debug file.
+When a new object file (@pxref{Objfiles in Python}) is read (for
+example, due to the @code{file} command, or because the inferior has
+loaded a shared library), @value{GDBN} will look for a file named by
+adding @samp{-gdb.py} to the object file's name. If this file exists
+and is readable, @value{GDBN} will evaluate it as a Python script.
+Note that, if a separate debug file is used, @value{GDBN} will look
+for the @samp{-gdb.py} file both in the directory associated with the
+application and the directory associated with the separate debug file.
+
+When reading a @samp{-gdb.py} file, @var{GDBN} sets the ``current
+objfile''. This is available via the @code{gdb.get_current_objfile}
+function. This can be useful for registering objfile-specific
+pretty-printers.
This feature is useful for supplying application-specific debugging
commands and scripts. It can be disabled using @code{maint set python
auto-load}.
@value{GDBN} does not track which files it has already auto-loaded.
-So, your @file{.gdb.py} should take care to ensure that it may be
+So, your @samp{-gdb.py} file should take care to ensure that it may be
evaluated multiple times without error.
@node Values From Inferior
@@ -18008,7 +18028,8 @@ This method must return a string.
@subsubsection Selecting Pretty-Printers
The Python dictionary @code{gdb.pretty_printers} maps regular
-expressions (strings) onto constructors. A constructor, in this
+expressions (strings) onto constructors. Each @code{gdb.Objfile} also
+contains a @code{pretty_printers} attribute. A constructor, in this
context, is a function which takes a single @code{gdb.Value} argument
and returns a a pretty-printer conforming to the interface definition
above.
@@ -18016,12 +18037,20 @@ above.
When printing a value, @value{GDBN} first computes the value's
canonical type by following typedefs, following a reference type to
its referenced type, and removing qualifiers, such as @code{const} or
-@code{volatile}. The name of this type is then compared to each
-regular expression. If a regular expression matches, then the
-corresponding pretty-printer is invoked with a @code{gdb.Value}
-representing the value to be printed.
+@code{volatile}.
+
+Then, @var{GDBN} tests each regular expression against this type name.
+@var{GDBN} first checks the @code{pretty_printers} attribute of each
+@code{gdb.Objfile}; after these have been exhausted it tries the
+global @code{gdb.pretty_printers}.
+
+If a regular expression matches, then the corresponding pretty-printer
+is invoked with a @code{gdb.Value} representing the value to be
+printed.
-The order in which the regular expressions are tried is not specified.
+The order in which the objfiles are searched is not specified.
+Similarly, the order in which the regular expressions in a given
+dictionary are tried is not specified.
Here is an example showing how a @code{std::string} printer might be
written:
@@ -18036,7 +18065,8 @@ class StdStringPrinter:
def to_string(self):
return self.val['_M_dataplus']['_M_p']
-gdb.pretty_printers['^std::basic_string<char.*>$'] = StdStringPrinter
+obj = gdb.get_current_objfile()
+obj.pretty_printers['^std::basic_string<char.*>$'] = StdStringPrinter
@end smallexample
@node Threads In Python
@@ -18395,6 +18425,33 @@ The value is a string, which must be one of a collection string
constants provided when the parameter is created.
@end table
+@node Objfiles in Python
+@subsubsection Objfiles in Python
+
+@cindex objfiles in python
+@cindex python objfiles
+@tindex gdb.Objfile
+@tindex Objfile
+@var{GDBN} loads symbols for an inferior from various
+symbol-containing files. These include the primary executable file,
+any shared libraries used by the inferior, and any separate debug info
+files. @var{GDBN} calls these symbol-containing files
+@dfn{objfiles}.
+
+Each objfile is represented by an instance of the @code{gdb.Objfile}
+class.
+
+@defmethod Objfile get_filename
+Return the file name of the objfile as a string.
+@end defmethod
+
+@defivar Objfile pretty_printers
+The @code{pretty_printers} attribute is used to look up
+pretty-printers by type. This is a dictionary which maps regular
+expressions (strings) to pretty-printing objects. @xref{Pretty
+Printing}, for more information.
+@end defivar
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
hooks/post-receive
--
Repository for Project Archer.
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2008-11-13 20:58 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2008-11-13 20:58 [SCM] archer-tromey-python: * gdb.texinfo (Basic Python): Document gdb.get_objfiles and tromey
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).