---

24.3.2.43 Missing Objfiles In Python

When ROCGDB opens a core file, for example with the core-file command (see core-file command), ROCGDB 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 ROCGDB 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 ROCGDB 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 ROCGDB 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

ROCGDB 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 ROCGDB 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 ROCGDB 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 ROCGDB 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 ROCGDB will have ignored it. In some limited cases ROCGDB might not be able to establish the filename of the file it is searching for, in this case ROCGDB will use a string ‘with build-id build_id’ as a replacement.

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

• None

  This indicates that this handler could not locate the missing file and ROCGDB should call any other registered handlers.

• True

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

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

  If ROCGDB 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 ROCGDB to get stuck in a loop. ROCGDB 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. ROCGDB will not call any other registered handlers to look for the missing file. ROCGDB will continue without the missing file, though this will degrade the debugging experience.

• A string

  The returned string should contain a filename. ROCGDB 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 ROCGDB. 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 ROCGDB.

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.

ROCGDB 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

ROCGDB 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.