Selecting Pretty-Printers (Debugging with GDB)
Next: Writing a Pretty-Printer, Previous: Pretty Printing API, Up: Python API [Contents][Index]
23.3.2.6 Selecting Pretty-Printers
GDB provides several ways to register a pretty-printer: globally, per program space, and per objfile. When choosing how to register your pretty-printer, a good rule is to register it with the smallest scope possible: that is prefer a specific objfile first, then a program space, and only register a printer globally as a last resort.
- Variable
- gdb.pretty_printers
- The Python list
gdb.pretty_printers
contains an array of functions or callable objects that have been registered via addition as a pretty-printer. Printers in this list are calledglobal
printers, they’re available when debugging all inferiors.
Each gdb.Progspace
contains a pretty_printers
attribute. Each gdb.Objfile
also contains a pretty_printers
attribute.
Each function on these lists is passed a single gdb.Value
argument and should return a pretty-printer object conforming to the interface definition above (see Pretty Printing API). If a function cannot create a pretty-printer for the value, it should return None
.
GDB first checks the pretty_printers
attribute of each gdb.Objfile
in the current program space and iteratively calls each enabled lookup routine in the list for that gdb.Objfile
until it receives a pretty-printer object. If no pretty-printer is found in the objfile lists, GDB then searches the pretty-printer list of the current program space, calling each enabled function until an object is returned. After these lists have been exhausted, it tries the global gdb.pretty_printers
list, again calling each enabled function until an object is returned.
The order in which the objfiles are searched is not specified. For a given list, functions are always invoked from the head of the list, and iterated over sequentially until the end of the list, or a printer object is returned.
For various reasons a pretty-printer may not work. For example, the underlying data structure may have changed and the pretty-printer is out of date.
The consequences of a broken pretty-printer are severe enough that GDB provides support for enabling and disabling individual printers. For example, if print frame-arguments
is on, a backtrace can become highly illegible if any argument is printed with a broken printer.
Pretty-printers are enabled and disabled by attaching an enabled
attribute to the registered function or callable object. If this attribute is present and its value is False
, the printer is disabled, otherwise the printer is enabled.
Next: Writing a Pretty-Printer, Previous: Pretty Printing API, Up: Python API [Contents][Index]