gdb: Introduce 'print max-depth' feature

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

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index d4d295c2121316b5f3a8af6159ef81ddce44b1fe..b47c38deef70b3d394b9e22b839379062175afac 100644 (file)
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1,4 +1,4 @@
-@c Copyright (C) 2008-2017 Free Software Foundation, Inc.
+@c Copyright (C) 2008-2019 Free Software Foundation, Inc.

 @c Permission is granted to copy, distribute and/or modify this document
 @c under the terms of the GNU Free Documentation License, Version 1.3 or
 @c any later version published by the Free Software Foundation; with the
 @c Permission is granted to copy, distribute and/or modify this document
 @c under the terms of the GNU Free Documentation License, Version 1.3 or
 @c any later version published by the Free Software Foundation; with the


@@ -18,6 +18,8 @@
 You can extend @value{GDBN} using the @uref{http://www.python.org/,
 Python programming language}.  This feature is available only if
 @value{GDBN} was configured using @option{--with-python}.
 You can extend @value{GDBN} using the @uref{http://www.python.org/,
 Python programming language}.  This feature is available only if
 @value{GDBN} was configured using @option{--with-python}.

+@value{GDBN} can be built against either Python 2 or Python 3; which
+one you have depends on this configure-time option.

 
 @cindex python directory
 Python scripts used by @value{GDBN} should be installed in
 
 @cindex python directory
 Python scripts used by @value{GDBN} should be installed in


@@ -113,10 +115,6 @@ interpreter:
 The script name must end with @samp{.py} and @value{GDBN} must be configured
 to recognize the script language based on filename extension using
 the @code{script-extension} setting.  @xref{Extending GDB, ,Extending GDB}.
 The script name must end with @samp{.py} and @value{GDBN} must be configured
 to recognize the script language based on filename extension using
 the @code{script-extension} setting.  @xref{Extending GDB, ,Extending GDB}.

-
-@item python execfile ("script-name")
-This method is based on the @code{execfile} Python built-in function,
-and thus is always available.

 @end table
 
 @node Python API
 @end table
 
 @node Python API


@@ -209,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.
 
 @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}).
 @findex gdb.PYTHONDIR
 @defvar gdb.PYTHONDIR
 A string containing the python directory (@pxref{Python}).


@@ -288,6 +290,26 @@ If no exception is raised, the return value is always an instance of
 @code{gdb.Value} (@pxref{Values From Inferior}).
 @end defun
 
 @code{gdb.Value} (@pxref{Values From Inferior}).
 @end defun
 

+@findex gdb.convenience_variable
+@defun gdb.convenience_variable (name)
+Return the value of the convenience variable (@pxref{Convenience
+Vars}) named @var{name}.  @var{name} must be a string.  The name
+should not include the @samp{$} that is used to mark a convenience
+variable in an expression.  If the convenience variable does not
+exist, then @code{None} is returned.
+@end defun
+
+@findex gdb.set_convenience_variable
+@defun gdb.set_convenience_variable (name, value)
+Set the value of the convenience variable (@pxref{Convenience Vars})
+named @var{name}.  @var{name} must be a string.  The name should not
+include the @samp{$} that is used to mark a convenience variable in an
+expression.  If @var{value} is @code{None}, then the convenience
+variable is removed.  Otherwise, if @var{value} is not a
+@code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
+using the @code{gdb.Value} constructor.
+@end defun
+

 @findex gdb.parse_and_eval
 @defun gdb.parse_and_eval (expression)
 Parse @var{expression}, which must be a string, as an expression in
 @findex gdb.parse_and_eval
 @defun gdb.parse_and_eval (expression)
 Parse @var{expression}, which must be a string, as an expression in


@@ -297,8 +319,7 @@ the current language, evaluate it, and return the result as a
 This function can be useful when implementing a new command
 (@pxref{Commands In Python}), as it provides a way to parse the
 command's argument as an expression.  It is also useful simply to
 This function can be useful when implementing a new command
 (@pxref{Commands In Python}), as it provides a way to parse the
 command's argument as an expression.  It is also useful simply to

-compute values, for example, it is the only way to get the value of a
-convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
+compute values.

 @end defun
 
 @findex gdb.find_pc_line
 @end defun
 
 @findex gdb.find_pc_line


@@ -307,7 +328,9 @@ Return the @code{gdb.Symtab_and_line} object corresponding to the
 @var{pc} value.  @xref{Symbol Tables In Python}.  If an invalid
 value of @var{pc} is passed as an argument, then the @code{symtab} and
 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
 @var{pc} value.  @xref{Symbol Tables In Python}.  If an invalid
 value of @var{pc} is passed as an argument, then the @code{symtab} and
 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object

-will be @code{None} and 0 respectively.
+will be @code{None} and 0 respectively.  This is identical to
+@code{gdb.current_progspace().find_pc_line(pc)} and is included for
+historical compatibility.

 @end defun
 
 @findex gdb.post_event
 @end defun
 
 @findex gdb.post_event


@@ -427,11 +450,13 @@ never returned.
 @findex gdb.solib_name
 @defun gdb.solib_name (address)
 Return the name of the shared library holding the given @var{address}
 @findex gdb.solib_name
 @defun gdb.solib_name (address)
 Return the name of the shared library holding the given @var{address}

-as a string, or @code{None}.
+as a string, or @code{None}.  This is identical to
+@code{gdb.current_progspace().solib_name(address)} and is included for
+historical compatibility.

 @end defun
 
 @findex gdb.decode_line 
 @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
 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


@@ -509,12 +534,20 @@ message as its value and the Python call stack backtrace at the Python
 statement closest to where the @value{GDBN} error occured as the
 traceback.
 
 statement closest to where the @value{GDBN} error occured as the
 traceback.
 

-@findex gdb.GdbError
-When implementing @value{GDBN} commands in Python via @code{gdb.Command},
-it is useful to be able to throw an exception that doesn't cause a
-traceback to be printed.  For example, the user may have invoked the
-command incorrectly.  Use the @code{gdb.GdbError} exception
-to handle this case.  Example:
+
+When implementing @value{GDBN} commands in Python via
+@code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
+to be able to throw an exception that doesn't cause a traceback to be
+printed.  For example, the user may have invoked the command
+incorrectly.  @value{GDBN} provides a special exception class that can
+be used for this purpose.
+
+@ftable @code
+@item gdb.GdbError
+When thrown from a command or function, this exception will cause the
+command or function to fail, but the Python stack will not be
+displayed.  @value{GDBN} does not throw this exception itself, but
+rather recognizes it when thrown from user Python code.  Example:

 
 @smallexample
 (gdb) python
 
 @smallexample
 (gdb) python


@@ -532,6 +565,7 @@ to handle this case.  Example:
 (gdb) hello-world 42
 hello-world takes no arguments
 @end smallexample
 (gdb) hello-world 42
 hello-world takes no arguments
 @end smallexample

+@end ftable

 
 @node Values From Inferior
 @subsubsection Values From Inferior
 
 @node Values From Inferior
 @subsubsection Values From Inferior


@@ -632,14 +666,14 @@ The type of this @code{gdb.Value}.  The value of this attribute is a
 @end defvar
 
 @defvar Value.dynamic_type
 @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,
 
 Note that this feature will only work when debugging a C@t{++} program
 that includes @acronym{RTTI} for the object in question.  Otherwise,


@@ -701,6 +735,14 @@ its result is used.
 @end table
 @end defun
 
 @end table
 @end defun
 

+@defun Value.__init__ (@var{val}, @var{type})
+This second form of the @code{gdb.Value} constructor returns a
+@code{gdb.Value} of type @var{type} where the value contents are taken
+from the Python buffer object specified by @var{val}.  The number of
+bytes in the Python buffer object must be greater than or equal to the
+size of @var{type}.
+@end defun
+

 @defun Value.cast (type)
 Return a new instance of @code{gdb.Value} that is the result of
 casting this instance to the type described by @var{type}, which must
 @defun Value.cast (type)
 Return a new instance of @code{gdb.Value} that is the result of
 casting this instance to the type described by @var{type}, which must


@@ -822,6 +864,91 @@ Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
 operator were used.  Consult a C@t{++} reference for details.
 @end defun
 
 operator were used.  Consult a C@t{++} reference for details.
 @end defun
 

+@defun Value.format_string (...)
+Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
+command does.  Invoked with no arguments, this is equivalent to calling
+the @code{str} function on the @code{gdb.Value}.  The representation of
+the same value may change across different versions of @value{GDBN}, so
+you shouldn't, for instance, parse the strings returned by this method.
+
+All the arguments are keyword only.  If an argument is not specified, the
+current global default setting is used.
+
+@table @code
+@item raw
+@code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
+used to format the value.  @code{False} if enabled pretty-printers
+matching the type represented by the @code{gdb.Value} should be used to
+format it.
+
+@item pretty_arrays
+@code{True} if arrays should be pretty printed to be more convenient to
+read, @code{False} if they shouldn't (see @code{set print array} in
+@ref{Print Settings}).
+
+@item pretty_structs
+@code{True} if structs should be pretty printed to be more convenient to
+read, @code{False} if they shouldn't (see @code{set print pretty} in
+@ref{Print Settings}).
+
+@item array_indexes
+@code{True} if array indexes should be included in the string
+representation of arrays, @code{False} if they shouldn't (see @code{set
+print array-indexes} in @ref{Print Settings}).
+
+@item symbols
+@code{True} if the string representation of a pointer should include the
+corresponding symbol name (if one exists), @code{False} if it shouldn't
+(see @code{set print symbol} in @ref{Print Settings}).
+
+@item unions
+@code{True} if unions which are contained in other structures or unions
+should be expanded, @code{False} if they shouldn't (see @code{set print
+union} in @ref{Print Settings}).
+
+@item deref_refs
+@code{True} if C@t{++} references should be resolved to the value they
+refer to, @code{False} (the default) if they shouldn't.  Note that, unlike
+for the @code{print} command, references are not automatically expanded
+when using the @code{format_string} method or the @code{str}
+function.  There is no global @code{print} setting to change the default
+behaviour.
+
+@item actual_objects
+@code{True} if the representation of a pointer to an object should
+identify the @emph{actual} (derived) type of the object rather than the
+@emph{declared} type, using the virtual function table.  @code{False} if
+the @emph{declared} type should be used.  (See @code{set print object} in
+@ref{Print Settings}).
+
+@item static_fields
+@code{True} if static members should be included in the string
+representation of a C@t{++} object, @code{False} if they shouldn't (see
+@code{set print static-members} in @ref{Print Settings}).
+
+@item max_elements
+Number of array elements to print, or @code{0} to print an unlimited
+number of elements (see @code{set print elements} in @ref{Print
+Settings}).
+
+@item max_depth
+The maximum depth to print for nested structs and unions, or @code{-1}
+to print an unlimited number of elements (see @code{set print
+max-depth} in @ref{Print Settings}).
+
+@item repeat_threshold
+Set the threshold for suppressing display of repeated array elements, or
+@code{0} to represent all elements, even if repeated.  (See @code{set
+print repeats} in @ref{Print Settings}).
+
+@item format
+A string containing a single character representing the format to use for
+the returned string.  For instance, @code{'x'} is equivalent to using the
+@value{GDBN} command @code{print} with the @code{/x} option and formats
+the value as a hexadecimal number.
+@end table
+@end defun
+

 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
 If this @code{gdb.Value} represents a string, then this method
 converts the contents to a Python string.  Otherwise, this method will
 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
 If this @code{gdb.Value} represents a string, then this method
 converts the contents to a Python string.  Otherwise, this method will


@@ -930,6 +1057,13 @@ description of the @code{Type.fields} method for a description of the
 
 An instance of @code{Type} has the following attributes:
 
 
 An instance of @code{Type} has the following attributes:
 

+@defvar Type.alignof
+The alignment of this type, in bytes.  Type alignment comes from the
+debugging information; if it was not specified, then @value{GDBN} will
+use the relevant ABI to try to determine the alignment.  In some
+cases, even this is not possible, and zero will be returned.
+@end defvar
+

 @defvar Type.code
 The type code for this type.  The type code will be one of the
 @code{TYPE_CODE_} constants defined below.
 @defvar Type.code
 The type code for this type.  The type code will be one of the
 @code{TYPE_CODE_} constants defined below.


@@ -1220,10 +1354,9 @@ Python module (@pxref{gdb.types}).
 @subsubsection Pretty Printing API
 @cindex python pretty printing api
 
 @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
 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
 
 @defun pretty_printer.children (self)
 @value{GDBN} will call this method on a pretty-printer to compute the


@@ -1237,6 +1370,9 @@ object which is convertible to a @value{GDBN} value.
 
 This method is optional.  If it does not exist, @value{GDBN} will act
 as though the value has no children.
 
 This method is optional.  If it does not exist, @value{GDBN} will act
 as though the value has no children.

+
+Children may be hidden from display based on the value of @samp{set
+print max-depth} (@pxref{Print Settings}).

 @end defun
 
 @defun pretty_printer.display_hint (self)
 @end defun
 
 @defun pretty_printer.display_hint (self)


@@ -1246,7 +1382,7 @@ consumer as a @samp{displayhint} attribute of the variable being
 printed.
 
 This method is optional.  If it does exist, this method must return a
 printed.
 
 This method is optional.  If it does exist, this method must return a

-string.
+string or the special value @code{None}.

 
 Some display hints are predefined by @value{GDBN}:
 
 
 Some display hints are predefined by @value{GDBN}:
 


@@ -1269,6 +1405,9 @@ string-printing function to format the string.  For the CLI this means
 adding quotation marks, possibly escaping some characters, respecting
 @code{set print elements}, and the like.
 @end table
 adding quotation marks, possibly escaping some characters, respecting
 @code{set print elements}, and the like.
 @end table

+
+The special value @code{None} causes @value{GDBN} to apply the default
+display rules.

 @end defun
 
 @defun pretty_printer.to_string (self)
 @end defun
 
 @defun pretty_printer.to_string (self)


@@ -1315,10 +1454,21 @@ printer exists, then this returns @code{None}.
 @subsubsection Selecting Pretty-Printers
 @cindex selecting python pretty-printers
 
 @subsubsection Selecting Pretty-Printers
 @cindex selecting python pretty-printers
 

+@value{GDBN} provides several ways to register a pretty-printer:
+globally, per program space, and per objfile.  When choosing how to
+register your pretty-printer, a good rule is to register it with the
+smallest scope possible: that is prefer a specific objfile first, then
+a program space, and only register a printer globally as a last
+resort.
+
+@findex gdb.pretty_printers
+@defvar gdb.pretty_printers

 The Python list @code{gdb.pretty_printers} contains an array of
 functions or callable objects that have been registered via addition
 as a pretty-printer.  Printers in this list are called @code{global}
 printers, they're available when debugging all inferiors.
 The Python list @code{gdb.pretty_printers} contains an array of
 functions or callable objects that have been registered via addition
 as a pretty-printer.  Printers in this list are called @code{global}
 printers, they're available when debugging all inferiors.

+@end defvar
+

 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
 attribute.
 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
 attribute.


@@ -1590,7 +1740,7 @@ order to avoid holding information that could become stale as the
 inferior changed.
 
 @node Frame Filter API
 inferior changed.
 
 @node Frame Filter API

-@subsubsection Filtering Frames.
+@subsubsection Filtering Frames

 @cindex frame filters api
 
 Frame filters are Python objects that manipulate the visibility of a
 @cindex frame filters api
 
 Frame filters are Python objects that manipulate the visibility of a


@@ -1742,11 +1892,11 @@ frame filters.  Although @code{priority} can be negative, it is
 recommended practice to assume zero is the lowest priority that a
 frame filter can be assigned.  Frame filters that have the same
 priority are executed in unsorted order in that priority slot.  This
 recommended practice to assume zero is the lowest priority that a
 frame filter can be assigned.  Frame filters that have the same
 priority are executed in unsorted order in that priority slot.  This

-attribute is mandatory.
+attribute is mandatory.  100 is a good default priority.

 @end defvar
 
 @node Frame Decorator API
 @end defvar
 
 @node Frame Decorator API

-@subsubsection Decorating Frames.
+@subsubsection Decorating Frames

 @cindex frame decorator api
 
 Frame decorators are sister objects to frame filters (@pxref{Frame
 @cindex frame decorator api
 
 Frame decorators are sister objects to frame filters (@pxref{Frame


@@ -1770,6 +1920,13 @@ boilerplate code to decorate the content of a @code{gdb.Frame}.  It is
 recommended that other frame decorators inherit and extend this
 object, and only to override the methods needed.
 
 recommended that other frame decorators inherit and extend this
 object, and only to override the methods needed.
 

+@tindex gdb.FrameDecorator
+@code{FrameDecorator} is defined in the Python module
+@code{gdb.FrameDecorator}, so your code can import it like:
+@smallexample
+from gdb.FrameDecorator import FrameDecorator
+@end smallexample
+

 @defun FrameDecorator.elided (self)
 
 The @code{elided} method groups frames together in a hierarchical
 @defun FrameDecorator.elided (self)
 
 The @code{elided} method groups frames together in a hierarchical


@@ -2248,17 +2405,40 @@ return @code{None}.  The code in @value{GDBN} that enables writing
 unwinders in Python uses this object to return frame's ID and previous
 frame registers when @value{GDBN} core asks for them.
 
 unwinders in Python uses this object to return frame's ID and previous
 frame registers when @value{GDBN} core asks for them.
 

+An unwinder should do as little work as possible.  Some otherwise
+innocuous operations can cause problems (even crashes, as this code is
+not not well-hardened yet).  For example, making an inferior call from
+an unwinder is unadvisable, as an inferior call will reset
+@value{GDBN}'s stack unwinding process, potentially causing re-entrant
+unwinding.
+

 @subheading Unwinder Input
 
 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
 provides a method to read frame's registers:
 
 @defun PendingFrame.read_register (reg)
 @subheading Unwinder Input
 
 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
 provides a method to read frame's registers:
 
 @defun PendingFrame.read_register (reg)

-This method returns the contents of the register @var{regn} in the
+This method returns the contents of the register @var{reg} in the

 frame as a @code{gdb.Value} object.  @var{reg} can be either a
 register number or a register name; the values are platform-specific.
 They are usually found in the corresponding
 frame as a @code{gdb.Value} object.  @var{reg} can be either a
 register number or a register name; the values are platform-specific.
 They are usually found in the corresponding

-@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
+@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.  If
+@var{reg} does not name a register for the current architecture, this
+method will throw an exception.
+
+Note that this method will always return a @code{gdb.Value} for a
+valid register name.  This does not mean that the value will be valid.
+For example, you may request a register that an earlier unwinder could
+not unwind---the value will be unavailable.  Instead, the
+@code{gdb.Value} returned from this method will be lazy; that is, its
+underlying bits will not be fetched until it is first used.  So,
+attempting to use such a value will cause an exception at the point of
+use.
+
+The type of the returned @code{gdb.Value} depends on the register and
+the architecture.  It is common for registers to have a scalar type,
+like @code{long long}; but many other types are possible, such as
+pointer, pointer-to-function, floating point or vector types.

 @end defun
 
 It also provides a factory method to create a @code{gdb.UnwindInfo}
 @end defun
 
 It also provides a factory method to create a @code{gdb.UnwindInfo}


@@ -2271,18 +2451,32 @@ using one of functions provided by @value{GDBN}.  @var{frame_id}'s attributes
 determine which function will be used, as follows:
 
 @table @code
 determine which function will be used, as follows:
 
 @table @code

-@item sp, pc, special
-@code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
-

 @item sp, pc
 @item sp, pc

-@code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
+The frame is identified by the given stack address and PC.  The stack
+address must be chosen so that it is constant throughout the lifetime
+of the frame, so a typical choice is the value of the stack pointer at
+the start of the function---in the DWARF standard, this would be the
+``Call Frame Address''.

 
 

-This is the most common case.
+This is the most common case by far.  The other cases are documented
+for completeness but are only useful in specialized situations.
+
+@item sp, pc, special
+The frame is identified by the stack address, the PC, and a
+``special'' address.  The special address is used on architectures
+that can have frames that do not change the stack, but which are still
+distinct, for example the IA-64, which has a second stack for
+registers.  Both @var{sp} and @var{special} must be constant
+throughout the lifetime of the frame.

 
 @item sp
 
 @item sp

-@code{frame_id_build_wild (@var{frame_id}.sp)}
+The frame is identified by the stack address only.  Any other stack
+frame with a matching @var{sp} will be considered to match this frame.
+Inside gdb, this is called a ``wild frame''.  You will never need
+this.

 @end table
 @end table

-The attribute values should be @code{gdb.Value}
+
+Each attribute value should be an instance of @code{gdb.Value}.

 
 @end defun
 
 
 @end defun
 


@@ -2756,6 +2950,10 @@ Boolean signaling whether the inferior was created using `attach', or
 started by @value{GDBN} itself.
 @end defvar
 
 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 ()
 A @code{gdb.Inferior} object has the following methods:
 
 @defun Inferior.is_valid ()


@@ -2772,6 +2970,14 @@ when it is called.  If there are no valid threads, the method will
 return an empty tuple.
 @end defun
 
 return an empty tuple.
 @end defun
 

+@defun Inferior.architecture ()
+Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
+for this inferior.  This represents the architecture of the inferior
+as a whole.  Some platforms can have multiple architectures in a
+single address space, so this may not match the architecture of a
+particular frame (@pxref{Frames In Python}).
+@end defun
+

 @findex Inferior.read_memory
 @defun Inferior.read_memory (address, length)
 Read @var{length} addressable memory units from the inferior, starting at
 @findex Inferior.read_memory
 @defun Inferior.read_memory (address, length)
 Read @var{length} addressable memory units from the inferior, starting at


@@ -2802,11 +3008,16 @@ containing the address where the pattern was found, or @code{None} if
 the pattern could not be found.
 @end defun
 
 the pattern could not be found.
 @end defun
 

+@findex Inferior.thread_from_handle

 @findex Inferior.thread_from_thread_handle
 @findex Inferior.thread_from_thread_handle

-@defun Inferior.thread_from_thread_handle (thread_handle)
-Return the thread object corresponding to @var{thread_handle}, a thread
+@defun Inferior.thread_from_handle (handle)
+Return the thread object corresponding to @var{handle}, a thread

 library specific data structure such as @code{pthread_t} for pthreads
 library implementations.
 library specific data structure such as @code{pthread_t} for pthreads
 library implementations.

+
+The function @code{Inferior.thread_from_thread_handle} provides
+the same functionality, but use of @code{Inferior.thread_from_thread_handle}
+is deprecated.

 @end defun
 
 @node Events In Python
 @end defun
 
 @node Events In Python


@@ -2945,9 +3156,16 @@ A reference to the program space (@code{gdb.Progspace}) whose objfile list has
 been cleared.  @xref{Progspaces In Python}.
 @end defvar
 
 been cleared.  @xref{Progspaces In Python}.
 @end defvar
 

-@item events.inferior_call_pre
-Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
-the inferior is about to be called.
+@item events.inferior_call
+Emits events just before and after a function in the inferior is
+called by @value{GDBN}.  Before an inferior call, this emits an event
+of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
+this emits an event of type @code{gdb.InferiorCallPostEvent}.
+
+@table @code
+@tindex gdb.InferiorCallPreEvent
+@item @code{gdb.InferiorCallPreEvent}
+Indicates that a function in the inferior is about to be called.

 
 @defvar InferiorCallPreEvent.ptid
 The thread in which the call will be run.
 
 @defvar InferiorCallPreEvent.ptid
 The thread in which the call will be run.


@@ -2957,9 +3175,9 @@ The thread in which the call will be run.
 The location of the function to be called.
 @end defvar
 
 The location of the function to be called.
 @end defvar
 

-@item events.inferior_call_post
-Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
-the inferior has returned.
+@tindex gdb.InferiorCallPostEvent
+@item @code{gdb.InferiorCallPostEvent}
+Indicates that a function in the inferior has just been called.

 
 @defvar InferiorCallPostEvent.ptid
 The thread in which the call was run.
 
 @defvar InferiorCallPostEvent.ptid
 The thread in which the call was run.


@@ -2968,6 +3186,7 @@ The thread in which the call was run.
 @defvar InferiorCallPostEvent.address
 The location of the function that was called.
 @end defvar
 @defvar InferiorCallPostEvent.address
 The location of the function that was called.
 @end defvar

+@end table

 
 @item events.memory_changed
 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
 
 @item events.memory_changed
 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the


@@ -3128,6 +3347,14 @@ Return a Boolean indicating whether the thread is running.
 Return a Boolean indicating whether the thread is exited.
 @end defun
 
 Return a Boolean indicating whether the thread is exited.
 @end defun
 

+@defun InferiorThread.handle ()
+Return the thread object's handle, represented as a Python @code{bytes}
+object.  A @code{gdb.Value} representation of the handle may be
+constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
+the Python @code{bytes} representation of the handle and @var{type} is
+a @code{gdb.Type} for the handle type.
+@end defun
+

 @node Recordings In Python
 @subsubsection Recordings In Python
 @cindex recordings in python
 @node Recordings In Python
 @subsubsection Recordings In Python
 @cindex recordings in python


@@ -3722,14 +3949,40 @@ parameter.  It can be read and assigned to just as any other
 attribute.  @value{GDBN} does validation when assignments are made.
 @end defvar
 
 attribute.  @value{GDBN} does validation when assignments are made.
 @end defvar
 

-There are two methods that should be implemented in any
-@code{Parameter} class.  These are:
+There are two methods that may be implemented in any @code{Parameter}
+class.  These are:

 
 @defun Parameter.get_set_string (self)
 
 @defun Parameter.get_set_string (self)

-@value{GDBN} will call this method when a @var{parameter}'s value has
-been changed via the @code{set} API (for example, @kbd{set foo off}).
-The @code{value} attribute has already been populated with the new
-value and may be used in output.  This method must return a string.
+If this method exists, @value{GDBN} will call it when a
+@var{parameter}'s value has been changed via the @code{set} API (for
+example, @kbd{set foo off}).  The @code{value} attribute has already
+been populated with the new value and may be used in output.  This
+method must return a string.  If the returned string is not empty,
+@value{GDBN} will present it to the user.
+
+If this method raises the @code{gdb.GdbError} exception
+(@pxref{Exception Handling}), then @value{GDBN} will print the
+exception's string and the @code{set} command will fail.  Note,
+however, that the @code{value} attribute will not be reset in this
+case.  So, if your parameter must validate values, it should store the
+old value internally and reset the exposed value, like so:
+
+@smallexample
+class ExampleParam (gdb.Parameter):
+   def __init__ (self, name):
+      super (ExampleParam, self).__init__ (name,
+                   gdb.COMMAND_DATA,
+                   gdb.PARAM_BOOLEAN)
+      self.value = True
+      self.saved_value = True
+   def validate(self):
+      return False
+   def get_set_string (self):
+      if not self.validate():
+        self.value = self.saved_value
+        raise gdb.GdbError('Failed to validate')
+      self.saved_value = self.value
+@end smallexample

 @end defun
 
 @defun Parameter.get_show_string (self, svalue)
 @end defun
 
 @defun Parameter.get_show_string (self, svalue)


@@ -3800,6 +4053,19 @@ The value is a filename.  This is just like
 The value is an integer.  This is like @code{PARAM_INTEGER}, except 0
 is interpreted as itself.
 
 The value is an integer.  This is like @code{PARAM_INTEGER}, except 0
 is interpreted as itself.
 

+@findex PARAM_ZUINTEGER
+@findex gdb.PARAM_ZUINTEGER
+@item gdb.PARAM_ZUINTEGER
+The value is an unsigned integer.  This is like @code{PARAM_INTEGER},
+except 0 is interpreted as itself, and the value cannot be negative.
+
+@findex PARAM_ZUINTEGER_UNLIMITED
+@findex gdb.PARAM_ZUINTEGER_UNLIMITED
+@item gdb.PARAM_ZUINTEGER_UNLIMITED
+The value is a signed integer.  This is like @code{PARAM_ZUINTEGER},
+except the special value -1 should be interpreted to mean
+``unlimited''.  Other negative values are not allowed.
+

 @findex PARAM_ENUM
 @findex gdb.PARAM_ENUM
 @item gdb.PARAM_ENUM
 @findex PARAM_ENUM
 @findex gdb.PARAM_ENUM
 @item gdb.PARAM_ENUM


@@ -3892,7 +4158,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.
 @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
 @end defun
 
 @findex gdb.progspaces


@@ -3926,6 +4194,45 @@ The @code{frame_filters} attribute is a dictionary of frame filter
 objects.  @xref{Frame Filter API}, for more information.
 @end defvar
 
 objects.  @xref{Frame Filter API}, for more information.
 @end defvar
 

+A program space has the following methods:
+
+@findex Progspace.block_for_pc
+@defun Progspace.block_for_pc (pc)
+Return the innermost @code{gdb.Block} containing the given @var{pc}
+value.  If the block cannot be found for the @var{pc} value specified,
+the function will return @code{None}.
+@end defun
+
+@findex Progspace.find_pc_line
+@defun Progspace.find_pc_line (pc)
+Return the @code{gdb.Symtab_and_line} object corresponding to the
+@var{pc} value.  @xref{Symbol Tables In Python}.  If an invalid value
+of @var{pc} is passed as an argument, then the @code{symtab} and
+@code{line} attributes of the returned @code{gdb.Symtab_and_line}
+object will be @code{None} and 0 respectively.
+@end defun
+
+@findex Progspace.is_valid
+@defun Progspace.is_valid ()
+Returns @code{True} if the @code{gdb.Progspace} object is valid,
+@code{False} if not.  A @code{gdb.Progspace} object can become invalid
+if the program space file it refers to is not referenced by any
+inferior.  All other @code{gdb.Progspace} methods will throw an
+exception if it is invalid at the time the method is called.
+@end defun
+
+@findex Progspace.objfiles
+@defun Progspace.objfiles ()
+Return a sequence of all the objfiles referenced by this program
+space.  @xref{Objfiles In Python}.
+@end defun
+
+@findex Progspace.solib_name
+@defun Progspace.solib_name (address)
+Return the name of the shared library holding the given @var{address}
+as a string, or @code{None}.
+@end defun
+

 One may add arbitrary attributes to @code{gdb.Progspace} objects
 in the usual Python way.
 This is useful if, for example, one needs to do some extra record keeping
 One may add arbitrary attributes to @code{gdb.Progspace} objects
 in the usual Python way.
 This is useful if, for example, one needs to do some extra record keeping


@@ -3995,8 +4302,10 @@ this function returns @code{None}.
 
 @findex gdb.objfiles
 @defun gdb.objfiles ()
 
 @findex gdb.objfiles
 @defun gdb.objfiles ()

-Return a sequence of all the objfiles current known to @value{GDBN}.
-@xref{Objfiles In Python}.
+Return a sequence of objfiles referenced by the current program space.
+@xref{Objfiles In Python}, and @ref{Progspaces In Python}.  This is identical
+to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
+historical compatibility.

 @end defun
 
 @findex gdb.lookup_objfile
 @end defun
 
 @findex gdb.lookup_objfile


@@ -4016,7 +4325,7 @@ is the build ID of the objfile.  Otherwise, @var{name} is a file name.
 This is supported only on some operating systems, notably those which use
 the ELF format for binary files and the @sc{gnu} Binutils.  For more details
 about this feature, see the description of the @option{--build-id}
 This is supported only on some operating systems, notably those which use
 the ELF format for binary files and the @sc{gnu} Binutils.  For more details
 about this feature, see the description of the @option{--build-id}

-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,

 The GNU Linker}.
 @end defun
 
 The GNU Linker}.
 @end defun
 


@@ -4052,7 +4361,7 @@ If the objfile does not have a build ID then the value is @code{None}.
 This is supported only on some operating systems, notably those which use
 the ELF format for binary files and the @sc{gnu} Binutils.  For more details
 about this feature, see the description of the @option{--build-id}
 This is supported only on some operating systems, notably those which use
 the ELF format for binary files and the @sc{gnu} Binutils.  For more details
 about this feature, see the description of the @option{--build-id}

-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,

 The GNU Linker}.
 @end defvar
 
 The GNU Linker}.
 @end defvar
 


@@ -4124,7 +4433,7 @@ from a different place.
 @end defun
 
 @node Frames In Python
 @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
 
 @cindex frames in python
 When the debugged program stops, @value{GDBN} is able to analyze its call


@@ -4280,7 +4589,10 @@ Returns the frame's resume address.
 @end defun
 
 @defun Frame.block ()
 @end defun
 
 @defun Frame.block ()

-Return the frame's code block.  @xref{Blocks In Python}.
+Return the frame's code block.  @xref{Blocks In Python}.  If the frame
+does not have a block -- for example, if there is no debugging
+information for the code in question -- then this will throw an
+exception.

 @end defun
 
 @defun Frame.function ()
 @end defun
 
 @defun Frame.function ()


@@ -4323,7 +4635,7 @@ Stack}.
 @end defun
 
 @node Blocks In Python
 @end defun
 
 @node Blocks In Python

-@subsubsection Accessing blocks from Python.
+@subsubsection Accessing blocks from Python

 
 @cindex blocks in python
 @tindex gdb.Block
 
 @cindex blocks in python
 @tindex gdb.Block


@@ -4393,7 +4705,9 @@ module:
 @defun gdb.block_for_pc (pc)
 Return the innermost @code{gdb.Block} containing the given @var{pc}
 value.  If the block cannot be found for the @var{pc} value specified,
 @defun gdb.block_for_pc (pc)
 Return the innermost @code{gdb.Block} containing the given @var{pc}
 value.  If the block cannot be found for the @var{pc} value specified,

-the function will return @code{None}.
+the function will return @code{None}.  This is identical to
+@code{gdb.current_progspace().block_for_pc(pc)} and is included for
+historical compatibility.

 @end defun
 
 A @code{gdb.Block} object has the following methods:
 @end defun
 
 A @code{gdb.Block} object has the following methods:


@@ -4414,7 +4728,8 @@ The start address of the block.  This attribute is not writable.
 @end defvar
 
 @defvar Block.end
 @end defvar
 
 @defvar Block.end

-The end address of the block.  This attribute is not writable.
+One past the last address that appears in the block.  This attribute
+is not writable.

 @end defvar
 
 @defvar Block.function
 @end defvar
 
 @defvar Block.function


@@ -4455,7 +4770,7 @@ writable.
 @end defvar
 
 @node Symbols In Python
 @end defvar
 
 @node Symbols In Python

-@subsubsection Python representation of Symbols.
+@subsubsection Python representation of Symbols

 
 @cindex symbols in python
 @tindex gdb.Symbol
 
 @cindex symbols in python
 @tindex gdb.Symbol


@@ -4610,18 +4925,13 @@ This domain holds struct, union and enum type names.
 @item gdb.SYMBOL_LABEL_DOMAIN
 This domain contains names of labels (for gotos).
 
 @item gdb.SYMBOL_LABEL_DOMAIN
 This domain contains names of labels (for gotos).
 

-@vindex SYMBOL_VARIABLES_DOMAIN
-@item gdb.SYMBOL_VARIABLES_DOMAIN
-This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
-contains everything minus functions and types.
+@vindex SYMBOL_MODULE_DOMAIN
+@item gdb.SYMBOL_MODULE_DOMAIN
+This domain contains names of Fortran module types.

 
 

-@vindex SYMBOL_FUNCTIONS_DOMAIN
-@item gdb.SYMBOL_FUNCTIONS_DOMAIN
-This domain contains all functions.
-
-@vindex SYMBOL_TYPES_DOMAIN
-@item gdb.SYMBOL_TYPES_DOMAIN
-This domain contains all types.
+@vindex SYMBOL_COMMON_BLOCK_DOMAIN
+@item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
+This domain contains names of Fortran common blocks.

 @end vtable
 
 The available address class categories in @code{gdb.Symbol} are represented
 @end vtable
 
 The available address class categories in @code{gdb.Symbol} are represented


@@ -4692,10 +5002,15 @@ The value does not actually exist in the program.
 @vindex SYMBOL_LOC_COMPUTED
 @item gdb.SYMBOL_LOC_COMPUTED
 The value's address is a computed location.
 @vindex SYMBOL_LOC_COMPUTED
 @item gdb.SYMBOL_LOC_COMPUTED
 The value's address is a computed location.

+
+@vindex SYMBOL_LOC_COMPUTED
+@item gdb.SYMBOL_LOC_COMPUTED
+The value's address is a symbol.  This is only used for Fortran common
+blocks.

 @end vtable
 
 @node Symbol Tables In Python
 @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
 
 @cindex symbol tables in python
 @tindex gdb.Symtab


@@ -5116,7 +5431,7 @@ value is @code{None}.  This attribute is writable.
 This attribute holds the commands attached to the breakpoint.  If
 there are commands, this attribute's value is a string holding all the
 commands, separated by newlines.  If there are no commands, this
 This attribute holds the commands attached to the breakpoint.  If
 there are commands, this attribute's value is a string holding all the
 commands, separated by newlines.  If there are no commands, this

-attribute is @code{None}.  This attribute is not writable.
+attribute is @code{None}.  This attribute is writable.

 @end defvar
 
 @node Finish Breakpoints in Python
 @end defvar
 
 @node Finish Breakpoints in Python


@@ -5171,7 +5486,7 @@ is not writable.
 @end defvar
 
 @node Lazy Strings In Python
 @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
 
 @cindex lazy strings in python
 @tindex gdb.LazyString