python: Add Inferior.progspace property

[deliverable/binutils-gdb.git] / gdb / doc / python.texi

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index eb4c3a53781e4cfd9c6d2824e0e7ac43ec390dea..75d8ae1e39994e99922097a5b167c4dce0849332 100644 (file)
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -207,6 +207,10 @@ methods and classes added by @value{GDBN} are placed in this module.
 @value{GDBN} automatically @code{import}s the @code{gdb} module for
 use in all scripts evaluated by the @code{python} command.
 
+Some types of the @code{gdb} module come with a textual representation
+(accessible through the @code{repr} or @code{str} functions).  These are
+offered for debugging purposes only, expect them to change over time.
+
 @findex gdb.PYTHONDIR
 @defvar gdb.PYTHONDIR
 A string containing the python directory (@pxref{Python}).
@@ -448,7 +452,7 @@ as a string, or @code{None}.
 @end defun
 
 @findex gdb.decode_line 
-@defun gdb.decode_line @r{[}expression@r{]}
+@defun gdb.decode_line (@r{[}expression@r{]})
 Return locations of the line specified by @var{expression}, or of the
 current line if no argument was given.  This function returns a Python
 tuple containing two elements.  The first element contains a string
@@ -658,14 +662,14 @@ The type of this @code{gdb.Value}.  The value of this attribute is a
 @end defvar
 
 @defvar Value.dynamic_type
-The dynamic type of this @code{gdb.Value}.  This uses C@t{++} run-time
-type information (@acronym{RTTI}) to determine the dynamic type of the
-value.  If this value is of class type, it will return the class in
-which the value is embedded, if any.  If this value is of pointer or
-reference to a class type, it will compute the dynamic type of the
-referenced object, and return a pointer or reference to that type,
-respectively.  In all other cases, it will return the value's static
-type.
+The dynamic type of this @code{gdb.Value}.  This uses the object's
+virtual table and the C@t{++} run-time type information
+(@acronym{RTTI}) to determine the dynamic type of the value.  If this
+value is of class type, it will return the class in which the value is
+embedded, if any.  If this value is of pointer or reference to a class
+type, it will compute the dynamic type of the referenced object, and
+return a pointer or reference to that type, respectively.  In all
+other cases, it will return the value's static type.
 
 Note that this feature will only work when debugging a C@t{++} program
 that includes @acronym{RTTI} for the object in question.  Otherwise,
@@ -1253,10 +1257,9 @@ Python module (@pxref{gdb.types}).
 @subsubsection Pretty Printing API
 @cindex python pretty printing api
 
-An example output is provided (@pxref{Pretty Printing}).
-
 A pretty-printer is just an object that holds a value and implements a
-specific interface, defined here.
+specific interface, defined here.  An example output is provided
+(@pxref{Pretty Printing}).
 
 @defun pretty_printer.children (self)
 @value{GDBN} will call this method on a pretty-printer to compute the
@@ -2833,6 +2836,10 @@ Boolean signaling whether the inferior was created using `attach', or
 started by @value{GDBN} itself.
 @end defvar
 
+@defvar Inferior.progspace
+The inferior's program space.  @xref{Progspaces In Python}.
+@end defvar
+
 A @code{gdb.Inferior} object has the following methods:
 
 @defun Inferior.is_valid ()
@@ -3992,7 +3999,9 @@ The following progspace-related functions are available in the
 @findex gdb.current_progspace
 @defun gdb.current_progspace ()
 This function returns the program space of the currently selected inferior.
-@xref{Inferiors and Programs}.
+@xref{Inferiors and Programs}.  This is identical to
+@code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
+included for historical compatibility.
 @end defun
 
 @findex gdb.progspaces
@@ -4224,7 +4233,7 @@ from a different place.
 @end defun
 
 @node Frames In Python
-@subsubsection Accessing inferior stack frames from Python.
+@subsubsection Accessing inferior stack frames from Python
 
 @cindex frames in python
 When the debugged program stops, @value{GDBN} is able to analyze its call
@@ -4426,7 +4435,7 @@ Stack}.
 @end defun
 
 @node Blocks In Python
-@subsubsection Accessing blocks from Python.
+@subsubsection Accessing blocks from Python
 
 @cindex blocks in python
 @tindex gdb.Block
@@ -4559,7 +4568,7 @@ writable.
 @end defvar
 
 @node Symbols In Python
-@subsubsection Python representation of Symbols.
+@subsubsection Python representation of Symbols
 
 @cindex symbols in python
 @tindex gdb.Symbol
@@ -4799,7 +4808,7 @@ The value's address is a computed location.
 @end vtable
 
 @node Symbol Tables In Python
-@subsubsection Symbol table representation in Python.
+@subsubsection Symbol table representation in Python
 
 @cindex symbol tables in python
 @tindex gdb.Symtab
@@ -5275,7 +5284,7 @@ is not writable.
 @end defvar
 
 @node Lazy Strings In Python
-@subsubsection Python representation of lazy strings.
+@subsubsection Python representation of lazy strings
 
 @cindex lazy strings in python
 @tindex gdb.LazyString