#### 23.3.2.26 Program Spaces In Python ¶

A program space, or progspace, represents a symbolic view of an address space. It consists of all of the objfiles of the program. See Objfiles In Python. See program spaces, for more details about program spaces.

The following progspace-related functions are available in the `gdb` module:

Function: gdb.current_progspace () ¶

  This function returns the program space of the currently selected inferior. See Debugging Multiple Inferiors Connections and Programs. This is identical to `gdb.selected_inferior().progspace` (see Inferiors In Python) and is included for historical compatibility.

Function: gdb.progspaces () ¶

  Return a sequence of all the progspaces currently known to GDB.

Each progspace is represented by an instance of the `gdb.Progspace` class.

Variable: Progspace.filename ¶

  The file name, as a string, of the main symbol file (from which debug symbols have been loaded) for the progspace, e.g. the argument to the `symbol-file` or `file` commands.

  If there is no main symbol table currently loaded, then this attribute will be `None`.

Variable: Progspace.symbol_file ¶

  The `gdb.Objfile` representing the main symbol file (from which debug symbols have been loaded) for the `gdb.Progspace`. This is the symbol file set by the `symbol-file` or `file` commands.

  This will be the `gdb.Objfile` representing `Progspace.filename` when `Progspace.filename` is not `None`.

  If there is no main symbol table currently loaded, then this attribute will be `None`.

  If the `Progspace` is invalid, i.e., when `Progspace.is_valid()` returns `False`, then attempting to access this attribute will raise a `RuntimeError` exception.

Variable: Progspace.executable_filename ¶

  The file name, as a string, of the executable file in use by this program space. The executable file is the file that GDB will invoke in order to start an inferior when using a native target. The file name within this attribute is updated by the `exec-file` and `file` commands.

  If no executable is currently set within this `Progspace` then this attribute contains `None`.

  If the `Progspace` is invalid, i.e., when `Progspace.is_valid()` returns `False`, then attempting to access this attribute will raise a `RuntimeError` exception.

Variable: Progspace.pretty_printers ¶

  The `pretty_printers` attribute is a list of functions. It is used to look up pretty-printers. A `Value` is passed to each function in order; if the function returns `None`, then the search continues. Otherwise, the return value should be an object which is used to format the value. See Pretty Printing API, for more information.

Variable: Progspace.type_printers ¶

  The `type_printers` attribute is a list of type printer objects. See Type Printing API, for more information.

Variable: Progspace.frame_filters ¶

  The `frame_filters` attribute is a dictionary of frame filter objects. See Filtering Frames, for more information.

Variable: Progspace.missing_file_handlers ¶

  The `missing_file_handlers` attribute is a list of tuples. Each tuple holds a missing-file handler object for this program space. For more information, see Missing Debug Info In Python, and Missing Objfiles In Python.

A program space has the following methods:

Function: Progspace.block_for_pc (pc) ¶

  Return the innermost `gdb.Block` containing the given pc value. If the block cannot be found for the pc value specified, the function will return `None`.

Function: Progspace.find_pc_line (pc) ¶

  Return the `gdb.Symtab_and_line` object corresponding to the pc value. See Symbol table representation in Python. If an invalid value of pc is passed as an argument, then the `symtab` and `line` attributes of the returned `gdb.Symtab_and_line` object will be `None` and 0 respectively.

Function: Progspace.is_valid () ¶

  Returns `True` if the `gdb.Progspace` object is valid, `False` if not. A `gdb.Progspace` object can become invalid if the program space file it refers to is not referenced by any inferior. All other `gdb.Progspace` methods will throw an exception if it is invalid at the time the method is called.

Function: Progspace.objfiles () ¶

  Return a sequence of all the objfiles referenced by this program space. See Objfiles In Python.

Function: Progspace.solib_name (address) ¶

  Return the name of the shared library holding the given address as a string, or `None`.

Function: Progspace.objfile_for_address (address) ¶

  Return the `gdb.Objfile` holding the given address, or `None` if no objfile covers it.

One may add arbitrary attributes to `gdb.Progspace` objects in the usual Python way. This is useful if, for example, one needs to do some extra record keeping associated with the program space.

See choosing attribute names, for guidance on selecting a suitable name for new attributes.

In this contrived example, we want to perform some processing when an objfile with a certain symbol is loaded, but we only want to do this once because it is expensive. To achieve this we record the results with the program space because we can’t predict when the desired objfile will be loaded.

    (gdb) python

    def clear_objfiles_handler(event):
        event.progspace.expensive_computation = None
    def expensive(symbol):
        """A mock routine to perform an "expensive" computation on symbol."""
        print ("Computing the answer to the ultimate question ...")
        return 42

    def new_objfile_handler(event):
        objfile = event.new_objfile
        progspace = objfile.progspace
        if not hasattr(progspace, 'expensive_computation') or \
                progspace.expensive_computation is None:
            # We use 'main' for the symbol to keep the example simple.
            # Note: There's no current way to constrain the lookup
            # to one objfile.
            symbol = gdb.lookup_global_symbol('main')
            if symbol is not None:
                progspace.expensive_computation = expensive(symbol)
    gdb.events.clear_objfiles.connect(clear_objfiles_handler)
    gdb.events.new_objfile.connect(new_objfile_handler)
    end

    (gdb) file /tmp/hello
    Reading symbols from /tmp/hello...
    Computing the answer to the ultimate question ...
    (gdb) python print(gdb.current_progspace().expensive_computation)
    42
    (gdb) run
    Starting program: /tmp/hello
    Hello.
    [Inferior 1 (process 4242) exited normally]