@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}).
@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
@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 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,
@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
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 ()
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
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)
@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
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
@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
@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
@end defun
@node Blocks In Python
-@subsubsection Accessing blocks from Python.
+@subsubsection Accessing blocks from Python
@cindex blocks in python
@tindex gdb.Block
@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 defvar
@node Symbols In Python
-@subsubsection Python representation of Symbols.
+@subsubsection Python representation of Symbols
@cindex symbols in python
@tindex gdb.Symbol
@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
@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
-@subsubsection Symbol table representation in Python.
+@subsubsection Symbol table representation in Python
@cindex symbol tables in python
@tindex gdb.Symtab
@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
projects / deliverable / binutils-gdb.git / blobdiff