crash.util package
******************

exception crash.util.InvalidComponentError(gdbtype: Type, spec: str, message: str)

   Bases: "LookupError"

   An error occured while resolving the member specification

   formatter = "cannot resolve '{}->{}' ({})"

crash.util.array_for_each(value: Value) -> Iterator[Value]

   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

   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

   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

   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

   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

   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

   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

   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

   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

   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: Type, member_name: str, error: bool = True) -> Tuple[int, Type] | None

   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: Type | Value | str | Symbol) -> Type

   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

   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

   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

   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

   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

   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
==========

* crash.util.symbols module

  * "CallbackCollection"

  * "DelayedCollection"

    * "DelayedCollection.attrs"

    * "DelayedCollection.get()"

    * "DelayedCollection.override()"

  * "DelayedValues"

  * "MinimalSymbolCallbacks"

  * "MinimalSymbols"

  * "MinimalSymvals"

  * "SymbolCallbacks"

  * "Symbols"

  * "Symvals"

  * "TypeCallbacks"

  * "Types"

    * "Types.override()"
