* Pretty Printing API:: Pretty-printing values.
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
* Writing a Pretty-Printer:: Writing a Pretty-Printer.
-* Type Printing API:: Pretty-printing types.
+* Type Printing API:: Pretty-printing types.
* Frame Filter API:: Filtering Frames.
* Frame Decorator API:: Decorating Frames.
* Writing a Frame Filter:: Writing a Frame Filter.
* Lazy Strings In Python:: Python representation of lazy strings.
* Architectures In Python:: Python representation of architectures.
* Registers In Python:: Python representation of registers.
-* Connections In Python:: Python representation of connections.
+* Connections In Python:: Python representation of connections.
* TUI Windows In Python:: Implementing new TUI windows.
* Disassembly In Python:: Instruction Disassembly In Python
@end menu
representation of a C@t{++} object, @code{False} if they shouldn't (see
@code{set print static-members} in @ref{Print Settings}).
+@item max_characters
+Number of string characters to print, @code{0} to follow
+@code{max_elements}, or @code{UINT_MAX} to print an unlimited number
+of characters (see @code{set print characters} in @ref{Print Settings}).
+
@item max_elements
Number of array elements to print, or @code{0} to print an unlimited
number of elements (see @code{set print elements} in @ref{Print
@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:
+@var{frame_id}. The @var{frame_id} is used internally by @value{GDBN}
+to identify the frames within the current thread's stack. The
+attributes of @var{frame_id} determine what type of frame is
+created within @value{GDBN}:
@table @code
@item sp, pc
@var{value} is a register value (a @code{gdb.Value} object).
@end defun
+@subheading Registering an Unwinder
+
+Object files and program spaces can have unwinders registered with
+them. In addition, you can register unwinders globally.
+
+The @code{gdb.unwinders} module provides the function to register an
+unwinder:
+
+@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
+@var{locus} specifies to which unwinder list to prepend the
+@var{unwinder}. It can be either an object file (@pxref{Objfiles In
+Python}), a program space (@pxref{Progspaces In Python}), or
+@code{None}, in which case the unwinder is registered globally. 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 an unwinder with an already existing
+name raises an exception unless @var{replace} is @code{True}, in which
+case the old unwinder is deleted and the new unwinder is registered in
+its place.
+
+@value{GDBN} first calls the unwinders from all the object files in no
+particular order, then the unwinders from the current program space,
+then the globally registered unwinders, and finally the unwinders
+builtin to @value{GDBN}.
+@end defun
+
@subheading Unwinder Skeleton Code
@value{GDBN} comes with the module containing the base @code{Unwinder}
follows:
@smallexample
-from gdb.unwinders import Unwinder
+from gdb.unwinder import Unwinder
class FrameId(object):
def __init__(self, sp, pc):
class MyUnwinder(Unwinder):
- def __init__(....):
- super(MyUnwinder, self).__init___(<expects unwinder name argument>)
+ def __init__(self):
+ super().__init___("MyUnwinder_Name")
- def __call__(pending_frame):
+ def __call__(self, 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>)
+
+ # Create a FrameID. Usually the frame is identified by a
+ # stack pointer and the function address.
+ sp = ... compute a stack address ...
+ pc = ... compute function address ...
unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
- # Find the values of the registers in the caller's frame and
+ # Find the values of the registers in the caller's frame and
# save them in the result:
- unwind_info.add_saved_register(<register>, <value>)
+ unwind_info.add_saved_register(<register-number>, <register-value>)
....
# Return the result:
return unwind_info
+gdb.unwinder.register_unwinder(<locus>, MyUnwinder(), <replace>)
@end smallexample
-@subheading Registering an Unwinder
-
-Object files and program spaces can have unwinders registered with
-them. In addition, you can also register unwinders globally.
-
-The @code{gdb.unwinders} module provides the function to register an
-unwinder:
-
-@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
-@var{locus} specifies to which unwinder list to prepend the
-@var{unwinder}. It can be either an object file, a program space, or
-@code{None}, in which case the unwinder is registered globally. 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 an unwinder with an 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
commands. Setting this attribute to @code{True} will install the
command for use. If there is already a Python command with this name
installed, the currently installed command will be uninstalled, and
-this command installed in its place.
+this command installed in its stead.
@end defvar
-The following code snippet shows how a two trivial MI command can be
+The following code snippet shows how some trivial MI commands can be
implemented in Python:
@smallexample
@findex PARAM_UINTEGER
@findex gdb.PARAM_UINTEGER
@item gdb.PARAM_UINTEGER
-The value is an unsigned integer. The value of 0 should be
-interpreted to mean ``unlimited''.
+The value is an unsigned integer. The value of @code{None} should be
+interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also
+be used to set that value), and the value of 0 is reserved and should
+not be used.
@findex PARAM_INTEGER
@findex gdb.PARAM_INTEGER
@item gdb.PARAM_INTEGER
-The value is a signed integer. The value of 0 should be interpreted
-to mean ``unlimited''.
+The value is a signed integer. The value of @code{None} should be
+interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also
+be used to set that value), and the value of 0 is reserved and should
+not be used.
@findex PARAM_STRING
@findex gdb.PARAM_STRING
@findex PARAM_ZINTEGER
@findex gdb.PARAM_ZINTEGER
@item gdb.PARAM_ZINTEGER
-The value is an integer. This is like @code{PARAM_INTEGER}, except 0
-is interpreted as itself.
+The value is a signed integer. This is like @code{PARAM_INTEGER},
+except that 0 is allowed and the value of @code{None} is not supported.
@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.
+The value is an unsigned integer. This is like @code{PARAM_UINTEGER},
+except that 0 is allowed and the value of @code{None} is not supported.
@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.
+The value is a signed integer. This is like @code{PARAM_INTEGER}
+including that the value of @code{None} should be interpreted to mean
+``unlimited'' (literal @code{'unlimited'} can also be used to set that
+value), except that 0 is allowed, and the value cannot be negative,
+except the special value -1 is returned for the setting of ``unlimited''.
@findex PARAM_ENUM
@findex gdb.PARAM_ENUM
projects / binutils-gdb.git / blobdiff