-@c Copyright (C) 2008-2014 Free Software Foundation, Inc.
+@c Copyright (C) 2008-2016 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
* Frame Filter API:: Filtering Frames.
* Frame Decorator API:: Decorating Frames.
* Writing a Frame Filter:: Writing a Frame Filter.
+* Unwinding Frames in Python:: Writing frame unwinder.
+* Xmethods In Python:: Adding and replacing methods of C++ classes.
+* Xmethod API:: Xmethod types.
+* Writing an Xmethod:: Writing an xmethod.
* Inferiors In Python:: Python representation of inferiors (processes)
* Events In Python:: Listening for events from @value{GDBN}.
* Threads In Python:: Accessing inferior threads from Python.
If a GDB exception happens while @var{command} runs, it is
translated as described in @ref{Exception Handling,,Exception Handling}.
-@var{from_tty} specifies whether @value{GDBN} ought to consider this
+The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
command as having originated from the user invoking it interactively.
It must be a boolean value. If omitted, it defaults to @code{False}.
By default, any output produced by @var{command} is sent to
-@value{GDBN}'s standard output. If the @var{to_string} parameter is
+@value{GDBN}'s standard output (and to the log output if logging is
+turned on). If the @var{to_string} parameter is
@code{True}, then output will be collected by @code{gdb.execute} and
returned as a string. The default is @code{False}, in which case the
return value is @code{None}. If @var{to_string} is @code{True}, the
@findex gdb.parameter
@defun gdb.parameter (parameter)
-Return the value of a @value{GDBN} parameter. @var{parameter} is a
-string naming the parameter to look up; @var{parameter} may contain
-spaces if the parameter has a multi-part name. For example,
-@samp{print object} is a valid parameter name.
+Return the value of a @value{GDBN} @var{parameter} given by its name,
+a string; the parameter name string may contain spaces if the parameter has a
+multi-part name. For example, @samp{print object} is a valid
+parameter name.
If the named parameter does not exist, this function throws a
@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
@findex gdb.history
@defun gdb.history (number)
Return a value from @value{GDBN}'s value history (@pxref{Value
-History}). @var{number} indicates which history element to return.
+History}). The @var{number} argument indicates which history element to return.
If @var{number} is negative, then @value{GDBN} will take its absolute value
and count backward from the last element (i.e., the most recent element) to
find the value to return. If @var{number} is zero, then @value{GDBN} will
@findex gdb.parse_and_eval
@defun gdb.parse_and_eval (expression)
-Parse @var{expression} as an expression in the current language,
-evaluate it, and return the result as a @code{gdb.Value}.
-@var{expression} must be a string.
+Parse @var{expression}, which must be a string, as an expression in
+the current language, evaluate it, and return the result as a
+@code{gdb.Value}.
This function can be useful when implementing a new command
(@pxref{Commands In Python}), as it provides a way to parse the
@value{GDBN} is not thread-safe. If your Python program uses multiple
threads, you must be careful to only call @value{GDBN}-specific
-functions in the main @value{GDBN} thread. @code{post_event} ensures
+functions in the @value{GDBN} thread. @code{post_event} ensures
this. For example:
@smallexample
@noindent
As result of this, @code{bar} will also be a @code{gdb.Value} object
-whose values are of the same type as those of @code{some_val}.
+whose values are of the same type as those of @code{some_val}. Valid
+Python operations can also be performed on @code{gdb.Value} objects
+representing a @code{struct} or @code{class} object. For such cases,
+the overloaded operator (if present), is used to perform the operation.
+For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
+representing instances of a @code{class} which overloads the @code{+}
+operator, then one can use the @code{+} operator in their Python script
+as follows:
+
+@smallexample
+val3 = val1 + val2
+@end smallexample
+
+@noindent
+The result of the operation @code{val3} is also a @code{gdb.Value}
+object corresponding to the value returned by the overloaded @code{+}
+operator. In general, overloaded operators are invoked for the
+following operations: @code{+} (binary addition), @code{-} (binary
+subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
+@code{>>}, @code{|}, @code{&}, @code{^}.
Inferior values that are structures or instances of some class can
be accessed using the Python @dfn{dictionary syntax}. For example, if
current architecture.
@item Python string
-A Python string is converted to a target string, using the current
-target encoding.
+A Python string is converted to a target string in the current target
+language using the current target encoding.
+If a character cannot be represented in the current target encoding,
+then an exception is thrown.
@item @code{gdb.Value}
If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
corresponding to @code{val}.
@end defun
+@defun Value.reference_value ()
+Return a @code{gdb.Value} object which is a reference to the value
+encapsulated by this instance.
+@end defun
+
+@defun Value.const_value ()
+Return a @code{gdb.Value} object which is a @code{const} version of the
+value encapsulated by this instance.
+@end defun
+
@defun Value.dynamic_cast (type)
Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
operator were used. Consult a C@t{++} reference for details.
converts the contents to a Python string. Otherwise, this method will
throw an exception.
-Strings are recognized in a language-specific way; whether a given
-@code{gdb.Value} represents a string is determined by the current
-language.
+Values are interpreted as strings according to the rules of the
+current language. If the optional length argument is given, the
+string will be converted to that length, and will include any embedded
+zeroes that the string may contain. Otherwise, for languages
+where the string is zero-terminated, the entire string will be
+converted.
-For C-like languages, a value is a string if it is a pointer to or an
-array of characters or ints. The string is assumed to be terminated
-by a zero of the appropriate width. However if the optional length
-argument is given, the string will be converted to that given length,
-ignoring any embedded zeros that the string may contain.
+For example, in C-like languages, a value is a string if it is a pointer
+to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
+or @code{char32_t}.
If the optional @var{encoding} argument is given, it must be a string
naming the encoding of the string in the @code{gdb.Value}, such as
@findex gdb.lookup_type
@defun gdb.lookup_type (name @r{[}, block@r{]})
-This function looks up a type by name. @var{name} is the name of the
-type to look up. It must be a string.
+This function looks up a type by its @var{name}, which must be a string.
If @var{block} is given, then @var{name} is looked up in that scope.
Otherwise, it is searched for globally.
@defun Type.template_argument (n @r{[}, block@r{]})
If this @code{gdb.Type} is an instantiation of a template, this will
-return a new @code{gdb.Type} which represents the type of the
-@var{n}th template argument.
+return a new @code{gdb.Value} or @code{gdb.Type} which represents the
+value of the @var{n}th template argument (indexed starting at 0).
-If this @code{gdb.Type} is not a template type, this will throw an
-exception. Ordinarily, only C@t{++} code will have template types.
+If this @code{gdb.Type} is not a template type, or if the type has fewer
+than @var{n} template arguments, this will throw an exception.
+Ordinarily, only C@t{++} code will have template types.
If @var{block} is given, then @var{name} is looked up in that scope.
Otherwise, it is searched for globally.
@end defun
+@defun Type.optimized_out ()
+Return @code{gdb.Value} instance of this type whose value is optimized
+out. This allows a frame decorator to indicate that the value of an
+argument or a local variable is not known.
+@end defun
Each type has a code, which indicates what category this type falls
into. The available type categories are represented by constants
defined in the @code{gdb} module:
-@table @code
-@findex TYPE_CODE_PTR
-@findex gdb.TYPE_CODE_PTR
+@vtable @code
+@vindex TYPE_CODE_PTR
@item gdb.TYPE_CODE_PTR
The type is a pointer.
-@findex TYPE_CODE_ARRAY
-@findex gdb.TYPE_CODE_ARRAY
+@vindex TYPE_CODE_ARRAY
@item gdb.TYPE_CODE_ARRAY
The type is an array.
-@findex TYPE_CODE_STRUCT
-@findex gdb.TYPE_CODE_STRUCT
+@vindex TYPE_CODE_STRUCT
@item gdb.TYPE_CODE_STRUCT
The type is a structure.
-@findex TYPE_CODE_UNION
-@findex gdb.TYPE_CODE_UNION
+@vindex TYPE_CODE_UNION
@item gdb.TYPE_CODE_UNION
The type is a union.
-@findex TYPE_CODE_ENUM
-@findex gdb.TYPE_CODE_ENUM
+@vindex TYPE_CODE_ENUM
@item gdb.TYPE_CODE_ENUM
The type is an enum.
-@findex TYPE_CODE_FLAGS
-@findex gdb.TYPE_CODE_FLAGS
+@vindex TYPE_CODE_FLAGS
@item gdb.TYPE_CODE_FLAGS
A bit flags type, used for things such as status registers.
-@findex TYPE_CODE_FUNC
-@findex gdb.TYPE_CODE_FUNC
+@vindex TYPE_CODE_FUNC
@item gdb.TYPE_CODE_FUNC
The type is a function.
-@findex TYPE_CODE_INT
-@findex gdb.TYPE_CODE_INT
+@vindex TYPE_CODE_INT
@item gdb.TYPE_CODE_INT
The type is an integer type.
-@findex TYPE_CODE_FLT
-@findex gdb.TYPE_CODE_FLT
+@vindex TYPE_CODE_FLT
@item gdb.TYPE_CODE_FLT
A floating point type.
-@findex TYPE_CODE_VOID
-@findex gdb.TYPE_CODE_VOID
+@vindex TYPE_CODE_VOID
@item gdb.TYPE_CODE_VOID
The special type @code{void}.
-@findex TYPE_CODE_SET
-@findex gdb.TYPE_CODE_SET
+@vindex TYPE_CODE_SET
@item gdb.TYPE_CODE_SET
A Pascal set type.
-@findex TYPE_CODE_RANGE
-@findex gdb.TYPE_CODE_RANGE
+@vindex TYPE_CODE_RANGE
@item gdb.TYPE_CODE_RANGE
A range type, that is, an integer type with bounds.
-@findex TYPE_CODE_STRING
-@findex gdb.TYPE_CODE_STRING
+@vindex TYPE_CODE_STRING
@item gdb.TYPE_CODE_STRING
A string type. Note that this is only used for certain languages with
language-defined string types; C strings are not represented this way.
-@findex TYPE_CODE_BITSTRING
-@findex gdb.TYPE_CODE_BITSTRING
+@vindex TYPE_CODE_BITSTRING
@item gdb.TYPE_CODE_BITSTRING
A string of bits. It is deprecated.
-@findex TYPE_CODE_ERROR
-@findex gdb.TYPE_CODE_ERROR
+@vindex TYPE_CODE_ERROR
@item gdb.TYPE_CODE_ERROR
An unknown or erroneous type.
-@findex TYPE_CODE_METHOD
-@findex gdb.TYPE_CODE_METHOD
+@vindex TYPE_CODE_METHOD
@item gdb.TYPE_CODE_METHOD
A method type, as found in C@t{++} or Java.
-@findex TYPE_CODE_METHODPTR
-@findex gdb.TYPE_CODE_METHODPTR
+@vindex TYPE_CODE_METHODPTR
@item gdb.TYPE_CODE_METHODPTR
A pointer-to-member-function.
-@findex TYPE_CODE_MEMBERPTR
-@findex gdb.TYPE_CODE_MEMBERPTR
+@vindex TYPE_CODE_MEMBERPTR
@item gdb.TYPE_CODE_MEMBERPTR
A pointer-to-member.
-@findex TYPE_CODE_REF
-@findex gdb.TYPE_CODE_REF
+@vindex TYPE_CODE_REF
@item gdb.TYPE_CODE_REF
A reference type.
-@findex TYPE_CODE_CHAR
-@findex gdb.TYPE_CODE_CHAR
+@vindex TYPE_CODE_CHAR
@item gdb.TYPE_CODE_CHAR
A character type.
-@findex TYPE_CODE_BOOL
-@findex gdb.TYPE_CODE_BOOL
+@vindex TYPE_CODE_BOOL
@item gdb.TYPE_CODE_BOOL
A boolean type.
-@findex TYPE_CODE_COMPLEX
-@findex gdb.TYPE_CODE_COMPLEX
+@vindex TYPE_CODE_COMPLEX
@item gdb.TYPE_CODE_COMPLEX
A complex float type.
-@findex TYPE_CODE_TYPEDEF
-@findex gdb.TYPE_CODE_TYPEDEF
+@vindex TYPE_CODE_TYPEDEF
@item gdb.TYPE_CODE_TYPEDEF
A typedef to some other type.
-@findex TYPE_CODE_NAMESPACE
-@findex gdb.TYPE_CODE_NAMESPACE
+@vindex TYPE_CODE_NAMESPACE
@item gdb.TYPE_CODE_NAMESPACE
A C@t{++} namespace.
-@findex TYPE_CODE_DECFLOAT
-@findex gdb.TYPE_CODE_DECFLOAT
+@vindex TYPE_CODE_DECFLOAT
@item gdb.TYPE_CODE_DECFLOAT
A decimal floating point type.
-@findex TYPE_CODE_INTERNAL_FUNCTION
-@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
+@vindex TYPE_CODE_INTERNAL_FUNCTION
@item gdb.TYPE_CODE_INTERNAL_FUNCTION
A function internal to @value{GDBN}. This is the type used to represent
convenience functions.
-@end table
+@end vtable
Further support for types is provided in the @code{gdb.types}
Python module (@pxref{gdb.types}).
@node Pretty Printing API
@subsubsection Pretty Printing API
+@cindex python pretty printing api
An example output is provided (@pxref{Pretty Printing}).
@node Selecting Pretty-Printers
@subsubsection Selecting Pretty-Printers
+@cindex selecting python pretty-printers
The Python list @code{gdb.pretty_printers} contains an array of
functions or callable objects that have been registered via addition
@defmethod type_recognizer recognize (self, type)
If @var{type} is not recognized, return @code{None}. Otherwise,
return a string which is to be printed as the name of @var{type}.
-@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
-Python}).
+The @var{type} argument will be an instance of @code{gdb.Type}
+(@pxref{Types In Python}).
@end defmethod
@value{GDBN} uses this two-pass approach so that type printers can
marker in the inlined frame, and also show the hierarchical
relationship.
+@node Unwinding Frames in Python
+@subsubsection Unwinding Frames in Python
+@cindex unwinding frames in Python
+
+In @value{GDBN} terminology ``unwinding'' is the process of finding
+the previous frame (that is, caller's) from the current one. An
+unwinder has three methods. The first one checks if it can handle
+given frame (``sniff'' it). For the frames it can sniff an unwinder
+provides two additional methods: it can return frame's ID, and it can
+fetch registers from the previous frame. A running @value{GDBN}
+mantains a list of the unwinders and calls each unwinder's sniffer in
+turn until it finds the one that recognizes the current frame. There
+is an API to register an unwinder.
+
+The unwinders that come with @value{GDBN} handle standard frames.
+However, mixed language applications (for example, an application
+running Java Virtual Machine) sometimes use frame layouts that cannot
+be handled by the @value{GDBN} unwinders. You can write Python code
+that can handle such custom frames.
+
+You implement a frame unwinder in Python as a class with which has two
+attributes, @code{name} and @code{enabled}, with obvious meanings, and
+a single method @code{__call__}, which examines a given frame and
+returns an object (an instance of @code{gdb.UnwindInfo class)}
+describing it. If an unwinder does not recognize a frame, it should
+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.
+
+@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
+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.
+@end defun
+
+It also provides a factory method to create a @code{gdb.UnwindInfo}
+instance to be returned to @value{GDBN}:
+
+@defun PendingFrame.create_unwind_info (frame_id)
+Returns a new @code{gdb.UnwindInfo} instance identified by given
+@var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
+using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
+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
+@code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
+
+This is the most common case.
+
+@item sp
+@code{frame_id_build_wild (@var{frame_id}.sp)}
+@end table
+The attribute values should be @code{gdb.Value}
+
+@end defun
+
+@subheading Unwinder Output: UnwindInfo
+
+Use @code{PendingFrame.create_unwind_info} method described above to
+create a @code{gdb.UnwindInfo} instance. Use the following method to
+specify caller registers that have been saved in this frame:
+
+@defun gdb.UnwindInfo.add_saved_register (reg, value)
+@var{reg} identifies the register. It can be a number or a name, just
+as for the @code{PendingFrame.read_register} method above.
+@var{value} is a register value (a @code{gdb.Value} object).
+@end defun
+
+@subheading Unwinder Skeleton Code
+
+@value{GDBN} comes with the module containing the base @code{Unwinder}
+class. Derive your unwinder class from it and structure the code as
+follows:
+
+@smallexample
+from gdb.unwinders import Unwinder
+
+class FrameId(object):
+ def __init__(self, sp, pc):
+ self.sp = sp
+ self.pc = pc
+
+
+class MyUnwinder(Unwinder):
+ def __init__(....):
+ supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
+
+ def __call__(pending_frame):
+ if not <we recognize frame>:
+ return None
+ # Create UnwindInfo. Usually the frame is identified by the stack
+ # pointer and the program counter.
+ sp = pending_frame.read_register(<SP number>)
+ pc = pending_frame.read_register(<PC number>)
+ unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
+
+ # Find the values of the registers in the caller's frame and
+ # save them in the result:
+ unwind_info.add_saved_register(<register>, <value>)
+ ....
+
+ # Return the result:
+ return unwind_info
+
+@end smallexample
+
+@subheading Registering a Unwinder
+
+An object file, a program space, and the @value{GDBN} proper can have
+unwinders registered with it.
+
+The @code{gdb.unwinders} module provides the function to register a
+unwinder:
+
+@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
+@var{locus} is specifies an object file or a program space to which
+@var{unwinder} is added. Passing @code{None} or @code{gdb} adds
+@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
+added @var{unwinder} will be called before any other unwinder from the
+same locus. Two unwinders in the same locus cannot have the same
+name. An attempt to add a unwinder with already existing name raises
+an exception unless @var{replace} is @code{True}, in which case the
+old unwinder is deleted.
+@end defun
+
+@subheading Unwinder Precedence
+
+@value{GDBN} first calls the unwinders from all the object files in no
+particular order, then the unwinders from the current program space,
+and finally the unwinders from @value{GDBN}.
+
+@node Xmethods In Python
+@subsubsection Xmethods In Python
+@cindex xmethods in Python
+
+@dfn{Xmethods} are additional methods or replacements for existing
+methods of a C@t{++} class. This feature is useful for those cases
+where a method defined in C@t{++} source code could be inlined or
+optimized out by the compiler, making it unavailable to @value{GDBN}.
+For such cases, one can define an xmethod to serve as a replacement
+for the method defined in the C@t{++} source code. @value{GDBN} will
+then invoke the xmethod, instead of the C@t{++} method, to
+evaluate expressions. One can also use xmethods when debugging
+with core files. Moreover, when debugging live programs, invoking an
+xmethod need not involve running the inferior (which can potentially
+perturb its state). Hence, even if the C@t{++} method is available, it
+is better to use its replacement xmethod if one is defined.
+
+The xmethods feature in Python is available via the concepts of an
+@dfn{xmethod matcher} and an @dfn{xmethod worker}. To
+implement an xmethod, one has to implement a matcher and a
+corresponding worker for it (more than one worker can be
+implemented, each catering to a different overloaded instance of the
+method). Internally, @value{GDBN} invokes the @code{match} method of a
+matcher to match the class type and method name. On a match, the
+@code{match} method returns a list of matching @emph{worker} objects.
+Each worker object typically corresponds to an overloaded instance of
+the xmethod. They implement a @code{get_arg_types} method which
+returns a sequence of types corresponding to the arguments the xmethod
+requires. @value{GDBN} uses this sequence of types to perform
+overload resolution and picks a winning xmethod worker. A winner
+is also selected from among the methods @value{GDBN} finds in the
+C@t{++} source code. Next, the winning xmethod worker and the
+winning C@t{++} method are compared to select an overall winner. In
+case of a tie between a xmethod worker and a C@t{++} method, the
+xmethod worker is selected as the winner. That is, if a winning
+xmethod worker is found to be equivalent to the winning C@t{++}
+method, then the xmethod worker is treated as a replacement for
+the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
+method. If the winning xmethod worker is the overall winner, then
+the corresponding xmethod is invoked via the @code{__call__} method
+of the worker object.
+
+If one wants to implement an xmethod as a replacement for an
+existing C@t{++} method, then they have to implement an equivalent
+xmethod which has exactly the same name and takes arguments of
+exactly the same type as the C@t{++} method. If the user wants to
+invoke the C@t{++} method even though a replacement xmethod is
+available for that method, then they can disable the xmethod.
+
+@xref{Xmethod API}, for API to implement xmethods in Python.
+@xref{Writing an Xmethod}, for implementing xmethods in Python.
+
+@node Xmethod API
+@subsubsection Xmethod API
+@cindex xmethod API
+
+The @value{GDBN} Python API provides classes, interfaces and functions
+to implement, register and manipulate xmethods.
+@xref{Xmethods In Python}.
+
+An xmethod matcher should be an instance of a class derived from
+@code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
+object with similar interface and attributes. An instance of
+@code{XMethodMatcher} has the following attributes:
+
+@defvar name
+The name of the matcher.
+@end defvar
+
+@defvar enabled
+A boolean value indicating whether the matcher is enabled or disabled.
+@end defvar
+
+@defvar methods
+A list of named methods managed by the matcher. Each object in the list
+is an instance of the class @code{XMethod} defined in the module
+@code{gdb.xmethod}, or any object with the following attributes:
+
+@table @code
+
+@item name
+Name of the xmethod which should be unique for each xmethod
+managed by the matcher.
+
+@item enabled
+A boolean value indicating whether the xmethod is enabled or
+disabled.
+
+@end table
+
+The class @code{XMethod} is a convenience class with same
+attributes as above along with the following constructor:
+
+@defun XMethod.__init__ (self, name)
+Constructs an enabled xmethod with name @var{name}.
+@end defun
+@end defvar
+
+@noindent
+The @code{XMethodMatcher} class has the following methods:
+
+@defun XMethodMatcher.__init__ (self, name)
+Constructs an enabled xmethod matcher with name @var{name}. The
+@code{methods} attribute is initialized to @code{None}.
+@end defun
+
+@defun XMethodMatcher.match (self, class_type, method_name)
+Derived classes should override this method. It should return a
+xmethod worker object (or a sequence of xmethod worker
+objects) matching the @var{class_type} and @var{method_name}.
+@var{class_type} is a @code{gdb.Type} object, and @var{method_name}
+is a string value. If the matcher manages named methods as listed in
+its @code{methods} attribute, then only those worker objects whose
+corresponding entries in the @code{methods} list are enabled should be
+returned.
+@end defun
+
+An xmethod worker should be an instance of a class derived from
+@code{XMethodWorker} defined in the module @code{gdb.xmethod},
+or support the following interface:
+
+@defun XMethodWorker.get_arg_types (self)
+This method returns a sequence of @code{gdb.Type} objects corresponding
+to the arguments that the xmethod takes. It can return an empty
+sequence or @code{None} if the xmethod does not take any arguments.
+If the xmethod takes a single argument, then a single
+@code{gdb.Type} object corresponding to it can be returned.
+@end defun
+
+@defun XMethodWorker.get_result_type (self, *args)
+This method returns a @code{gdb.Type} object representing the type
+of the result of invoking this xmethod.
+The @var{args} argument is the same tuple of arguments that would be
+passed to the @code{__call__} method of this worker.
+@end defun
+
+@defun XMethodWorker.__call__ (self, *args)
+This is the method which does the @emph{work} of the xmethod. The
+@var{args} arguments is the tuple of arguments to the xmethod. Each
+element in this tuple is a gdb.Value object. The first element is
+always the @code{this} pointer value.
+@end defun
+
+For @value{GDBN} to lookup xmethods, the xmethod matchers
+should be registered using the following function defined in the module
+@code{gdb.xmethod}:
+
+@defun register_xmethod_matcher (locus, matcher, replace=False)
+The @code{matcher} is registered with @code{locus}, replacing an
+existing matcher with the same name as @code{matcher} if
+@code{replace} is @code{True}. @code{locus} can be a
+@code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
+@code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
+@code{None}. If it is @code{None}, then @code{matcher} is registered
+globally.
+@end defun
+
+@node Writing an Xmethod
+@subsubsection Writing an Xmethod
+@cindex writing xmethods in Python
+
+Implementing xmethods in Python will require implementing xmethod
+matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
+the following C@t{++} class:
+
+@smallexample
+class MyClass
+@{
+public:
+ MyClass (int a) : a_(a) @{ @}
+
+ int geta (void) @{ return a_; @}
+ int operator+ (int b);
+
+private:
+ int a_;
+@};
+
+int
+MyClass::operator+ (int b)
+@{
+ return a_ + b;
+@}
+@end smallexample
+
+@noindent
+Let us define two xmethods for the class @code{MyClass}, one
+replacing the method @code{geta}, and another adding an overloaded
+flavor of @code{operator+} which takes a @code{MyClass} argument (the
+C@t{++} code above already has an overloaded @code{operator+}
+which takes an @code{int} argument). The xmethod matcher can be
+defined as follows:
+
+@smallexample
+class MyClass_geta(gdb.xmethod.XMethod):
+ def __init__(self):
+ gdb.xmethod.XMethod.__init__(self, 'geta')
+
+ def get_worker(self, method_name):
+ if method_name == 'geta':
+ return MyClassWorker_geta()
+
+
+class MyClass_sum(gdb.xmethod.XMethod):
+ def __init__(self):
+ gdb.xmethod.XMethod.__init__(self, 'sum')
+
+ def get_worker(self, method_name):
+ if method_name == 'operator+':
+ return MyClassWorker_plus()
+
+
+class MyClassMatcher(gdb.xmethod.XMethodMatcher):
+ def __init__(self):
+ gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
+ # List of methods 'managed' by this matcher
+ self.methods = [MyClass_geta(), MyClass_sum()]
+
+ def match(self, class_type, method_name):
+ if class_type.tag != 'MyClass':
+ return None
+ workers = []
+ for method in self.methods:
+ if method.enabled:
+ worker = method.get_worker(method_name)
+ if worker:
+ workers.append(worker)
+
+ return workers
+@end smallexample
+
+@noindent
+Notice that the @code{match} method of @code{MyClassMatcher} returns
+a worker object of type @code{MyClassWorker_geta} for the @code{geta}
+method, and a worker object of type @code{MyClassWorker_plus} for the
+@code{operator+} method. This is done indirectly via helper classes
+derived from @code{gdb.xmethod.XMethod}. One does not need to use the
+@code{methods} attribute in a matcher as it is optional. However, if a
+matcher manages more than one xmethod, it is a good practice to list the
+xmethods in the @code{methods} attribute of the matcher. This will then
+facilitate enabling and disabling individual xmethods via the
+@code{enable/disable} commands. Notice also that a worker object is
+returned only if the corresponding entry in the @code{methods} attribute
+of the matcher is enabled.
+
+The implementation of the worker classes returned by the matcher setup
+above is as follows:
+
+@smallexample
+class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
+ def get_arg_types(self):
+ return None
+
+ def get_result_type(self, obj):
+ return gdb.lookup_type('int')
+
+ def __call__(self, obj):
+ return obj['a_']
+
+
+class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
+ def get_arg_types(self):
+ return gdb.lookup_type('MyClass')
+
+ def get_result_type(self, obj):
+ return gdb.lookup_type('int')
+
+ def __call__(self, obj, other):
+ return obj['a_'] + other['a_']
+@end smallexample
+
+For @value{GDBN} to actually lookup a xmethod, it has to be
+registered with it. The matcher defined above is registered with
+@value{GDBN} globally as follows:
+
+@smallexample
+gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
+@end smallexample
+
+If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
+code as follows:
+
+@smallexample
+MyClass obj(5);
+@end smallexample
+
+@noindent
+then, after loading the Python script defining the xmethod matchers
+and workers into @code{GDBN}, invoking the method @code{geta} or using
+the operator @code{+} on @code{obj} will invoke the xmethods
+defined above:
+
+@smallexample
+(gdb) p obj.geta()
+$1 = 5
+
+(gdb) p obj + obj
+$2 = 10
+@end smallexample
+
+Consider another example with a C++ template class:
+
+@smallexample
+template <class T>
+class MyTemplate
+@{
+public:
+ MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
+ ~MyTemplate () @{ delete [] data_; @}
+
+ int footprint (void)
+ @{
+ return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
+ @}
+
+private:
+ int dsize_;
+ T *data_;
+@};
+@end smallexample
+
+Let us implement an xmethod for the above class which serves as a
+replacement for the @code{footprint} method. The full code listing
+of the xmethod workers and xmethod matchers is as follows:
+
+@smallexample
+class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
+ def __init__(self, class_type):
+ self.class_type = class_type
+
+ def get_arg_types(self):
+ return None
+
+ def get_result_type(self):
+ return gdb.lookup_type('int')
+
+ def __call__(self, obj):
+ return (self.class_type.sizeof +
+ obj['dsize_'] *
+ self.class_type.template_argument(0).sizeof)
+
+
+class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
+ def __init__(self):
+ gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
+
+ def match(self, class_type, method_name):
+ if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
+ class_type.tag) and
+ method_name == 'footprint'):
+ return MyTemplateWorker_footprint(class_type)
+@end smallexample
+
+Notice that, in this example, we have not used the @code{methods}
+attribute of the matcher as the matcher manages only one xmethod. The
+user can enable/disable this xmethod by enabling/disabling the matcher
+itself.
+
@node Inferiors In Python
@subsubsection Inferiors In Python
@cindex inferiors in Python
@findex Inferior.read_memory
@defun Inferior.read_memory (address, length)
-Read @var{length} bytes of memory from the inferior, starting at
+Read @var{length} addressable memory units from the inferior, starting at
@var{address}. Returns a buffer object, which behaves much like an array
or a string. It can be modified and given to the
@code{Inferior.write_memory} function. In @code{Python} 3, the return
@var{address}. The @var{buffer} parameter must be a Python object
which supports the buffer protocol, i.e., a string, an array or the
object returned from @code{Inferior.read_memory}. If given, @var{length}
-determines the number of bytes from @var{buffer} to be written.
+determines the number of addressable memory units from @var{buffer} to be
+written.
@end defun
@findex gdb.search_memory
@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
@end defvar
+@item events.clear_objfiles
+Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
+files for a program space has been reset.
+@code{gdb.ClearObjFilesEvent} has one attribute:
+
+@defvar ClearObjFilesEvent.progspace
+A reference to the program space (@code{gdb.Progspace}) whose objfile list has
+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.
+
+@defvar InferiorCallPreEvent.ptid
+The thread in which the call will be run.
+@end defvar
+
+@defvar InferiorCallPreEvent.address
+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.
+
+@defvar InferiorCallPostEvent.ptid
+The thread in which the call was run.
+@end defvar
+
+@defvar InferiorCallPostEvent.address
+The location of the function that was called.
+@end defvar
+
+@item events.memory_changed
+Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
+inferior has been modified by the @value{GDBN} user, for instance via a
+command like @w{@code{set *addr = value}}. The event has the following
+attributes:
+
+@defvar MemoryChangedEvent.address
+The start address of the changed region.
+@end defvar
+
+@defvar MemoryChangedEvent.length
+Length in bytes of the changed region.
+@end defvar
+
+@item events.register_changed
+Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
+inferior has been modified by the @value{GDBN} user.
+
+@defvar RegisterChangedEvent.frame
+A gdb.Frame object representing the frame in which the register was modified.
+@end defvar
+@defvar RegisterChangedEvent.regnum
+Denotes which register was modified.
+@end defvar
+
@end table
@node Threads In Python
@end defvar
@defvar InferiorThread.num
-ID of the thread, as assigned by GDB.
+The per-inferior number of the thread, as assigned by GDB.
@end defvar
@defvar InferiorThread.ptid
does not use that identifier.
@end defvar
+@defvar InferiorThread.inferior
+The inferior this thread belongs to. This attribute is represented as
+a @code{gdb.Inferior} object. This attribute is not writable.
+@end defvar
+
A @code{gdb.InferiorThread} object has the following methods:
@defun InferiorThread.is_valid ()
(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
complete}).
-The arguments @var{text} and @var{word} are both strings. @var{text}
-holds the complete command line up to the cursor's location.
+The arguments @var{text} and @var{word} are both strings; @var{text}
+holds the complete command line up to the cursor's location, while
@var{word} holds the last word of the command line; this is computed
using a word-breaking heuristic.
from the @code{complete} method. These predefined completion
constants are all defined in the @code{gdb} module:
-@table @code
-@findex COMPLETE_NONE
-@findex gdb.COMPLETE_NONE
+@vtable @code
+@vindex COMPLETE_NONE
@item gdb.COMPLETE_NONE
This constant means that no completion should be done.
-@findex COMPLETE_FILENAME
-@findex gdb.COMPLETE_FILENAME
+@vindex COMPLETE_FILENAME
@item gdb.COMPLETE_FILENAME
This constant means that filename completion should be performed.
-@findex COMPLETE_LOCATION
-@findex gdb.COMPLETE_LOCATION
+@vindex COMPLETE_LOCATION
@item gdb.COMPLETE_LOCATION
This constant means that location completion should be done.
@xref{Specify Location}.
-@findex COMPLETE_COMMAND
-@findex gdb.COMPLETE_COMMAND
+@vindex COMPLETE_COMMAND
@item gdb.COMPLETE_COMMAND
This constant means that completion should examine @value{GDBN}
command names.
-@findex COMPLETE_SYMBOL
-@findex gdb.COMPLETE_SYMBOL
+@vindex COMPLETE_SYMBOL
@item gdb.COMPLETE_SYMBOL
This constant means that completion should be done using symbol names
as the source.
-@findex COMPLETE_EXPRESSION
-@findex gdb.COMPLETE_EXPRESSION
+@vindex COMPLETE_EXPRESSION
@item gdb.COMPLETE_EXPRESSION
This constant means that completion should be done on expressions.
Often this means completing on symbol names, but some language
parsers also have support for completing on field names.
-@end table
+@end vtable
The following code snippet shows how a trivial CLI command can be
implemented in Python:
objects. @xref{Frame Filter API}, for more information.
@end defvar
+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
+associated with the program space.
+
+In this contrived example, we want to perform some processing when
+an objfile with a certain symbol is loaded, but we only want to do
+this once because it is expensive. To achieve this we record the results
+with the program space because we can't predict when the desired objfile
+will be loaded.
+
+@smallexample
+(gdb) python
+def clear_objfiles_handler(event):
+ event.progspace.expensive_computation = None
+def expensive(symbol):
+ """A mock routine to perform an "expensive" computation on symbol."""
+ print "Computing the answer to the ultimate question ..."
+ return 42
+def new_objfile_handler(event):
+ objfile = event.new_objfile
+ progspace = objfile.progspace
+ if not hasattr(progspace, 'expensive_computation') or \
+ progspace.expensive_computation is None:
+ # We use 'main' for the symbol to keep the example simple.
+ # Note: There's no current way to constrain the lookup
+ # to one objfile.
+ symbol = gdb.lookup_global_symbol('main')
+ if symbol is not None:
+ progspace.expensive_computation = expensive(symbol)
+gdb.events.clear_objfiles.connect(clear_objfiles_handler)
+gdb.events.new_objfile.connect(new_objfile_handler)
+end
+(gdb) file /tmp/hello
+Reading symbols from /tmp/hello...done.
+Computing the answer to the ultimate question ...
+(gdb) python print gdb.current_progspace().expensive_computation
+42
+(gdb) run
+Starting program: /tmp/hello
+Hello.
+[Inferior 1 (process 4242) exited normally]
+@end smallexample
+
@node Objfiles In Python
@subsubsection Objfiles In Python
@xref{Objfiles In Python}.
@end defun
+@findex gdb.lookup_objfile
+@defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
+Look up @var{name}, a file name or build ID, in the list of objfiles
+for the current program space (@pxref{Progspaces In Python}).
+If the objfile is not found throw the Python @code{ValueError} exception.
+
+If @var{name} is a relative file name, then it will match any
+source file name with the same trailing components. For example, if
+@var{name} is @samp{gcc/expr.c}, then it will match source file
+name of @file{/build/trunk/gcc/expr.c}, but not
+@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
+
+If @var{by_build_id} is provided and is @code{True} then @var{name}
+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}
+command-line option in @ref{Options, , Command Line Options, ld.info,
+The GNU Linker}.
+@end defun
+
Each objfile is represented by an instance of the @code{gdb.Objfile}
class.
@defvar Objfile.filename
-The file name of the objfile as a string.
+The file name of the objfile as a string, with symbolic links resolved.
+
+The value is @code{None} if the objfile is no longer valid.
+See the @code{gdb.Objfile.is_valid} method, described below.
+@end defvar
+
+@defvar Objfile.username
+The file name of the objfile as specified by the user as a string.
+
+The value is @code{None} if the objfile is no longer valid.
+See the @code{gdb.Objfile.is_valid} method, described below.
+@end defvar
+
+@defvar Objfile.owner
+For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
+object that debug info is being provided for.
+Otherwise this is @code{None}.
+Separate debug info objfiles are added with the
+@code{gdb.Objfile.add_separate_debug_file} method, described below.
+@end defvar
+
+@defvar Objfile.build_id
+The build ID of the objfile as a string.
+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}
+command-line option in @ref{Options, , Command Line Options, ld.info,
+The GNU Linker}.
+@end defvar
+
+@defvar Objfile.progspace
+The containing program space of the objfile as a @code{gdb.Progspace}
+object. @xref{Progspaces In Python}.
@end defvar
@defvar Objfile.pretty_printers
objects. @xref{Frame Filter API}, for more information.
@end defvar
+One may add arbitrary attributes to @code{gdb.Objfile} objects
+in the usual Python way.
+This is useful if, for example, one needs to do some extra record keeping
+associated with the objfile.
+
+In this contrived example we record the time when @value{GDBN}
+loaded the objfile.
+
+@smallexample
+(gdb) python
+import datetime
+def new_objfile_handler(event):
+ # Set the time_loaded attribute of the new objfile.
+ event.new_objfile.time_loaded = datetime.datetime.today()
+gdb.events.new_objfile.connect(new_objfile_handler)
+end
+(gdb) file ./hello
+Reading symbols from ./hello...done.
+(gdb) python print gdb.objfiles()[0].time_loaded
+2014-10-09 11:41:36.770345
+@end smallexample
+
A @code{gdb.Objfile} object has the following methods:
@defun Objfile.is_valid ()
if it is invalid at the time the method is called.
@end defun
+@defun Objfile.add_separate_debug_file (file)
+Add @var{file} to the list of files that @value{GDBN} will search for
+debug information for the objfile.
+This is useful when the debug info has been removed from the program
+and stored in a separate file. @value{GDBN} has built-in support for
+finding separate debug info files (@pxref{Separate Debug Files}), but if
+the file doesn't live in one of the standard places that @value{GDBN}
+searches then this function can be used to add a debug info file
+from a different place.
+@end defun
+
@node Frames In Python
@subsubsection Accessing inferior stack frames from Python.
The frame unwinder did not find any saved PC, but we needed
one to unwind further.
+@item gdb.FRAME_UNWIND_MEMORY_ERROR
+The frame unwinder caused an error while trying to access memory.
+
@item gdb.FRAME_UNWIND_FIRST_ERROR
Any stop reason greater or equal to this value indicates some kind
of error. This special value facilitates writing code that tests
@xref{Symbol Tables In Python}.
@end defun
+@defun Frame.read_register (register)
+Return the value of @var{register} in this frame. The @var{register}
+argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
+Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
+does not exist.
+@end defun
+
@defun Frame.read_var (variable @r{[}, block@r{]})
Return the value of @var{variable} in this frame. If the optional
argument @var{block} is provided, search for the variable from that
block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter). @var{variable}
-must be a string or a @code{gdb.Symbol} object. @var{block} must be a
+determined by the frame's current program counter). The @var{variable}
+argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
@code{gdb.Block} object.
@end defun
The available domain categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module:
-@table @code
-@findex SYMBOL_UNDEF_DOMAIN
-@findex gdb.SYMBOL_UNDEF_DOMAIN
+@vtable @code
+@vindex SYMBOL_UNDEF_DOMAIN
@item gdb.SYMBOL_UNDEF_DOMAIN
This is used when a domain has not been discovered or none of the
following domains apply. This usually indicates an error either
in the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_VAR_DOMAIN
-@findex gdb.SYMBOL_VAR_DOMAIN
+
+@vindex SYMBOL_VAR_DOMAIN
@item gdb.SYMBOL_VAR_DOMAIN
This domain contains variables, function names, typedef names and enum
type values.
-@findex SYMBOL_STRUCT_DOMAIN
-@findex gdb.SYMBOL_STRUCT_DOMAIN
+
+@vindex SYMBOL_STRUCT_DOMAIN
@item gdb.SYMBOL_STRUCT_DOMAIN
This domain holds struct, union and enum type names.
-@findex SYMBOL_LABEL_DOMAIN
-@findex gdb.SYMBOL_LABEL_DOMAIN
+
+@vindex SYMBOL_LABEL_DOMAIN
@item gdb.SYMBOL_LABEL_DOMAIN
This domain contains names of labels (for gotos).
-@findex SYMBOL_VARIABLES_DOMAIN
-@findex gdb.SYMBOL_VARIABLES_DOMAIN
+
+@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.
-@findex SYMBOL_FUNCTIONS_DOMAIN
-@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
+
+@vindex SYMBOL_FUNCTIONS_DOMAIN
@item gdb.SYMBOL_FUNCTION_DOMAIN
This domain contains all functions.
-@findex SYMBOL_TYPES_DOMAIN
-@findex gdb.SYMBOL_TYPES_DOMAIN
+
+@vindex SYMBOL_TYPES_DOMAIN
@item gdb.SYMBOL_TYPES_DOMAIN
This domain contains all types.
-@end table
+@end vtable
The available address class categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module:
-@table @code
-@findex SYMBOL_LOC_UNDEF
-@findex gdb.SYMBOL_LOC_UNDEF
+@vtable @code
+@vindex SYMBOL_LOC_UNDEF
@item gdb.SYMBOL_LOC_UNDEF
If this is returned by address class, it indicates an error either in
the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_LOC_CONST
-@findex gdb.SYMBOL_LOC_CONST
+
+@vindex SYMBOL_LOC_CONST
@item gdb.SYMBOL_LOC_CONST
Value is constant int.
-@findex SYMBOL_LOC_STATIC
-@findex gdb.SYMBOL_LOC_STATIC
+
+@vindex SYMBOL_LOC_STATIC
@item gdb.SYMBOL_LOC_STATIC
Value is at a fixed address.
-@findex SYMBOL_LOC_REGISTER
-@findex gdb.SYMBOL_LOC_REGISTER
+
+@vindex SYMBOL_LOC_REGISTER
@item gdb.SYMBOL_LOC_REGISTER
Value is in a register.
-@findex SYMBOL_LOC_ARG
-@findex gdb.SYMBOL_LOC_ARG
+
+@vindex SYMBOL_LOC_ARG
@item gdb.SYMBOL_LOC_ARG
Value is an argument. This value is at the offset stored within the
symbol inside the frame's argument list.
-@findex SYMBOL_LOC_REF_ARG
-@findex gdb.SYMBOL_LOC_REF_ARG
+
+@vindex SYMBOL_LOC_REF_ARG
@item gdb.SYMBOL_LOC_REF_ARG
Value address is stored in the frame's argument list. Just like
@code{LOC_ARG} except that the value's address is stored at the
offset, not the value itself.
-@findex SYMBOL_LOC_REGPARM_ADDR
-@findex gdb.SYMBOL_LOC_REGPARM_ADDR
+
+@vindex SYMBOL_LOC_REGPARM_ADDR
@item gdb.SYMBOL_LOC_REGPARM_ADDR
Value is a specified register. Just like @code{LOC_REGISTER} except
the register holds the address of the argument instead of the argument
itself.
-@findex SYMBOL_LOC_LOCAL
-@findex gdb.SYMBOL_LOC_LOCAL
+
+@vindex SYMBOL_LOC_LOCAL
@item gdb.SYMBOL_LOC_LOCAL
Value is a local variable.
-@findex SYMBOL_LOC_TYPEDEF
-@findex gdb.SYMBOL_LOC_TYPEDEF
+
+@vindex SYMBOL_LOC_TYPEDEF
@item gdb.SYMBOL_LOC_TYPEDEF
Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
have this class.
-@findex SYMBOL_LOC_BLOCK
-@findex gdb.SYMBOL_LOC_BLOCK
+
+@vindex SYMBOL_LOC_BLOCK
@item gdb.SYMBOL_LOC_BLOCK
Value is a block.
-@findex SYMBOL_LOC_CONST_BYTES
-@findex gdb.SYMBOL_LOC_CONST_BYTES
+
+@vindex SYMBOL_LOC_CONST_BYTES
@item gdb.SYMBOL_LOC_CONST_BYTES
Value is a byte-sequence.
-@findex SYMBOL_LOC_UNRESOLVED
-@findex gdb.SYMBOL_LOC_UNRESOLVED
+
+@vindex SYMBOL_LOC_UNRESOLVED
@item gdb.SYMBOL_LOC_UNRESOLVED
Value is at a fixed address, but the address of the variable has to be
determined from the minimal symbol table whenever the variable is
referenced.
-@findex SYMBOL_LOC_OPTIMIZED_OUT
-@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
+
+@vindex SYMBOL_LOC_OPTIMIZED_OUT
@item gdb.SYMBOL_LOC_OPTIMIZED_OUT
The value does not actually exist in the program.
-@findex SYMBOL_LOC_COMPUTED
-@findex gdb.SYMBOL_LOC_COMPUTED
+
+@vindex SYMBOL_LOC_COMPUTED
@item gdb.SYMBOL_LOC_COMPUTED
The value's address is a computed location.
-@end table
+@end vtable
@node Symbol Tables In Python
@subsubsection Symbol table representation in Python.
This attribute is not writable.
@end defvar
+@defvar Symtab.producer
+The name and possibly version number of the program that
+compiled the code in the symbol table.
+The contents of this string is up to the compiler.
+If no producer information is available then @code{None} is returned.
+This attribute is not writable.
+@end defvar
+
A @code{gdb.Symtab} object has the following methods:
@defun Symtab.is_valid ()
@defun LineTable.line (line)
Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
-entries in the line table for the given @var{line}. @var{line} refers
-to the source code line. If there are no entries for that source code
+entries in the line table for the given @var{line}, which specifies
+the source code line. If there are no entries for that source code
@var{line}, the Python @code{None} is returned.
@end defun
class.
@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
-Create a new breakpoint. @var{spec} is a string naming the location
-of the breakpoint, or an expression that defines a watchpoint. The
-contents can be any location recognized by the @code{break} command,
-or in the case of a watchpoint, by the @code{watch} command. The
-optional @var{type} denotes the breakpoint to create from the types
-defined later in this chapter. This argument can be either:
-@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
+Create a new breakpoint according to @var{spec}, which is a string
+naming the location of the breakpoint, or an expression that defines a
+watchpoint. The contents can be any location recognized by the
+@code{break} command, or in the case of a watchpoint, by the
+@code{watch} command. The optional @var{type} denotes the breakpoint
+to create from the types defined later in this chapter. This argument
+can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}; it
defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
argument allows the breakpoint to become invisible to the user. The
breakpoint will neither be reported when created, nor will it be
The available watchpoint types represented by constants are defined in the
@code{gdb} module:
-@table @code
-@findex WP_READ
-@findex gdb.WP_READ
+@vtable @code
+@vindex WP_READ
@item gdb.WP_READ
Read only watchpoint.
-@findex WP_WRITE
-@findex gdb.WP_WRITE
+@vindex WP_WRITE
@item gdb.WP_WRITE
Write only watchpoint.
-@findex WP_ACCESS
-@findex gdb.WP_ACCESS
+@vindex WP_ACCESS
@item gdb.WP_ACCESS
Read/Write watchpoint.
-@end table
+@end vtable
@defun Breakpoint.is_valid ()
Return @code{True} if this @code{Breakpoint} object is valid,
inferior leaves the scope of that watchpoint.
@end defun
-@defun Breakpoint.delete
+@defun Breakpoint.delete ()
Permanently deletes the @value{GDBN} breakpoint. This also
invalidates the Python @code{Breakpoint} object. Any further access
to this object's attributes or methods will raise an error.
@defvar Breakpoint.enabled
This attribute is @code{True} if the breakpoint is enabled, and
-@code{False} otherwise. This attribute is writable.
+@code{False} otherwise. This attribute is writable. You can use it to enable
+or disable the breakpoint.
@end defvar
@defvar Breakpoint.silent
@end defvar
@defvar Breakpoint.thread
-If the breakpoint is thread-specific, this attribute holds the thread
-id. If the breakpoint is not thread-specific, this attribute is
-@code{None}. This attribute is writable.
+If the breakpoint is thread-specific, this attribute holds the
+thread's global id. If the breakpoint is not thread-specific, this
+attribute is @code{None}. This attribute is writable.
@end defvar
@defvar Breakpoint.task
The available types are represented by constants defined in the @code{gdb}
module:
-@table @code
-@findex BP_BREAKPOINT
-@findex gdb.BP_BREAKPOINT
+@vtable @code
+@vindex BP_BREAKPOINT
@item gdb.BP_BREAKPOINT
Normal code breakpoint.
-@findex BP_WATCHPOINT
-@findex gdb.BP_WATCHPOINT
+@vindex BP_WATCHPOINT
@item gdb.BP_WATCHPOINT
Watchpoint breakpoint.
-@findex BP_HARDWARE_WATCHPOINT
-@findex gdb.BP_HARDWARE_WATCHPOINT
+@vindex BP_HARDWARE_WATCHPOINT
@item gdb.BP_HARDWARE_WATCHPOINT
Hardware assisted watchpoint.
-@findex BP_READ_WATCHPOINT
-@findex gdb.BP_READ_WATCHPOINT
+@vindex BP_READ_WATCHPOINT
@item gdb.BP_READ_WATCHPOINT
Hardware assisted read watchpoint.
-@findex BP_ACCESS_WATCHPOINT
-@findex gdb.BP_ACCESS_WATCHPOINT
+@vindex BP_ACCESS_WATCHPOINT
@item gdb.BP_ACCESS_WATCHPOINT
Hardware assisted access watchpoint.
-@end table
+@end vtable
@defvar Breakpoint.hit_count
This attribute holds the hit count for the breakpoint, an integer.
Print the list of all Python scripts that @value{GDBN} auto-loaded.
Also printed is the list of Python scripts that were mentioned in
-the @code{.debug_gdb_scripts} section and were not found
-(@pxref{dotdebug_gdb_scripts section}).
+the @code{.debug_gdb_scripts} section and were either not found
+(@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
+@code{auto-load safe-path} rejection (@pxref{Auto-loading}).
This is useful because their names are not printed when @value{GDBN}
tries to load them and fails. There may be many of them, and printing
an error message for each one is problematic.
@end smallexample
@end table
-When reading an auto-loaded file, @value{GDBN} sets the
+When reading an auto-loaded file or script, @value{GDBN} sets the
@dfn{current objfile}. This is available via the @code{gdb.current_objfile}
function (@pxref{Objfiles In Python}). This can be useful for
registering objfile-specific pretty-printers and frame-filters.
A pretty-printer which handles printing of @code{enum} values. Unlike
@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
work properly when there is some overlap between the enumeration
-constants. @var{name} is the name of the printer and also the name of
-the @code{enum} type to look up.
+constants. The argument @var{name} is the name of the printer and
+also the name of the @code{enum} type to look up.
@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
Register @var{printer} with the pretty-printer list of @var{obj}.
API}).
@item register_type_printer (locus, printer)
-This is a convenience function to register a type printer.
-@var{printer} is the type printer to register. It must implement the
-type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
-which case the printer is registered with that objfile; a
-@code{gdb.Progspace}, in which case the printer is registered with
-that progspace; or @code{None}, in which case the printer is
-registered globally.
+This is a convenience function to register a type printer
+@var{printer}. The printer must implement the type printer protocol.
+The @var{locus} argument is either a @code{gdb.Objfile}, in which case
+the printer is registered with that objfile; a @code{gdb.Progspace},
+in which case the printer is registered with that progspace; or
+@code{None}, in which case the printer is registered globally.
@item TypePrinter
This is a base class that implements the type printer protocol. Type
projects / deliverable / binutils-gdb.git / blobdiff