crash.util.symbols module¶
The crash.util.symbols module provides a mechanism to simply discover and resolve symbols, types, minimal symbols, and values.
A typical use is declaring a DelayedCollection at the top of a module and using the DelayedCollection within the classes and functions that are a part of the module.
Each of the collections defined here are instantiated using a list of
names that each collection type will resolve into a type, a symbol, a minimal
symbol, etc. The names will by available as dictionary keys and also as
attribute names. In the latter case, the names will be resolved into
a form usable as an attribute name. See Types
for more information.
-
class
crash.util.symbols.
CallbackCollection
(cls: Type[crash.infra.lookup.NamedCallback], cbs: Union[List[Tuple[str, Callable]], Tuple[str, Callable]])[source]¶ Bases:
object
-
class
crash.util.symbols.
DelayedCollection
(cls: Type[crash.infra.lookup.DelayedValue], names: Union[List[str], str])[source]¶ Bases:
object
A generic container for delayed lookups.
In addition to the
get()
method, the names are also accessible via attribute names (__getattr__
) or dictionary keys (__getitem__
).Parameters: - cls – The type of
DelayedValue
to be collected - names – The names of all the symbols to be collected
-
attrs
¶ A dictionary that maps the attribute names to the
DelayedValue
object associated with each one. While the__getattr__
and__getitem__
methods will return the contained object. This dictionary will contain the container object or the contained object if it has been overridden viaoverride()
.Type: dict
-
get
(name: str) → Union[gdb.Type, gdb.Value, gdb.Symbol, gdb.MinSymbol, Any][source]¶ Obtain the object associated with name
Parameters: name – The attribute name associated with the
DelayedValue
Returns: The underlying object associated with this name.
Return type: object
Raises: NameError
– The name does not exist.DelayedAttributeError
– The name exists but the value has not been resolved yet.
-
override
(name: str, value: Union[gdb.Type, gdb.Value, gdb.Symbol, gdb.MinSymbol, Any]) → None[source]¶ Override the
DelayedValue
stored in the collectionAt times it may be required to override the value kept in the collection.
- cls – The type of
-
class
crash.util.symbols.
DelayedValues
(names: Union[List[str], str])[source]¶ Bases:
crash.util.symbols.DelayedCollection
A container to keep generic
DelayedValue
objects.These will raise
DelayedAttributeError
untilDelayedValue.callback()
is called with a value to populate it.The callback must be accessed via
DelayedCollection.attrs
or theDelayedValue
object will be evaluated first, also raisingDelayedAttributeError
.Example:
>>> from crash.util.symbols import DelayedValues >>> dvals = DelayedValues(['generic_value', 'another_value']) >>> dvals.attrs['generic_value'].callback(True) >>> print(dvals.generic_value) True >>> print(dvals.another_value) Traceback (most recent call last): File "<string>", line 4, in <module> File "./build/lib/crash/util/symbols.py", line 107, in __getattr__ return self.get(name) File "./build/lib/crash/util/symbols.py", line 85, in get raise DelayedAttributeError(name) crash.exceptions.DelayedAttributeError: Delayed attribute another_value has not been completed.
Parameters: names – The names to use for the DelayedValue
objects.
-
class
crash.util.symbols.
MinimalSymbolCallbacks
(cbs: Union[List[Tuple[str, Callable]], Tuple[str, Callable]])[source]¶
-
class
crash.util.symbols.
MinimalSymbols
(names: Union[List[str], str])[source]¶ Bases:
crash.util.symbols.DelayedCollection
A container to resolve
gdb.MinSymbol
objects from the symbol table as they become available. Minimal symbols don’t have any type information associated with them so they are mostly used to resolve names to addresses.Example:
>>> import gdb >>> from crash.util.symbols import MinimalSymbols >>> msymbols = MinimalSymbols(['modules', 'super_block']) >>> print(msymbols.modules.type) 11 >>> print(gdb.MINSYMBOL_TYPE_FILE_BSS) 11 >>> print(msymbols['modules']) modules >>> print(msymbols['modules'].value()) <data variable, no debug info> >>> print(msymbols['modules'].value().address) 0xffffffff820ff030 <modules> >>> print(type(msymbols['modules'])) <class 'gdb.MinSymbol'>
Parameters: names – A str
orlist
ofstr
containing the names of the minimal symbols to resolve.
-
class
crash.util.symbols.
MinimalSymvals
(names: Union[List[str], str])[source]¶ Bases:
crash.util.symbols.DelayedCollection
A container to resolve
gdb.MinSymbol
objects from the symbol table as they become available and uses the address of the values associated with them as the stored object. Minimal symbols don’t have any type information associated with them so they are mostly used to resolve names to addresses.Example:
>>> import gdb from crash.util.symbols import MinimalSymvals >>> msymvals = MinimalSymvals(['modules', 'super_block']) >>> print(f"{msymvals.modules:#x}") 0xffffffff820ff030 >>> print(f"{msymvals['modules']:#x}") 0xffffffff820ff030 >>> print(type(msymvals['modules'])) <class 'int'>
Parameters: names – A str
orlist
ofstr
containing the names of the minimal symbols to resolve.
-
class
crash.util.symbols.
SymbolCallbacks
(cbs: Union[List[Tuple[str, Callable]], Tuple[str, Callable]])[source]¶
-
class
crash.util.symbols.
Symbols
(names: Union[List[str], str])[source]¶ Bases:
crash.util.symbols.DelayedCollection
A container to resolve
gdb.Symbol
objects from the symbol table as they become available.Example:
>>> from crash.util.symbols import Symvals >>> symbols = Symbols(["modules", "super_blocks"]) >>> print(symbols.modules) modules >>> print(symbols['modules']) modules >>> print(symbols.modules.type) <class 'gdb.Symbol'>
Parameters: names – A str
orlist
ofstr
containing the names of the symbols to resolve.
-
class
crash.util.symbols.
Symvals
(names: Union[List[str], str])[source]¶ Bases:
crash.util.symbols.DelayedCollection
A container to resolve
gdb.Symbol
objects from the symbol table as they become available and use the associated values as the stored object.Example:
>>> from crash.util.symbols import Symvals >>> symvals = Symvals(["modules", "super_blocks"]) >>> print(symvals.modules) { next = 0xffffffffc0675208 <__this_module+8>, prev = 0xffffffffc00e8b48 <__this_module+8> } >>> print(symvals.modules.address) 0xffffffffab0ff030 <modules> >>> print(symvals['modules']) { next = 0xffffffffc0675208 <__this_module+8>, prev = 0xffffffffc00e8b48 <__this_module+8> } >>> print(symvals.modules.type) <class 'gdb.Value'>
Parameters: names – A str
orlist
ofstr
containing the names of the symbols to resolve.
-
class
crash.util.symbols.
TypeCallbacks
(cbs: Union[List[Tuple[str, Callable]], Tuple[str, Callable]])[source]¶
-
class
crash.util.symbols.
Types
(names: Union[List[str], str])[source]¶ Bases:
crash.util.symbols.DelayedCollection
A container to resolve
gdb.Type
objects from the symbol table as they become available.Example:
>>> from crash.util.symbols import Types >>> types = Types(["struct foo", "struct foo *"]) >>> ex1 = types.foo_type >>> ex2 = types.foo_p_type >>> ex3 = types['foo_type'] >>> ex4 = types['struct foo']
See
resolve_type()
for details.Parameters: names – A str
orlist
ofstr
containing the names of the types to resolve.