23.3.2.41 Missing Debug Info In Python

When GDB encounters a new objfile (see Objfiles In Python), e.g. the primary executable, or any shared libraries used by the inferior, GDB will attempt to load the corresponding debug information for that objfile. The debug information might be found within the objfile itself, or within a separate objfile which GDB will automatically locate and load.

Sometimes though, GDB might not find any debug information for an objfile, in this case the debugging experience will be restricted.

If GDB fails to locate any debug information for a particular objfile, there is an opportunity for a Python extension to step in. A Python extension can potentially locate the missing debug information using some platform- or project-specific steps, and inform GDB of its location. Or a Python extension might provide some platform- or project-specific advice to the user about how to obtain the missing debug information.

A missing debug information Python extension consists of a handler object which has the name and enabled attributes, and implements the __call__ method. When GDB encounters an objfile for which it is unable to find any debug information, it invokes the __call__ method. Full details of how handlers are written can be found below.

The gdb.missing_debug Module

GDB comes with a gdb.missing_debug module which contains the following class and global function:

class: gdb.missing_debug.MissingDebugHandler

MissingDebugHandler is a base class from which user-created handlers can derive, though it is not required that handlers derive from this class, so long as any user created handler has the name and enabled attributes, and implements the __call__ method.

Function: MissingDebugHandler.__init__ (name)

The name is a string used to reference this missing debug handler within some GDB commands. Valid names consist of the characters [-_a-zA-Z0-9], creating a handler with an invalid name raises a ValueError exception.

Function: MissingDebugHandler.__call__ (objfile)

Sub-classes must override the __call__ method. The objfile argument will be a gdb.Objfile, this is the objfile for which GDB was unable to find any debug information.

The return value from the __call__ method indicates what GDB should do next. The possible return values are:

• None

  This indicates that this handler could not help with objfile, GDB should call any other registered handlers.

• True

  This indicates that this handler has installed the debug information into a location where GDB would normally expect to find it when looking for separate debug information files (see Separate Debug Files). GDB will repeat the normal lookup process, which should now find the separate debug file.

  If GDB still doesn’t find the separate debug information file after this second attempt, then the Python missing debug information handlers are not invoked a second time, this prevents a badly behaved handler causing GDB to get stuck in a loop. GDB will continue without any debug information for objfile.

• False

  This indicates that this handler has done everything that it intends to do with objfile, but no separate debug information can be found. GDB will not call any other registered handlers for objfile. GDB will continue without debugging information for objfile.

• A string

  The returned string should contain a filename. GDB will not call any further registered handlers, and will instead load the debug information from the file identified by the returned filename.

Invoking the __call__ method from this base class will raise a NotImplementedError exception.

Variable: MissingDebugHandler.name

A read-only attribute which is a string, the name of this handler passed to the __init__ method.

Variable: MissingDebugHandler.enabled

A modifiable attribute containing a boolean; when True, the handler is enabled, and will be used by GDB. When False, the handler has been disabled, and will not be used.

Function: gdb.missing_debug.register_handler (locus, handler, replace=False)

Register a new missing debug handler with GDB.

handler is an instance of a sub-class of MissingDebugHandler, or at least an instance of an object that has the same attributes and methods as MissingDebugHandler.

locus specifies to which handler list to prepend handler. It can be either a gdb.Progspace (see Progspaces In Python) or None, in which case the handler is registered globally. The newly registered handler will be called before any other handler from the same locus. Two handlers in the same locus cannot have the same name, an attempt to add a handler with an already existing name raises an exception unless replace is True, in which case the old handler is deleted and the new handler is prepended to the selected handler list.

GDB first calls the handlers for the current program space, and then the globally registered handlers. As soon as a handler returns a value other than None, no further handlers are called for this objfile.