class documentation

class StructInstance:

View In Hierarchy

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:objectUndocumented
Returns
boolUndocumented
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:strUndocumented
Returns
strUndocumented
def __hash__(self):

Returns the hash for this value.

Returns
intUndocumented
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:StructUndocumented
buf:bytesUndocumented
ctx:_trace.ContextUndocumented
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:objectUndocumented
Returns
boolUndocumented
def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
strUndocumented
def as_bytes(self):

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

Returns
bytesUndocumented
def bitfield(self, bitfield_name):

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

Information

Parameters
bitfield_name:strthe exact name of one of the declared bitfields of the struct. For fields, use field.
Returns
BitfieldInstanceUndocumented
Raises
KeyErrorif no field with this name exists in the struct.
ValueErrorif 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:strthe exact name of one of the declared fields of the struct. For bitfields, use bitfield.
Returns
FieldInstanceUndocumented
Raises
KeyErrorif no field with this name exists in the struct.
ValueErrorif 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:intUndocumented
current_depth:intUndocumented
Returns
strUndocumented
@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