gtirb.byteinterval module

class gtirb.byteinterval.ByteInterval(*, address=None, size=None, initialized_size=None, contents=b'', blocks=(), symbolic_expressions={}, uuid=None, section=None)

Bases: Node

A contiguous region of bytes in a binary.

A ByteInterval defines a relative ordering for a group of ByteBlocks, optionally at a fixed address in memory. It also stores the bytes associated with these blocks.

If two blocks are in two different ByteIntervals, then it should be considered safe (that is, preserving of program semantics) to move one block relative to the other in memory. If two blocks are in the same ByteInterval, then it should be considered unknown if moving the two blocks relative to one another in memory is a safe operation.

Variables:

• ~.address – The fixed address of this interval, if present. If this field is present, it may indicate the original address at which this interval was located at in memory, or it may indicate that this block’s address is fixed and must not be changed. If this field is not present, it indicates that the interval is free to be moved around in memory while preserving program semantics.

• ~.size – The size of this interval in bytes. If this number is greater than initialized_size, this indicates that the high addresses taken up by this interval consist of uninitialized bytes. This often occurs in BSS sections, where data is zero-initialized rather than stored as zeroes in the binary.

• ~.contents – The bytes stored in this interval.

• ~.blocks – A set of all ByteBlocks in this interval.

• ~.symbolic_expressions – A mapping, from offset in the interval, to a SymbolicExpression in the interval.

__init__(*, address=None, size=None, initialized_size=None, contents=b'', blocks=(), symbolic_expressions={}, uuid=None, section=None)

Parameters:

• address (typing.Optional[int]) – The fixed address of this interval, if present.

• size (typing.Optional[int]) – The size of this interval in bytes.

• initialized_size (typing.Optional[int]) – The number of initialized bytes in this interval.

• contents (typing.ByteString) – The bytes stored in this interval.

• blocks (typing.Iterable[gtirb.block.ByteBlock]) – A set of all ByteBlocks in this interval.

• symbolic_expressions (typing.Union[typing.Mapping[int, gtirb.symbolicexpression.SymbolicExpression], typing.Iterable[typing.Tuple[int, gtirb.symbolicexpression.SymbolicExpression]]]) – A mapping, from offset in the interval, to a SymbolicExpression in the interval.

• uuid (typing.Optional[uuid.UUID]) – The UUID of this ByteInterval, or None if a new UUID needs generated via uuid.uuid4(). Defaults to None.

• section (typing.Optional[gtirb.section.Section]) – The Section this interval belongs to.

address

A descriptor that will notify a parent when the value is set and can be otherwise used like a normal attribute.

blocks: gtirb.util.SetWrapper[gtirb.block.ByteBlock]

byte_blocks_at(addrs)

Finds all the byte blocks that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.ByteBlock]

byte_blocks_at_offset(offsets)

Finds all the byte blocks that begin at an offset or range of offsets.

Parameters:

offsets (typing.Union[int, range]) – Either a range object or a single offset.

Return type:

typing.Iterable[gtirb.block.ByteBlock]

byte_blocks_on(addrs)

Finds all the byte blocks that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.ByteBlock]

byte_blocks_on_offset(offsets)

Finds all the byte blocks that overlap an offset or range of offsets.

Parameters:

offsets (typing.Union[int, range]) – Either a range object or a single offset.

Return type:

typing.Iterable[gtirb.block.ByteBlock]

code_blocks_at(addrs)

Finds all the code blocks that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.CodeBlock]

code_blocks_at_offset(offsets)

Finds all the code blocks that begin at an offset or range of offsets.

Parameters:

offsets (typing.Union[int, range]) – Either a range object or a single offset.

Return type:

typing.Iterable[gtirb.block.CodeBlock]

code_blocks_on(addrs)

Finds all the code blocks that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.CodeBlock]

code_blocks_on_offset(offsets)

Finds all the code blocks that overlap an offset or range of offsets.

Parameters:

offsets (typing.Union[int, range]) – Either a range object or a single offset.

Return type:

typing.Iterable[gtirb.block.CodeBlock]

data_blocks_at(addrs)

Finds all the data blocks that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.DataBlock]

data_blocks_at_offset(offsets)

Finds all the data blocks that begin at an offset or range of offsets.

Parameters:

offsets (typing.Union[int, range]) – Either a range object or a single offset.

Return type:

typing.Iterable[gtirb.block.DataBlock]

data_blocks_on(addrs)

Finds all the data blocks that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.DataBlock]

data_blocks_on_offset(offsets)

Finds all the data blocks that overlap an offset or range of offsets.

Parameters:

offsets (typing.Union[int, range]) – Either a range object or a single offset.

Return type:

typing.Iterable[gtirb.block.DataBlock]

deep_eq(other)

Check: is self structurally equal to other?

This method should be used only when deep structural equality checks are actually needed, and not for all equality checks. Typically the default implmentation of __eq__, which checks pointer equality, is sufficient; Nodes are cached such that references to two Nodes with the same UUID refer to the same exact object. Use this method when you have manually constructed Nodes that may share the same UUID despite being different objects, and you need to check for structural equality.

Return type:

bool

property initialized_size: int

The number of initialized bytes in this interval.

Not all bytes in this interval may correspond to bytes physically stored in the underlying file format. This can occur, for example, in BSS sections, which are zero-initialized at loadtime, but these zeroes are not stored in the file itself. If this number is smaller than size, this indicates that any bytes past this number are unitialized bytes with values determined at loadtime. As such, all bytes past this number in this interval’s byte vector are truncated when saving to file.

property ir: IR | None

Get the IR this node ultimately belongs to.

property module: Module | None

Get the module this node ultimately belongs to.

property section: Section | None

The Section this interval belongs to.

size

A descriptor that will notify a parent when the value is set and can be otherwise used like a normal attribute.

property symbolic_expressions: MutableMapping[int, SymbolicExpression]

symbolic_expressions_at(addrs)

Finds all the symbolic expressions that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[typing.Tuple[gtirb.byteinterval.ByteInterval, int, gtirb.symbolicexpression.SymbolicExpression]]

Returns:

Yields (interval, offset, symexpr) tuples for every symbolic expression in the range.

symbolic_expressions_at_offset(offsets)

Finds all the symbolic expressions that begin at an offset or range of offsets.

Parameters:

addrs – Either a range object or a single offset.

Return type:

typing.Iterable[typing.Tuple[gtirb.byteinterval.ByteInterval, int, gtirb.symbolicexpression.SymbolicExpression]]

Returns:

Yields (interval, offset, symexpr) tuples for every symbolic expression in the range.