Missing Objfiles In Python (Debugging with GDB)

#### 23.3.2.42 Missing Objfiles In Python ¶

When GDB opens a core file, for example with the `core-file` command (see core-file command), GDB will attempt to load the corresponding executable and shared libraries. Often these files can be found on the local machine, but sometimes these files cannot be found, in which case the debugging experience will be restricted.

If GDB fails to locate a particular file then there is an opportunity for a Python extension to step in. A Python extension can potentially locate the missing file 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 file.

A missing-objfile Python extension consists of a handler object which has the `name` and `enabled` attributes, and implements the `__call__` method. When GDB encounters a situation where a file cannot be found, but the build-id (see build ID) for the missing file is known, then the `__call__` method is invoked to try and find the file. Full details of how handlers are written can be found below.

#### The `gdb.missing_objfile` Module ¶

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

class: gdb.missing_objfile.MissingObjfileHandler ¶

  `MissingObjfileHandler` 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: MissingObjfileHandler.__init__ (name) ¶

    The name is a string used to reference this missing-objfile 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: MissingObjfileHandler.__call__ (pspace, build_id, filename) ¶

    Sub-classes must override the `__call__` method. The pspace argument will be a `gdb.Progspace` (see Program Spaces In Python), this is the program space in which GDB is looking for the missing file.

    The build_id argument is a string containing the build-id of the file that is missing, this will be in the same format as returned by `Objfile.build_id` (see Objfile.build_id).

    The filename argument contains the name of the file that GDB is looking for. This information is provided to allow handlers to generate informative messages for the user. A handler is not required to place the missing file at this location. There might already be a file present at this location, but it might not match the required build-id, in which case GDB will have ignored it. In some limited cases GDB might not be able to establish the filename of the file it is searching for, in this case GDB will use a string ‘`with build-id build_id`’ as a replacement.

    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 locate the missing file and GDB should call any other registered handlers.

    - `True`

      This indicates that this handler has installed the missing file into a location where GDB would normally expect to find it. The only location in which GDB will look is within the `.build-id` sub-directory within the debug-file-directory (see debug-file-directory).

      GDB will repeat the normal lookup process, which should now find the previously missing file.

      If GDB still doesn’t find file after this second attempt, then the Python missing-objfile 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 the missing file, though this will degrade the debugging experience.

    - `False`

      This indicates that this handler has done everything that it intends to do but the missing file could not be found. GDB will not call any other registered handlers to look for the missing file. GDB will continue without the missing file, though this will degrade the debugging experience.

    - A string

      The returned string should contain a filename. GDB will not call any further registered handlers, and will instead use the returned filename as the missing file.

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

  Variable: MissingObjfileHandler.name ¶

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

  Variable: MissingObjfileHandler.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_objfile.register_handler (locus, handler, replace=`False`) ¶

  Register a new missing-objfile handler with GDB.

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

  locus specifies to which handler list to prepend handler. It can be either a `gdb.Progspace` (see Program Spaces 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.

#### Managing Missing-Objfile Handlers ¶

GDB defines the following commands to manage registered missing-objfile handlers:

`info missing-objfile-handlers [ locus [ name-regexp ] ]` ¶

  Lists all registered missing-objfile handlers. Arguments locus and name-regexp are both optional and can be used to filter which handlers are listed.

  The locus argument should be either `global`, `progspace`, or the name of an object file. Only handlers registered for the specified locus will be listed.

  The name-regexp is a regular expression used to match against handler names.

`disable missing-objfile-handler [ locus [ name-regexp ] ]` ¶

  The locus and name-regexp are interpreted as in `info missing-objfile-handlers` above, but instead of listing the matching handlers, all of the matching handlers are disabled. The `enabled` field of each matching handler is set to `False`.

`enable missing-objfile-handler [ locus [ name-regexp ] ]` ¶

  The locus and name-regexp are interpreted as in `info missing-objfile-handlers` above, but instead of listing the matching handlers, all of the matching handlers are enabled. The `enabled` field of each matching handler is set to `True`.