Type Printing API - Debugging with GDB
Description: Debugging with GDB

Next: Inferiors In Python, Previous: Writing a Pretty-Printer, Up: Python API

##### 23.2.2.8 Type Printing API

gdb provides a way for Python code to customize type display. This is mainly useful for substituting canonical typedef names for types.

A type printer is just a Python object conforming to a certain protocol. A simple base class implementing the protocol is provided; see gdb.types. A type printer must supply at least:

— Instance Variable of type_printer: enabled

> A boolean which is True if the printer is enabled, and False otherwise. This is manipulated by the `enable type-printer` and `disable type-printer` commands.

— Instance Variable of type_printer: name

> The name of the type printer. This must be a string. This is used by the `enable type-printer` and `disable type-printer` commands.

— Method on type_printer: instantiate (self)

> This is called by gdb at the start of type-printing. It is only called if the type printer is enabled. This method must return a new object that supplies a `recognize` method, as described below.

When displaying a type, say via the `ptype` command, gdb will compute a list of type recognizers. This is done by iterating first over the per-objfile type printers (see Objfiles In Python), followed by the per-progspace type printers (see Progspaces In Python), and finally the global type printers.

gdb will call the `instantiate` method of each enabled type printer. If this method returns `None`, then the result is ignored; otherwise, it is appended to the list of recognizers.

Then, when gdb is going to display a type name, it iterates over the list of recognizers. For each one, it calls the recognition function, stopping if the function returns a non-`None` value. The recognition function is defined as:

— Method on type_recognizer: recognize (self, type)

> If type is not recognized, return `None`. Otherwise, return a string which is to be printed as the name of type. type will be an instance of `gdb.Type` (see Types In Python).

gdb uses this two-pass approach so that type printers can efficiently cache information without holding on to it too long. For example, it can be convenient to look up type information in a type printer and hold it for a recognizer's lifetime; if a single pass were done then type printers would have to make use of the event system in order to avoid holding information that could become stale as the inferior changed.