gdb: Frame Decorator API
23.2.2.10 Decorating Frames
...........................
Frame decorators are sister objects to frame filters (
Frame Filter
API). Frame decorators are applied by a frame filter and can only be
used in conjunction with frame filters.
The purpose of a frame decorator is to customize the printed content
of each 'gdb.Frame' in commands where frame filters are executed. This
concept is called decorating a frame. Frame decorators decorate a
'gdb.Frame' with Python code contained within each API call. This
separates the actual data contained in a 'gdb.Frame' from the decorated
data produced by a frame decorator. This abstraction is necessary to
maintain integrity of the data contained in each 'gdb.Frame'.
Frame decorators have a mandatory interface, defined below.
GDB already contains a frame decorator called 'FrameDecorator'. This
contains substantial amounts of boilerplate code to decorate the content
of a 'gdb.Frame'. It is recommended that other frame decorators inherit
and extend this object, and only to override the methods needed.
'FrameDecorator' is defined in the Python module
'gdb.FrameDecorator', so your code can import it like:
from gdb.FrameDecorator import FrameDecorator
-- Function: FrameDecorator.elided (self)
The 'elided' method groups frames together in a hierarchical
system. An example would be an interpreter, where multiple
low-level frames make up a single call in the interpreted language.
In this example, the frame filter would elide the low-level frames
and present a single high-level frame, representing the call in the
interpreted language, to the user.
The 'elided' function must return an iterable and this iterable
must contain the frames that are being elided wrapped in a suitable
frame decorator. If no frames are being elided this function may
return an empty iterable, or 'None'. Elided frames are indented
from normal frames in a 'CLI' backtrace, or in the case of
'GDB/MI', are placed in the 'children' field of the eliding frame.
It is the frame filter's task to also filter out the elided frames
from the source iterator. This will avoid printing the frame
twice.
-- Function: FrameDecorator.function (self)
This method returns the name of the function in the frame that is
to be printed.
This method must return a Python string describing the function, or
'None'.
If this function returns 'None', GDB will not print any data for
this field.
-- Function: FrameDecorator.address (self)
This method returns the address of the frame that is to be printed.
This method must return a Python numeric integer type of sufficient
size to describe the address of the frame, or 'None'.
If this function returns a 'None', GDB will not print any data for
this field.
-- Function: FrameDecorator.filename (self)
This method returns the filename and path associated with this
frame.
This method must return a Python string containing the filename and
the path to the object file backing the frame, or 'None'.
If this function returns a 'None', GDB will not print any data for
this field.
-- Function: FrameDecorator.line (self):
This method returns the line number associated with the current
position within the function addressed by this frame.
This method must return a Python integer type, or 'None'.
If this function returns a 'None', GDB will not print any data for
this field.
-- Function: FrameDecorator.frame_args (self)
This method must return an iterable, or 'None'. Returning an empty
iterable, or 'None' means frame arguments will not be printed for
this frame. This iterable must contain objects that implement two
methods, described here.
This object must implement a 'argument' method which takes a single
'self' parameter and must return a 'gdb.Symbol' (Symbols In
Python), or a Python string. The object must also implement a
'value' method which takes a single 'self' parameter and must
return a 'gdb.Value' (Values From Inferior), a Python
value, or 'None'. If the 'value' method returns 'None', and the
'argument' method returns a 'gdb.Symbol', GDB will look-up and
print the value of the 'gdb.Symbol' automatically.
A brief example:
class SymValueWrapper():
def __init__(self, symbol, value):
self.sym = symbol
self.val = value
def value(self):
return self.val
def symbol(self):
return self.sym
class SomeFrameDecorator()
...
...
def frame_args(self):
args = []
try:
block = self.inferior_frame.block()
except:
return None
# Iterate over all symbols in a block. Only add
# symbols that are arguments.
for sym in block:
if not sym.is_argument:
continue
args.append(SymValueWrapper(sym,None))
# Add example synthetic argument.
args.append(SymValueWrapper(``foo'', 42))
return args
-- Function: FrameDecorator.frame_locals (self)
This method must return an iterable or 'None'. Returning an empty
iterable, or 'None' means frame local arguments will not be printed
for this frame.
The object interface, the description of the various strategies for
reading frame locals, and the example are largely similar to those
described in the 'frame_args' function, (The frame filter
frame_args function frame_args.). Below is a modified example:
class SomeFrameDecorator()
...
...
def frame_locals(self):
vars = []
try:
block = self.inferior_frame.block()
except:
return None
# Iterate over all symbols in a block. Add all
# symbols, except arguments.
for sym in block:
if sym.is_argument:
continue
vars.append(SymValueWrapper(sym,None))
# Add an example of a synthetic local variable.
vars.append(SymValueWrapper(``bar'', 99))
return vars
-- Function: FrameDecorator.inferior_frame (self):
This method must return the underlying 'gdb.Frame' that this frame
decorator is decorating. GDB requires the underlying frame for
internal frame information to determine how to print certain values
when printing a frame.
Info Catalog
gdb: Frame Filter API
gdb: Python API
gdb: Writing a Frame Filter