crash.util package

exception crash.util.InvalidComponentError(gdbtype: gdb.Type, spec: str, message: str)[source]

Bases: LookupError

An error occured while resolving the member specification

formatter = "cannot resolve '{}->{}' ({})"
crash.util.array_for_each(value: gdb.Value) → Iterator[gdb.Value][source]

Yields each element in an array separately

Parameters:value (gdb.Value) – The array to iterate
Yields:gdb.Value – One element in the array at a time
crash.util.array_size(value: gdb.Value) → int[source]

Returns the number of elements in an array

Parameters:value (gdb.Value) – The array to size
Returns:The number of elements in the array
Return type:int
crash.util.container_of(val: gdb.Value, gdbtype: gdb.Type, member: str) → gdb.Value[source]

Returns an object that contains the specified object at the given offset.

Parameters:
  • val (gdb.Value) – The value to be converted. It can refer to an allocated structure or a pointer.
  • gdbtype (gdb.Type) – The type of the object that will be generated
  • member (str) – The name of the member in the target struct that contains val.
Returns:

The converted object, of the type specified by

the caller.
Return type:

gdb.Value<gdbtype>
Raises:

TypeError – val is not a gdb.Value
crash.util.decode_flags(value: gdb.Value, names: Dict[int, str], separator: str = '|') → str[source]

Present a bitfield of individual flags in a human-readable format.

Parameters:
  • value (gdb.Value<integer type>) – The value containing the flags to be decoded.
  • names (dict of int->str) – A dictionary containing mappings for each bit number to a human-readable name. Any flags found that do not have a matching value in the dict will be displayed as FLAG_<number>.
  • separator (str, defaults to "|") – The string to use as a separator between each flag name in the output.
Returns:

A human-readable string displaying the flag values.
Return type:

str
Raises:

TypeError – value is not gdb.Value or names is not dict.
crash.util.decode_uuid(value: gdb.Value) → uuid.UUID[source]

Decode an array of bytes that describes a UUID into a Python-style UUID object

Parameters:value (gdb.Value<uint8_t[16] or char[16]>) – The UUID to decode
Returns:The UUID object that describes the value
Return type:uuid.UUID
Raises:TypeError – value is not gdb.Value or does not describe a 16-byte array.
crash.util.decode_uuid_t(value: gdb.Value) → uuid.UUID[source]

Decode a Linux kernel uuid_t into a Python-style UUID object

Parameters:value (gdb.Value) – The uuid_t to be decoded
Returns:The UUID object that describes the value
Return type:uuid.UUID
Raises:TypeError – value is not gdb.Value<uuid_t>
crash.util.find_member_variant(gdbtype: gdb.Type, variants: List[str]) → str[source]

Examines the given type and returns the first found member name

Over time, structure member names may change. This routine allows the caller to provide a list of potential names and returns the first one found.

Parameters:
  • gdbtype (gdb.Type) – The type of structure or union to examine
  • variants (list of str) – The names of members to search
Returns:

The first member name found
Return type:

str
Raises:

TypeError – No named member could be found
crash.util.get_symbol_value(symname: str, block: gdb.Block = None, domain: int = None) → gdb.Value[source]

Returns the value associated with a named symbol

Parameters:
  • symname (str) – Name of the symbol to resolve
  • block (gdb.Block, optional, default=None) – The block to resolve the symbol within
  • domain (gdb.Symbol constant SYMBOL_*_DOMAIN, optional, default=None) – The domain to search for the symbol
Returns:

The requested value
Return type:

gdb.Value
Raises:

MissingSymbolError – The symbol or value cannot be located
crash.util.get_typed_pointer(val: Union[gdb.Value, str, int], gdbtype: gdb.Type) → gdb.Value[source]

Returns a pointer to the requested type at the given address

If the val is passed as a gdb.Value, it will be casted to the expected type. If it is not a pointer, the address of the value will be used instead.

Parameters:
  • val (gdb.Value, str, or int) – The address for which to provide a casted pointer
  • gdbtype (gdb.Type) – The type of the pointer to return
Returns:

The casted pointer of the requested type
Return type:

gdb.Value
Raises:

TypeError – string value for val does not describe a hex address or the type cannot be converted to an address
crash.util.offsetof(gdbtype: gdb.Type, member_name: str, error: bool = True) → Optional[int][source]

Returns the offset of a named member of a structure

Parameters:
  • gdbtype (gdb.Type) – The type that contains the specified member, must be a struct or union
  • member_name (str) – The member of the member to resolve
  • error (bool, optional, default=True) – Whether to consider lookup failures an error
Returns:

The offset of the resolved member None: The member could not be resolved
Return type:

int
Raises:
  • ArgumentTypeError – gdbtype is not a valid type
  • InvalidComponentError – member_name is not valid for the type
crash.util.offsetof_type(gdbtype: gdb.Type, member_name: str, error: bool = True) → Optional[Tuple[int, gdb.Type]][source]

Returns the offset and type of a named member of a structure

Parameters:
  • gdbtype (gdb.Type) – The type that contains the specified member, must be a struct or union
  • member_name (str) – The member of the member to resolve
  • error (bool, optional, default=True) – Whether to consider lookup failures an error
Returns:

int: The offset of the resolved member gdb.Type: The type of the resolved member
Return type:

Tuple of
Raises:
  • ArgumentTypeError – gdbtype is not of type gdb.Type
  • InvalidComponentError – member_name is not valid for the type
crash.util.resolve_type(val: Union[gdb.Type, gdb.Value, str, gdb.Symbol]) → gdb.Type[source]

Resolves a gdb.Type given a type, value, string, or symbol

Parameters:

val (gdb.Type, gdb.Value, str, gdb.Symbol) – The object for which to resolve the type
Returns:

The resolved type
Return type:

gdb.Type
Raises:
  • TypeError – The object type of val is not valid
  • MissingTypeError – could not resolve the type from string argument
crash.util.safe_get_symbol_value(symname: str, block: gdb.Block = None, domain: int = None) → Optional[gdb.Value][source]

Returns the value associated with a named symbol

Parameters:
  • symname (str) – Name of the symbol to resolve
  • block (gdb.Block, optional, default=None) – The block to resolve the symbol within
  • domain (gdb.Symbol constant SYMBOL_*_DOMAIN, optional, default=None) – The domain to search for the symbol
Returns:

The requested value or None: if the symbol or value cannot be found
Return type:

gdb.Value
crash.util.safe_lookup_type(name: str, block: gdb.Block = None) → Optional[gdb.Type][source]

Looks up a gdb.Type without throwing an exception on failure

Parameters:
  • name (str) – The name of the type to look up
  • block (gdb.Block, optional, default=None) – The block to use to resolve the type
Returns:

gdb.Type for requested type or None if it could not be found
crash.util.struct_has_member(gdbtype: Union[gdb.Type, gdb.Value, str, gdb.Symbol], name: str) → bool[source]

Returns whether a structure has a given member name.

A typical method of determining whether a structure has a member is just to check the fields list. That generally works but falls apart when the structure contains an anonymous union or substructure since it will push the members one level deeper in the namespace.

This routine provides a simple interface that covers those details.

Parameters:
  • val (gdb.Type, gdb.Value, str, gdb.Symbol) – The object for which to resolve the type to search for the member
  • name (str) – The name of the member to query
Returns:

Whether the member is present in the specified type
Return type:

bool
Raises:

TypeError – An invalid argument has been provided.