reven2.types._instance.StructInstance

class documentation

class StructInstance:

A struct instance, the result of reading a Struct at a context.

Print the bytes that make up the instance with the StructInstance.as_bytes method, or read a specific field as a FieldInstance from its name with the StructInstance.field and StructInstance.bitfield methods (use the latter for bitfields, and the former for the rest, or be welcomed by a ValueError).

>>> struct_instance.as_bytes()[0:28]
b'0Ñ]\x06B'

If you need the list of fields and their type, you can get back the underlying Struct description with the StructInstance.type property.

After getting a FieldInstance, you can obtain its value by reading it:

>>> struct_instance.field("Length").read()
48

Method	`__eq__`	Compares the instance for equality with an object.
Method	`__format__`	Formats the value according to the specified options.
Method	`__hash__`	Returns the hash for this value.
Method	`__init__`	Initializes a new instance of this class from its `Struct` type, its bytes and the context it was read at.
Method	`__ne__`	Compares the instance for equality with an object.
Method	`__str__`	Returns the nicely printable string representation of this instance.
Method	`as_bytes`	Returns the buffer of bytes that this instance is composed of.
Method	`bitfield`	Returns the result of reading the bitfield whose name was supplied.
Method	`field`	Returns the result of reading the field whose name was supplied.
Method	`fields`	Returns an iterator over the field and bitfield instances of this instance, in the order of declaration.
Method	`format`	Undocumented
Property	`context`	The context that this instance was spawned at.
Property	`type`	The struct type of this instance.
Instance Variable	`_buf`	Undocumented
Instance Variable	`_ctx`	Undocumented
Instance Variable	`_struct`	Undocumented

def __eq__(self, o):

Compares the instance for equality with an object.

if the object is of type bytes, it will be considered equal to this instance if it is equal to the underlying bytes that this instance is made of.
two StructInstances are considered equal if they have the same underlying Struct and bytes.
if the object is neither bytes nor StructInstance, then it will never be considered equal.

Notes

The context where this struct was spawned at is never taken into consideration for the purpose of equality. This means that two StructInstances at different contexts with the same type and bytes will be considered equal.
Similarly, the source from which the instance was read is never taken into consideration for the purpose of equality. This means that two StructInstances coming from different addresses in memory or different registers can compare equal if they have the same type and bytes.

Parameters
o:`object`	Undocumented
Returns
`bool`	Undocumented

def __format__(self, format_spec):

Formats the value according to the specified options.

The options are expected to be in the format described by reven2.util.parse_colon_separated_key_values.

The options will be passed as argument to format.

Examples

>>> # default formatting
>>> print(f"{instance}")
struct _RTL_AVL_TREE /* 0x8 */ {
    /* 0x0 */ Root : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe00013174e80,
}

>>> # expand inner struct
>>> print(f"{instance:max_depth=2}")
struct _RTL_AVL_TREE /* 0x8 */ {
    /* 0x0 */ Root : _RTL_BALANCED_NODE* = (struct _RTL_BALANCED_NODE /* 0x18 */ {
        /* 0x0 */ Children : [_RTL_BALANCED_NODE*; 2] = [...],
        /* 0x0 */ Left : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe000138fa510,
        /* 0x8 */ Right : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe00012818bc0,
        /* 0x10 */ Red : U8[0..1] = 0,
        /* 0x10 */ Balance : U8[0..2] = 0,
        /* 0x10 */ ParentValue : U64 = 0,
    })* @ds:0xffffe00013174e80,
}

>>> # do not expand struct at all
>>> print(f"{instance:max_depth=0}")
struct _RTL_AVL_TREE /* 0x8 */ { /* ... */ }

>>> # expand inner-inner struct
>>> print(f"{instance:max_depth=3}")
struct _RTL_AVL_TREE /* 0x8 */ {
    /* 0x0 */ Root : _RTL_BALANCED_NODE* = (struct _RTL_BALANCED_NODE /* 0x18 */ {
        /* 0x0 */ Children : [_RTL_BALANCED_NODE*; 2] = [
            (...)* @ds:0xffffe000138fa510,
            (...)* @ds:0xffffe00012818bc0],
        /* 0x0 */ Left : _RTL_BALANCED_NODE* = (struct _RTL_BALANCED_NODE /* 0x18 */ {
            /* 0x0 */ Children : [_RTL_BALANCED_NODE*; 2] = [...],
            /* 0x0 */ Left : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe0001216e4b0,
            /* 0x8 */ Right : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe000139fdd10,
            /* 0x10 */ Red : U8[0..1] = 0,
            /* 0x10 */ Balance : U8[0..2] = 0,
            /* 0x10 */ ParentValue : U64 = 18446708889657757312,
        })* @ds:0xffffe000138fa510,
        /* 0x8 */ Right : _RTL_BALANCED_NODE* = (struct _RTL_BALANCED_NODE /* 0x18 */ {
            /* 0x0 */ Children : [_RTL_BALANCED_NODE*; 2] = [...],
            /* 0x0 */ Left : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe0001303ddd0,
            /* 0x8 */ Right : _RTL_BALANCED_NODE* = (...)* @ds:0xffffe00012182530,
            /* 0x10 */ Red : U8[0..1] = 1,
            /* 0x10 */ Balance : U8[0..2] = 1,
            /* 0x10 */ ParentValue : U64 = 18446708889657757313,
        })* @ds:0xffffe00012818bc0,
        /* 0x10 */ Red : U8[0..1] = 0,
        /* 0x10 */ Balance : U8[0..2] = 0,
        /* 0x10 */ ParentValue : U64 = 0,
    })* @ds:0xffffe00013174e80,
}

Parameters
format_spec:`str`	Undocumented
Returns
`str`	Undocumented

def __hash__(self):

Returns the hash for this value.

Returns
`int`	Undocumented

def __init__(self, struct, buf, ctx):

Initializes a new instance of this class from its Struct type, its bytes and the context it was read at.

Warnings

At the moment, this object is not meant to be constructed directly. Use Context.read instead.

Parameters
struct:`Struct`	Undocumented
buf:`bytes`	Undocumented
ctx:`_trace.Context`	Undocumented

def __ne__(self, o):

Compares the instance for equality with an object.

if the object is of type bytes, it will be considered equal to this instance if it is equal to the underlying bytes that this instance is made of.
two StructInstances are considered equal if they have the same underlying Struct and bytes.
if the object is neither bytes nor StructInstance, then it will never be considered equal.

Notes

The context where this struct was spawned at is never taken into consideration for the purpose of equality. This means that two StructInstances at different contexts with the same type and bytes will be considered equal.
Similarly, the source from which the instance was read is never taken into consideration for the purpose of equality. This means that two StructInstances coming from different addresses in memory or different registers can compare equal if they have the same type and bytes.

Parameters
o:`object`	Undocumented
Returns
`bool`	Undocumented

def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
`str`	Undocumented

def as_bytes(self):

Returns the buffer of bytes that this instance is composed of.

Returns
`bytes`	Undocumented

def bitfield(self, bitfield_name):

Returns the result of reading the bitfield whose name was supplied.

Information

Parameters
bitfield_name:`str`	the exact name of one of the declared bitfields of the struct. For fields, use `field`.
Returns
`BitfieldInstance`	Undocumented
Raises
`KeyError`	if no field with this name exists in the struct.
`ValueError`	if a field with this name does exist in the struct, but it is not a bitfield.

def field(self, field_name):

Returns the result of reading the field whose name was supplied.

Information

Parameters
field_name:`str`	the exact name of one of the declared fields of the struct. For bitfields, use `bitfield`.
Returns
`FieldInstance`	Undocumented
Raises
`KeyError`	if no field with this name exists in the struct.
`ValueError`	if a field with this name does exist in the struct, but it is a bitfield.

def fields(self):

Returns an iterator over the field and bitfield instances of this instance, in the order of declaration.

Returns
`_Iterator[_Union[FieldInstance, BitfieldInstance]]`	Undocumented

def format(self, max_depth=1, current_depth=1):

Undocumented

Parameters
max_depth:`int`	Undocumented
current_depth:`int`	Undocumented
Returns
`str`	Undocumented

@property
context: _trace.Context =

The context that this instance was spawned at.

@property
type: Struct =

The struct type of this instance.

_buf =

Undocumented

_ctx =

Undocumented

_struct =

Undocumented