class documentation

class Struct(_Type):

View In Hierarchy

A user-defined, named structure type. Can actually also be a union type.

The supported way of getting a Struct is to read type information from the debug object of a binary, using the reven2.ossi.Binary.exact_type method.

>>> struct_ty = next(server.ossi.executed_binaries("ntoskrnl")).exact_type("_OBJECT_ATTRIBUTES")

A Struct obtained in this way can then produce reven2.types.StructInstances by passing it as the type in the reven2.trace.Context.read method.

>>> struct_instance = ctx.read(reven2.address.LogicalAddress(0x65dd168), struct_ty)

To see the fields of a Struct at a glance, you can use its string representation that will list them in a custom format.

>>> print(struct_ty)
StructKind.Struct _OBJECT_ATTRIBUTES /* 0x30 */ {
    /* 0x0 */ Length : U32,
    /* 0x8 */ RootDirectory : void*,
    /* 0x10 */ ObjectName : _UNICODE_STRING*,
    /* 0x18 */ Attributes : U32,
    /* 0x20 */ SecurityDescriptor : void*,
    /* 0x28 */ SecurityQualityOfService : void*,
}

You can also iterate over the fields programmatically with the Struct.fields method, and get a specific field from its name with the Struct.field and Struct.bitfield methods (use the latter for bitfields, and the former for regular fields, or be welcomed by a ValueError).

Method __eq__ Compares the instance for equality with an object.
Method __hash__ Returns the hash for this value.
Method __init__ Initializes a new instance of this class from its kind, its size in bytes, its name, its mangled name if available, all of its fields, and optionally a Resolver.
Method __ne__ Compares the instance for equality with an object.
Method __str__ Returns the nicely printable string representation of this instance.
Method bitfield Find a bitfield from its name.
Method description The short description of this type.
Method field Find a regular (as in, non-bitfield) field from its name.
Method fields An iterator other the fields in this struct, in declaration order.
Method is_context_sensitive Whether the context argument needed by some methods actually has an effect.
Property kind Whether this instance is a struct, class, interface or enum.
Property mangled_name The mangled name of this struct, if exists.
Property name The name of this struct.
Method _construct_type Return the underlying construct instance
Method _decode Undocumented
Method _encode Undocumented
Instance Variable _fields Undocumented
Instance Variable _kind Undocumented
Instance Variable _mangled_name Undocumented
Instance Variable _name Undocumented
Instance Variable _resolver Undocumented
Instance Variable _size Undocumented

Inherited from Type:

Method parse Parses the value of an instance of this type from a raw buffer, possibly depending on the context.
Method size_bytes The minimal number of bytes necessary to hold an instance of this type, possibly depending on the context.
Method to_bytes Build a byte buffer from a value of this type.
Method _resolve Uses the resolver to return a resolved version of the type, if possible.
def __eq__(self, o):

Compares the instance for equality with an object.

  • if the object is not a Struct, it will never be equal to this instance.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __hash__(self):

Returns the hash for this value.

Returns
intUndocumented
def __init__(self, kind, size, name, mangled_name, fields, resolver=None):

Initializes a new instance of this class from its kind, its size in bytes, its name, its mangled name if available, all of its fields, and optionally a Resolver.

Parameters
kind:StructKindUndocumented
size:intUndocumented
name:strUndocumented
mangled_name:_Optional[str]Undocumented
fields:_Iterable[_Union[RegularField, Bitfield]]Undocumented
resolver:_Optional[_BaseTypeResolver]Undocumented
def __ne__(self, o):

Compares the instance for equality with an object.

  • if the object is not a Struct, it will never be equal to this instance.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
strUndocumented
def bitfield(self, key):

Find a bitfield from its name.

Information

Parameters
key:strthe exact name of the bitfield in the struct.
Returns
BitfieldUndocumented
Raises
KeyErrorif no field with this name exists in the struct.
ValueErrorif a field with this name exists in the struct, but is not a bitfield.
def description(self):

The short description of this type.

For named types, it is the name of the type. For other types, it is generally __str__.

Returns
strUndocumented
def field(self, key):

Find a regular (as in, non-bitfield) field from its name.

Information

Parameters
key:strthe exact name of the field in the struct.
Returns
RegularFieldUndocumented
Raises
KeyErrorif no field with this name exists in the struct.
ValueErrorif a field with this name exists in the struct, but is a bitfield.
def fields(self):

An iterator other the fields in this struct, in declaration order.

Returns
_Iterator[_Union[RegularField, Bitfield]]Undocumented
def is_context_sensitive(self):

Whether the context argument needed by some methods actually has an effect.

Types that return False to this method are context-insensitive types. You can safely pass any object as context parameter (including None) to the methods of such type.

Note that the context-sensitivity of a type may change in the future.

Examples

Getting the size of a type without needing a context for context-insensitive types: >>> types.U32.is_context_sensitive() False >>> types.U32.size_bytes(context=None) 4 >>> array32_12 = types.Array(types.U32, 12) >>> array32_12.is_context_sensitive() False >>> array32_12.size_bytes() # context=None by default 48

Context-sensitive types may raise errors when attempting to get the size without a context: >>> types.USize.is_context_sensitive() True >>> types.USize.size_bytes(context=None) ValueError: Please provide a context when using a context-sensitive type

Returns
boolUndocumented
@property
kind: StructKind =

Whether this instance is a struct, class, interface or enum.

@property
mangled_name: _Optional[str] =

The mangled name of this struct, if exists.

@property
name: str =

The name of this struct.

def _construct_type(self, context=None):

Return the underlying construct instance

Parameters
context:_Optional[Context]Undocumented
Returns
_construct.core.ConstructUndocumented
def _decode(self, buf, context):

Undocumented

Parameters
buf:bytesUndocumented
context:ContextUndocumented
Returns
StructInstanceUndocumented
def _encode(self, value, _):

Undocumented

Parameters
value:StructInstanceUndocumented
_Undocumented
Returns
bytesUndocumented
_fields =

Undocumented

_kind =

Undocumented

_mangled_name =

Undocumented

_name =

Undocumented

_resolver =

Undocumented

_size =

Undocumented