crash.util package

exception crash.util.InvalidComponentError(gdbtype: 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: Value) → Iterator[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: 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: Value, gdbtype: Type, member: str) → 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: 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: Value) → 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: Value) → 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: 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: Block = None, domain: int = None) → 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: Value | str | int, gdbtype: Type) → 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: Type, member_name: str, error: bool = True) → int | None[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:
crash.util.offsetof_type(gdbtype: Type, member_name: str, error: bool = True) → Tuple[int, Type] | None[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:
crash.util.resolve_type(val: Type | Value | str | Symbol) → 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_find_member_variant(gdbtype: Type, variants: List[str]) → str | None[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 or None: if no named member could be found

Return type:

str

crash.util.safe_get_symbol_value(symname: str, block: Block = None, domain: int = None) → Value | None[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_int(value: Any) → int | None[source]

Try to parse the input (typically string) as int.

Parameters:

value (Any) – the input to be parsed

Returns:

the parsed input value, or None: if input could not be parsed as int

Return type:

int

crash.util.safe_lookup_type(name: str, block: Block = None) → Type | None[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: Type | Value | str | 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.

Submodules