-@c Copyright (C) 2008-2014 Free Software Foundation, Inc.
+@c Copyright (C) 2008-2018 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.
+* Recordings In Python:: Accessing recordings from Python.
* Commands In Python:: Implementing new commands in Python.
* Parameters In Python:: Adding new @value{GDBN} parameters.
* Functions In Python:: Writing new convenience functions.
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}.
@findex gdb.breakpoints
@defun gdb.breakpoints ()
Return a sequence holding all of @value{GDBN}'s breakpoints.
-@xref{Breakpoints In Python}, for more information.
+@xref{Breakpoints In Python}, for more information. In @value{GDBN}
+version 7.11 and earlier, this function returned @code{None} if there
+were no breakpoints. This peculiarity was subsequently fixed, and now
+@code{gdb.breakpoints} returns an empty sequence in this case.
+@end defun
+
+@defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
+Return a Python list holding a collection of newly set
+@code{gdb.Breakpoint} objects matching function names defined by the
+@var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
+system functions (those not explicitly defined in the inferior) will
+also be included in the match. The @var{throttle} keyword takes an
+integer that defines the maximum number of pattern matches for
+functions matched by the @var{regex} pattern. If the number of
+matches exceeds the integer value of @var{throttle}, a
+@code{RuntimeError} will be raised and no breakpoints will be created.
+If @var{throttle} is not defined then there is no imposed limit on the
+maximum number of matches and breakpoints to be created. The
+@var{symtabs} keyword takes a Python iterable that yields a collection
+of @code{gdb.Symtab} objects and will restrict the search to those
+functions only contained within the @code{gdb.Symtab} objects.
@end defun
@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
@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} 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
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
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.
@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.
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.
@table @code
@item bitpos
This attribute is not available for @code{enum} or @code{static}
-(as in C@t{++} or Java) fields. The value is the position, counting
+(as in C@t{++}) fields. The value is the position, counting
in bits, from the start of the containing type.
@item enumval
@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
@vindex TYPE_CODE_METHOD
@item gdb.TYPE_CODE_METHOD
-A method type, as found in C@t{++} or Java.
+A method type, as found in C@t{++}.
@vindex TYPE_CODE_METHODPTR
@item gdb.TYPE_CODE_METHODPTR
@item gdb.TYPE_CODE_REF
A reference type.
+@vindex TYPE_CODE_RVALUE_REF
+@item gdb.TYPE_CODE_RVALUE_REF
+A C@t{++}11 rvalue reference type.
+
@vindex TYPE_CODE_CHAR
@item gdb.TYPE_CODE_CHAR
A character type.
@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
+@code{Inferior.write_memory} function. In Python 3, the return
value is a @code{memoryview} object.
@end defun
@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
the pattern could not be found.
@end defun
+@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
+library specific data structure such as @code{pthread_t} for pthreads
+library implementations.
+@end defun
+
@node Events In Python
@subsubsection Events In Python
@cindex inferior events in Python
@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
the attribute does not exist.
@end defvar
-@defvar ExitedEvent inferior
+@defvar ExitedEvent.inferior
A reference to the inferior which triggered the @code{exited} event.
@end defvar
@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
+
+@item events.breakpoint_created
+This is emitted when a new breakpoint has been created. The argument
+that is passed is the new @code{gdb.Breakpoint} object.
+
+@item events.breakpoint_modified
+This is emitted when a breakpoint has been modified in some way. The
+argument that is passed is the new @code{gdb.Breakpoint} object.
+
+@item events.breakpoint_deleted
+This is emitted when a breakpoint has been deleted. The argument that
+is passed is the @code{gdb.Breakpoint} object. When this event is
+emitted, the @code{gdb.Breakpoint} object will already be in its
+invalid state; that is, the @code{is_valid} method will return
+@code{False}.
+
+@item events.before_prompt
+This event carries no payload. It is emitted each time @value{GDBN}
+presents a prompt to the user.
+
+@item events.new_inferior
+This is emitted when a new inferior is created. Note that the
+inferior is not necessarily running; in fact, it may not even have an
+associated executable.
+
+The event is of type @code{gdb.NewInferiorEvent}. This has a single
+attribute:
+
+@defvar NewInferiorEvent.inferior
+The new inferior, a @code{gdb.Inferior} object.
+@end defvar
+
+@item events.inferior_deleted
+This is emitted when an inferior has been deleted. Note that this is
+not the same as process exit; it is notified when the inferior itself
+is removed, say via @code{remove-inferiors}.
+
+The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
+attribute:
+
+@defvar NewInferiorEvent.inferior
+The inferior that is being removed, a @code{gdb.Inferior} object.
+@end defvar
+
+@item events.new_thread
+This is emitted when @value{GDBN} notices a new thread. The event is of
+type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
+This has a single attribute:
+
+@defvar NewThreadEvent.inferior_thread
+The new thread.
+@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.global_num
+The global ID of the thread, as assigned by GDB. You can use this to
+make Python breakpoints thread-specific, for example
+(@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
@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 ()
Return a Boolean indicating whether the thread is exited.
@end defun
+@node Recordings In Python
+@subsubsection Recordings In Python
+@cindex recordings in python
+
+The following recordings-related functions
+(@pxref{Process Record and Replay}) are available in the @code{gdb}
+module:
+
+@defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
+Start a recording using the given @var{method} and @var{format}. If
+no @var{format} is given, the default format for the recording method
+is used. If no @var{method} is given, the default method will be used.
+Returns a @code{gdb.Record} object on success. Throw an exception on
+failure.
+
+The following strings can be passed as @var{method}:
+
+@itemize @bullet
+@item
+@code{"full"}
+@item
+@code{"btrace"}: Possible values for @var{format}: @code{"pt"},
+@code{"bts"} or leave out for default format.
+@end itemize
+@end defun
+
+@defun gdb.current_recording ()
+Access a currently running recording. Return a @code{gdb.Record}
+object on success. Return @code{None} if no recording is currently
+active.
+@end defun
+
+@defun gdb.stop_recording ()
+Stop the current recording. Throw an exception if no recording is
+currently active. All record objects become invalid after this call.
+@end defun
+
+A @code{gdb.Record} object has the following attributes:
+
+@defvar Record.method
+A string with the current recording method, e.g.@: @code{full} or
+@code{btrace}.
+@end defvar
+
+@defvar Record.format
+A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
+@code{None}.
+@end defvar
+
+@defvar Record.begin
+A method specific instruction object representing the first instruction
+in this recording.
+@end defvar
+
+@defvar Record.end
+A method specific instruction object representing the current
+instruction, that is not actually part of the recording.
+@end defvar
+
+@defvar Record.replay_position
+The instruction representing the current replay position. If there is
+no replay active, this will be @code{None}.
+@end defvar
+
+@defvar Record.instruction_history
+A list with all recorded instructions.
+@end defvar
+
+@defvar Record.function_call_history
+A list with all recorded function call segments.
+@end defvar
+
+A @code{gdb.Record} object has the following methods:
+
+@defun Record.goto (instruction)
+Move the replay position to the given @var{instruction}.
+@end defun
+
+The common @code{gdb.Instruction} class that recording method specific
+instruction objects inherit from, has the following attributes:
+
+@defvar Instruction.pc
+An integer representing this instruction's address.
+@end defvar
+
+@defvar Instruction.data
+A buffer with the raw instruction data. In Python 3, the return value is a
+@code{memoryview} object.
+@end defvar
+
+@defvar Instruction.decoded
+A human readable string with the disassembled instruction.
+@end defvar
+
+@defvar Instruction.size
+The size of the instruction in bytes.
+@end defvar
+
+Additionally @code{gdb.RecordInstruction} has the following attributes:
+
+@defvar RecordInstruction.number
+An integer identifying this instruction. @code{number} corresponds to
+the numbers seen in @code{record instruction-history}
+(@pxref{Process Record and Replay}).
+@end defvar
+
+@defvar RecordInstruction.sal
+A @code{gdb.Symtab_and_line} object representing the associated symtab
+and line of this instruction. May be @code{None} if no debug information is
+available.
+@end defvar
+
+@defvar RecordInstruction.is_speculative
+A boolean indicating whether the instruction was executed speculatively.
+@end defvar
+
+If an error occured during recording or decoding a recording, this error is
+represented by a @code{gdb.RecordGap} object in the instruction list. It has
+the following attributes:
+
+@defvar RecordGap.number
+An integer identifying this gap. @code{number} corresponds to the numbers seen
+in @code{record instruction-history} (@pxref{Process Record and Replay}).
+@end defvar
+
+@defvar RecordGap.error_code
+A numerical representation of the reason for the gap. The value is specific to
+the current recording method.
+@end defvar
+
+@defvar RecordGap.error_string
+A human readable string with the reason for the gap.
+@end defvar
+
+A @code{gdb.RecordFunctionSegment} object has the following attributes:
+
+@defvar RecordFunctionSegment.number
+An integer identifying this function segment. @code{number} corresponds to
+the numbers seen in @code{record function-call-history}
+(@pxref{Process Record and Replay}).
+@end defvar
+
+@defvar RecordFunctionSegment.symbol
+A @code{gdb.Symbol} object representing the associated symbol. May be
+@code{None} if no debug information is available.
+@end defvar
+
+@defvar RecordFunctionSegment.level
+An integer representing the function call's stack level. May be
+@code{None} if the function call is a gap.
+@end defvar
+
+@defvar RecordFunctionSegment.instructions
+A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
+associated with this function call.
+@end defvar
+
+@defvar RecordFunctionSegment.up
+A @code{gdb.RecordFunctionSegment} object representing the caller's
+function segment. If the call has not been recorded, this will be the
+function segment to which control returns. If neither the call nor the
+return have been recorded, this will be @code{None}.
+@end defvar
+
+@defvar RecordFunctionSegment.prev
+A @code{gdb.RecordFunctionSegment} object representing the previous
+segment of this function call. May be @code{None}.
+@end defvar
+
+@defvar RecordFunctionSegment.next
+A @code{gdb.RecordFunctionSegment} object representing the next segment of
+this function call. May be @code{None}.
+@end defvar
+
+The following example demonstrates the usage of these objects and
+functions to create a function that will rewind a record to the last
+time a function in a different file was executed. This would typically
+be used to track the execution of user provided callback functions in a
+library which typically are not visible in a back trace.
+
+@smallexample
+def bringback ():
+ rec = gdb.current_recording ()
+ if not rec:
+ return
+
+ insn = rec.instruction_history
+ if len (insn) == 0:
+ return
+
+ try:
+ position = insn.index (rec.replay_position)
+ except:
+ position = -1
+ try:
+ filename = insn[position].sal.symtab.fullname ()
+ except:
+ filename = None
+
+ for i in reversed (insn[:position]):
+ try:
+ current = i.sal.symtab.fullname ()
+ except:
+ current = None
+
+ if filename == current:
+ continue
+
+ rec.goto (i)
+ return
+@end smallexample
+
+Another possible application is to write a function that counts the
+number of code executions in a given line range. This line range can
+contain parts of functions or span across several functions and is not
+limited to be contiguous.
+
+@smallexample
+def countrange (filename, linerange):
+ count = 0
+
+ def filter_only (file_name):
+ for call in gdb.current_recording ().function_call_history:
+ try:
+ if file_name in call.symbol.symtab.fullname ():
+ yield call
+ except:
+ pass
+
+ for c in filter_only (filename):
+ for i in c.instructions:
+ try:
+ if i.sal.line in linerange:
+ count += 1
+ break;
+ except:
+ pass
+
+ return count
+@end smallexample
+
@node Commands In Python
@subsubsection Commands In Python
(@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.
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)
-@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.
@end defun
@defun Parameter.get_show_string (self, svalue)
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
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.
@code{unwind_stop_reason} method further down in this section).
@end defun
+@findex gdb.invalidate_cached_frames
+@defun gdb.invalidate_cached_frames
+@value{GDBN} internally keeps a cache of the frames that have been
+unwound. This function invalidates this cache.
+
+This function should not generally be called by ordinary Python code.
+It is documented for the sake of completeness.
+@end defun
+
A @code{gdb.Frame} object has the following methods:
@defun Frame.is_valid ()
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
contains everything minus functions and types.
@vindex SYMBOL_FUNCTIONS_DOMAIN
-@item gdb.SYMBOL_FUNCTION_DOMAIN
+@item gdb.SYMBOL_FUNCTIONS_DOMAIN
This domain contains all functions.
@vindex SYMBOL_TYPES_DOMAIN
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
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
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}
-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
-listed in the output from @code{info breakpoints} (but will be listed
-with the @code{maint info breakpoints} command). The optional
-@var{temporary} argument makes the breakpoint a temporary breakpoint.
-Temporary breakpoints are deleted after they have been hit. Any
-further access to the Python breakpoint after it has been hit will
-result in a runtime error (as that breakpoint has now been
-automatically deleted). The optional @var{wp_class} argument defines
-the class of watchpoint to create, if @var{type} is
-@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
-is assumed to be a @code{gdb.WP_WRITE} class.
+A breakpoint can be created using one of the two forms of the
+@code{gdb.Breakpoint} constructor. The first one accepts a string
+like one would pass to the @code{break}
+(@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
+(@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
+create both breakpoints and watchpoints. The second accepts separate Python
+arguments similar to @ref{Explicit Locations}, and can only be used to create
+breakpoints.
+
+@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
+Create a new breakpoint according to @var{spec}, which is a string naming the
+location of a breakpoint, or an expression that defines a watchpoint. The
+string should describe a location in a format recognized by the @code{break}
+command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
+watchpoint, by the @code{watch} command
+(@pxref{Set Watchpoints, , Setting Watchpoints}).
+
+The optional @var{type} argument specifies the type of the breakpoint to create,
+as defined below.
+
+The optional @var{wp_class} argument defines the class of watchpoint to create,
+if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
+defaults to @code{gdb.WP_WRITE}.
+
+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 listed in the output from @code{info breakpoints} (but will be listed with
+the @code{maint info breakpoints} command).
+
+The optional @var{temporary} argument makes the breakpoint a temporary
+breakpoint. Temporary breakpoints are deleted after they have been hit. Any
+further access to the Python breakpoint after it has been hit will result in a
+runtime error (as that breakpoint has now been automatically deleted).
+
+The optional @var{qualified} argument is a boolean that allows interpreting
+the function passed in @code{spec} as a fully-qualified name. It is equivalent
+to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
+@ref{Explicit Locations}).
+
@end defun
+@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
+This second form of creating a new breakpoint specifies the explicit
+location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
+be created in the specified source file @var{source}, at the specified
+@var{function}, @var{label} and @var{line}.
+
+@var{internal}, @var{temporary} and @var{qualified} have the same usage as
+explained previously.
+@end defun
+
+The available types are represented by constants defined in the @code{gdb}
+module:
+
+@vtable @code
+@vindex BP_BREAKPOINT
+@item gdb.BP_BREAKPOINT
+Normal code breakpoint.
+
+@vindex BP_WATCHPOINT
+@item gdb.BP_WATCHPOINT
+Watchpoint breakpoint.
+
+@vindex BP_HARDWARE_WATCHPOINT
+@item gdb.BP_HARDWARE_WATCHPOINT
+Hardware assisted watchpoint.
+
+@vindex BP_READ_WATCHPOINT
+@item gdb.BP_READ_WATCHPOINT
+Hardware assisted read watchpoint.
+
+@vindex BP_ACCESS_WATCHPOINT
+@item gdb.BP_ACCESS_WATCHPOINT
+Hardware assisted access watchpoint.
+@end vtable
+
+The available watchpoint types represented by constants are defined in the
+@code{gdb} module:
+
+@vtable @code
+@vindex WP_READ
+@item gdb.WP_READ
+Read only watchpoint.
+
+@vindex WP_WRITE
+@item gdb.WP_WRITE
+Write only watchpoint.
+
+@vindex WP_ACCESS
+@item gdb.WP_ACCESS
+Read/Write watchpoint.
+@end vtable
+
@defun Breakpoint.stop (self)
The @code{gdb.Breakpoint} class can be sub-classed and, in
particular, you may choose to implement the @code{stop} method.
@end smallexample
@end defun
-The available watchpoint types represented by constants are defined in the
-@code{gdb} module:
-
-@vtable @code
-@vindex WP_READ
-@item gdb.WP_READ
-Read only watchpoint.
-
-@vindex WP_WRITE
-@item gdb.WP_WRITE
-Write only watchpoint.
-
-@vindex WP_ACCESS
-@item gdb.WP_ACCESS
-Read/Write watchpoint.
-@end vtable
-
@defun Breakpoint.is_valid ()
Return @code{True} if this @code{Breakpoint} object is valid,
@code{False} otherwise. A @code{Breakpoint} object can become invalid
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
@code{silent} attribute.
@end defvar
+@defvar Breakpoint.pending
+This attribute is @code{True} if the breakpoint is pending, and
+@code{False} otherwise. @xref{Set Breaks}. This attribute is
+read-only.
+@end defvar
+
+@anchor{python_breakpoint_thread}
@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
writable.
@end defvar
-The available types are represented by constants defined in the @code{gdb}
-module:
-
-@vtable @code
-@vindex BP_BREAKPOINT
-@item gdb.BP_BREAKPOINT
-Normal code breakpoint.
-
-@vindex BP_WATCHPOINT
-@item gdb.BP_WATCHPOINT
-Watchpoint breakpoint.
-
-@vindex BP_HARDWARE_WATCHPOINT
-@item gdb.BP_HARDWARE_WATCHPOINT
-Hardware assisted watchpoint.
-
-@vindex BP_READ_WATCHPOINT
-@item gdb.BP_READ_WATCHPOINT
-Hardware assisted read watchpoint.
-
-@vindex BP_ACCESS_WATCHPOINT
-@item gdb.BP_ACCESS_WATCHPOINT
-Hardware assisted access watchpoint.
-@end vtable
-
@defvar Breakpoint.hit_count
This attribute holds the hit count for the breakpoint, an integer.
This attribute is writable, but currently it can only be set to zero.
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
@defvar LazyString.type
This attribute holds the type that is represented by the lazy string's
-type. For a lazy string this will always be a pointer type. To
+type. For a lazy string this is a pointer or array type. To
resolve this to the lazy string's character type, use the type's
@code{target} method. @xref{Types In Python}. This attribute is not
writable.
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