class documentation

class PointerInstance(_Generic[_ValueType]):

View In Hierarchy

A pointer instance, the result of reading a pointer.

Produce the value pointed to by the pointer with the PointerInstance.deref method.

You can always produce the pointed value as bytes with the PointerInstance.deref_bytes method, or as an str with the PointerInstance.deref_str method.

To cast this instance to a PointerInstance pointing to a different type, use the PointerInstance.cast_inner method.

Debug objects produce pointers with reven2.address.LogicalAddress as a base address, but sometimes the address is actually a reven2.address.LinearAddress, a reven2.address.PhysicalAddress, or a reven2.address.LogicalAddress with a different segment. In that case use the PointerInstance.with_base_address method to "fix-up" the address space of the pointer prior to dereferencing it.

Method __add__ Produces a new pointer whose address is offset by the specified number of elements (not bytes).
Method __and__ Produces a new pointer whose address has been modified by a bitwise and compared to the current instance.
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 __iadd__ Adds the specified number of elements (not bytes) to offset the address of this instance.
Method __iand__ Modifies this instance to apply the bitwise and operator with the specified value.
Method __init__ Initializes a new pointer instance from its pointer type, its offset and the context it was read at.
Method __ior__ Modifies this instance to apply the bitwise or operator with the specified value.
Method __isub__ Subtracts the specified number of elements (not bytes) to offset the address of this instance.
Method __ne__ Compares the instance for equality with an object.
Method __or__ Produces a new pointer whose address has been modified by a bitwise or compared to the current instance.
Method __str__ Returns the nicely printable string representation of this instance.
Method __sub__ Produces a new pointer whose address is subtracted by the specified number of elements (not bytes).
Method assert_array Asserts to the type system that this pointer produces an array value.
Method assert_bool Asserts to the type system that this pointer produces a boolean value.
Method assert_enum Asserts to the type system that this pointer produces an enum value.
Method assert_float Asserts to the type system that this pointer produces a float value.
Method assert_int Asserts to the type system that this pointer produces an integer value.
Method assert_ptr Asserts to the type system that this pointer produces a pointer value.
Method assert_struct Asserts to the type system that this pointer produces a struct value.
Method cast_inner Returns this pointer instance, specifying a different element type it should dereference to.
Method deref Dereferences this pointer to produce the value it points to.
Method deref_bytes Dereferences this pointer to produce the value it points to, interpreted as a buffer of bytes.
Method deref_str Dereferences this pointer to produce the value it points to, interpreted as a null-terminated string.
Method format Returns the nicely printable string representation of this instance.
Method slice Interpret this pointer as an array of the specified size.
Method with_base_address Returns a new PointerInstance using the specified base address instead of the current one.
Class Variable SubArrayValueType Undocumented
Class Variable SubPointerValueType Undocumented
Property address The address of the pointer.
Property context The context at which this instance was produced.
Property type The pointer type.
Instance Variable _address Undocumented
Instance Variable _ctx Undocumented
Instance Variable _pointer Undocumented
def __add__(self, other):

Produces a new pointer whose address is offset by the specified number of elements (not bytes).

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __and__(self, other):

Produces a new pointer whose address has been modified by a bitwise and compared to the current instance.

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __eq__(self, o):

Compares the instance for equality with an object.

  • if the object is of type _AbstractAddress, it will be considered equal to this instance if it is equal to the underlying adddress of this pointer instance.
  • two PointerInstances are considered equal if they have the same inner type and the same address.
  • if the object is neither _AbstractAddress nor PointerInstance, then it will never be considered equal.
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.

See StructInstance.__format__ for examples.

Parameters
format_spec:strUndocumented
Returns
strUndocumented
def __hash__(self):

Returns the hash for this value.

Returns
intUndocumented
def __iadd__(self, other):

Adds the specified number of elements (not bytes) to offset the address of this instance.

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __iand__(self, other):

Modifies this instance to apply the bitwise and operator with the specified value.

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __init__(self, pointer, offset, ctx):

Initializes a new pointer instance from its pointer type, its offset and the context it was read at.

Warnings

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

Parameters
pointer:_PointerUndocumented
offset:intUndocumented
ctx:_trace.ContextUndocumented
def __ior__(self, other):

Modifies this instance to apply the bitwise or operator with the specified value.

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __isub__(self, other):

Subtracts the specified number of elements (not bytes) to offset the address of this instance.

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __ne__(self, o):

Compares the instance for equality with an object.

  • if the object is of type _AbstractAddress, it will be considered equal to this instance if it is equal to the underlying adddress of this pointer instance.
  • two PointerInstances are considered equal if they have the same inner type and the same address.
  • if the object is neither _AbstractAddress nor PointerInstance, then it will never be considered equal.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __or__(self, other):

Produces a new pointer whose address has been modified by a bitwise or compared to the current instance.

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
strUndocumented
def __sub__(self, other):

Produces a new pointer whose address is subtracted by the specified number of elements (not bytes).

Parameters
other:intUndocumented
Returns
PointerInstance[_ValueType]Undocumented
def assert_array(self):

Asserts to the type system that this pointer produces an array value.

Information

Returns
PointerInstance[ArrayInstance]this instance, with the additional type information that it produces an array value.
Raises
ValueErrorif this instance does not, in fact, produce an array value, according to its runtime type.
def assert_bool(self):

Asserts to the type system that this pointer produces a boolean value.

Information

Returns
PointerInstance[bool]this instance, with the additional type information that it produces a boolean value.
Raises
ValueErrorif this instance does not, in fact, produce a boolean value, according to its runtime type.
def assert_enum(self):

Asserts to the type system that this pointer produces an enum value.

Information

Returns
PointerInstance[EnumerationInstance]this instance, with the additional type information that it produces an enum value.
Raises
ValueErrorif this instance does not, in fact, produce an enum value, according to its runtime type.
def assert_float(self):

Asserts to the type system that this pointer produces a float value.

Information

Returns
PointerInstance[float]this instance, with the additional type information that it produces a float value.
Raises
ValueErrorif this instance does not, in fact, produce a float value, according to its runtime type.
def assert_int(self):

Asserts to the type system that this pointer produces an integer value.

Information

Returns
PointerInstance[int]this instance, with the additional type information that it produces an int.
Raises
ValueErrorif this instance does not, in fact, produce an integer value, according to its runtime type.
def assert_ptr(self):

Asserts to the type system that this pointer produces a pointer value.

Information

Returns
PointerInstance[PointerInstance]this instance, with the additional type information that it produces a pointer value.
Raises
ValueErrorif this instance does not, in fact, produce a pointer value, according to its runtime type.
def assert_struct(self):

Asserts to the type system that this pointer produces a struct value.

Information

Returns
PointerInstance[StructInstance]this instance, with the additional type information that it produces a struct value.
Raises
ValueErrorif this instance does not, in fact, produce a struct value, according to its runtime type.
def cast_inner(self, inner_type):

Returns this pointer instance, specifying a different element type it should dereference to.

This method is a cast, able to change the type that the pointer points to. It cannot fail, but make sure the result makes sense.

Parameters
inner_type:_TypeUndocumented
Returns
PointerInstanceUndocumented
def deref(self):

Dereferences this pointer to produce the value it points to.

Information

Returns
_ValueTypea value whose type is determined by the element type of the pointer.
def deref_bytes(self):

Dereferences this pointer to produce the value it points to, interpreted as a buffer of bytes.

Information

Returns
bytesa buffer of bytes of length the size of the element type of the pointer.
def deref_str(self, cstring):

Dereferences this pointer to produce the value it points to, interpreted as a null-terminated string.

Information

Parameters
cstring:_CStringallows to specify the encoding and maximum size of the string to read.
Returns
strthe value pointed to by this pointer, as a string.
Raises
EncodingErrorif the bytes pointed to by the pointer contain errors wrt to the specified encoding.
def format(self, max_depth=1, current_depth=1):

Returns the nicely printable string representation of this instance.

Parameters
max_depth:intUndocumented
current_depth:intUndocumented
Returns
strUndocumented
def slice(self, size):

Interpret this pointer as an array of the specified size.

This allows to "undecay" arrays.

Parameters
size:intUndocumented
Returns
ArrayInstance[_ValueType]Undocumented
def with_base_address(self, base_address):

Returns a new PointerInstance using the specified base address instead of the current one.

Parameters
base_address:_AbstractAddressUndocumented
Returns
PointerInstance[_ValueType]Undocumented
SubArrayValueType =

Undocumented

SubPointerValueType =

Undocumented

@property
address: _AbstractAddress =

The address of the pointer.

@property
context: _trace.Context =

The context at which this instance was produced.

@property
type: _Pointer =

The pointer type.

_address =

Undocumented

_ctx =

Undocumented

_pointer =

Undocumented