reven2.types._instance.PointerInstance

class documentation

class PointerInstance(_Generic[_ValueType]):

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:`int`	Undocumented
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:`int`	Undocumented
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:`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.

See StructInstance.__format__ for examples.

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

def __hash__(self):

Returns the hash for this value.

Returns
`int`	Undocumented

def __iadd__(self, other):

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

Parameters
other:`int`	Undocumented
Returns
`PointerInstance[_ValueType]`	Undocumented

def __iand__(self, other):

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

Parameters
other:`int`	Undocumented
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:`_Pointer`	Undocumented
offset:`int`	Undocumented
ctx:`_trace.Context`	Undocumented

def __ior__(self, other):

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

Parameters
other:`int`	Undocumented
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:`int`	Undocumented
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:`object`	Undocumented
Returns
`bool`	Undocumented

def __or__(self, other):

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

Parameters
other:`int`	Undocumented
Returns
`PointerInstance[_ValueType]`	Undocumented

def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
`str`	Undocumented

def __sub__(self, other):

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

Parameters
other:`int`	Undocumented
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
`ValueError`	if 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
`ValueError`	if 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
`ValueError`	if 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
`ValueError`	if 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
`ValueError`	if 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
`ValueError`	if 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
`ValueError`	if 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:`_Type`	Undocumented
Returns
`PointerInstance`	Undocumented

def deref(self):

Dereferences this pointer to produce the value it points to.

Information

Returns
`_ValueType`	a 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
`bytes`	a 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:`_CString`	allows to specify the encoding and maximum size of the string to read.
Returns
`str`	the value pointed to by this pointer, as a string.
Raises
`EncodingError`	if 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:`int`	Undocumented
current_depth:`int`	Undocumented
Returns
`str`	Undocumented

def slice(self, size):

Interpret this pointer as an array of the specified size.

This allows to "undecay" arrays.

Parameters
size:`int`	Undocumented
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:`_AbstractAddress`	Undocumented
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