Package ghidra.program.model.mem

# Interface MemoryBlock

All Superinterfaces:
  `Comparable<MemoryBlock>`, `Serializable`

All Known Implementing Classes:
  `MemoryBlockDB`, `MemoryBlockStub`

public interface MemoryBlock extends Serializable, Comparable<MemoryBlock>
Interface that defines a block in memory.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `EXECUTE`
  `static final String`
  `EXTERNAL_BLOCK_NAME`
  A special purpose EXTERNAL block may be created by certain program loaders (e.g., Elf) to act as a stand-in for unknown external symbol locations when relocation support is required using a valid memory address.
  `static final int`
  `READ`
  `static final int`
  `VOLATILE`
  `static final int`
  `WRITE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `contains(Address addr)`
  Return whether addr is contained in this block.
  `AddressRange`
  `getAddressRange()`
  Get the address range that corresponds to this block.
  `byte`
  `getByte(Address addr)`
  Returns the byte at the given address in this block.
  `int`
  `getBytes(Address addr, byte[] b)`
  Tries to get b.length bytes from this block at the given address.
  `int`
  `getBytes(Address addr, byte[] b, int off, int len)`
  Tries to get len bytes from this block at the given address and put them into the given byte array at the specified offet.
  `String`
  `getComment()`
  Get the comment associated with this block.
  `InputStream`
  `getData()`
  Get memory data in the form of an InputStream.
  `Address`
  `getEnd()`
  Return the end address of this block.
  `String`
  `getName()`
  Get the name of this block
  `int`
  `getPermissions()`
  Returns block permissions as a bit mask.
  `long`
  `getSize()`
  Get the number of bytes in this block.
  `BigInteger`
  `getSizeAsBigInteger()`
  Get the number of bytes in this block.
  `List<MemoryBlockSourceInfo>`
  `getSourceInfos()`
  Returns a list of `MemoryBlockSourceInfo` objects for this block.
  `String`
  `getSourceName()`
  Get the name of the source of this memory block.
  `Address`
  `getStart()`
  Return the starting address for this block.
  `MemoryBlockType`
  `getType()`
  Get the type for this block: DEFAULT, BIT_MAPPED, or BYTE_MAPPED (see `MemoryBlockType`).
  `boolean`
  `isExecute()`
  Returns the value of the execute property associated with this block
  `default boolean`
  `isExternalBlock()`
  Returns true if this is a reserved EXTERNAL memory block based upon its name (see `EXTERNAL_BLOCK_NAME`).
  `boolean`
  `isInitialized()`
  Return whether this block has been initialized.
  `boolean`
  `isLoaded()`
  Returns true if this memory block is a real loaded block (i.e.
  `boolean`
  `isMapped()`
  Returns true if this is either a bit-mapped or byte-mapped block
  `boolean`
  `isOverlay()`
  Returns true if this is an overlay block (i.e., contained within overlay space).
  `boolean`
  `isRead()`
  Returns the value of the read property associated with this block
  `boolean`
  `isVolatile()`
  Returns the value of the volatile property associated with this block.
  `boolean`
  `isWrite()`
  Returns the value of the write property associated with this block
  `void`
  `putByte(Address addr, byte b)`
  Puts the given byte at the given address in this block.
  `int`
  `putBytes(Address addr, byte[] b)`
  Tries to put b.length bytes from the specified byte array to this block.
  `int`
  `putBytes(Address addr, byte[] b, int off, int len)`
  Tries to put len bytes from the specified byte array to this block.
  `void`
  `setComment(String comment)`
  Set the comment associated with this block.
  `void`
  `setExecute(boolean e)`
  Sets the execute property associated with this block.
  `void`
  `setName(String name)`
  Set the name for this block (See `NamingUtilities.isValidName(String)` for naming rules).
  `void`
  `setPermissions(boolean read, boolean write, boolean execute)`
  Sets the read, write, execute permissions on this block
  `void`
  `setRead(boolean r)`
  Sets the read property associated with this block.
  `void`
  `setSourceName(String sourceName)`
  Sets the name of the source file that provided the data.
  `void`
  `setVolatile(boolean v)`
  Sets the volatile property associated with this block.
  `void`
  `setWrite(boolean w)`
  Sets the write property associated with this block.

  ### Methods inherited from interface java.lang.Comparable

  `compareTo`

- ## Field Details

  - ### EXTERNAL_BLOCK_NAME

    static final String EXTERNAL_BLOCK_NAME
    A special purpose EXTERNAL block may be created by certain program loaders (e.g., Elf) to act as a stand-in for unknown external symbol locations when relocation support is required using a valid memory address. While the EXTERNAL block is created out of neccessity for relocation processing it introduces a number of limitations when used to carry data symbols where pointer math and offset-references may occur.

    The method `Memory.isExternalBlockAddress(Address)` may be used to determine if a specific address is contained within an EXTERNAL memory block.

    NOTE: Close proximity to the end of an address space should be avoided to allow for `OffsetReference` use.

    See Also:
      - Constant Field Values

  - ### VOLATILE

    static final int VOLATILE
    See Also:
      - Constant Field Values

  - ### READ

    static final int READ
    See Also:
      - Constant Field Values

  - ### WRITE

    static final int WRITE
    See Also:
      - Constant Field Values

  - ### EXECUTE

    static final int EXECUTE
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getPermissions

    int getPermissions()
    Returns block permissions as a bit mask. Permission bits defined as READ, WRITE, EXECUTE and VOLATILE

  - ### getData

    InputStream getData()
    Get memory data in the form of an InputStream. Null is returned for thos memory blocks which have no data.

  - ### contains

    boolean contains(Address addr)
    Return whether addr is contained in this block.
    Parameters:
      `addr` - address

  - ### getStart

    Address getStart()
    Return the starting address for this block.
    Returns:
      block's start address

  - ### getEnd

    Address getEnd()
    Return the end address of this block.
    Returns:
      end address of the block

  - ### getAddressRange

    AddressRange getAddressRange()
    Get the address range that corresponds to this block.
    Returns:
      block address range

  - ### getSize

    long getSize()
    Get the number of bytes in this block.
    Returns:
      number of bytes in the block

  - ### getSizeAsBigInteger

    BigInteger getSizeAsBigInteger()
    Get the number of bytes in this block.
    Returns:
      the number of bytes in this block as a BigInteger

  - ### getName

    String getName()
    Get the name of this block

  - ### setName

    void setName(String name) throws IllegalArgumentException, LockException
    Set the name for this block (See `NamingUtilities.isValidName(String)` for naming rules). Specified name must not conflict with an address space name.
    Parameters:
      `name` - the new name for this block.
    Throws:
      `IllegalArgumentException` - if invalid name specified
      `LockException` - renaming an Overlay block without exclusive access

  - ### getComment

    String getComment()
    Get the comment associated with this block.

  - ### setComment

    void setComment(String comment)
    Set the comment associated with this block.
    Parameters:
      `comment` - the comment to associate with this block.

  - ### isRead

    boolean isRead()
    Returns the value of the read property associated with this block

  - ### setRead

    void setRead(boolean r)
    Sets the read property associated with this block.
    Parameters:
      `r` - the value to set the read property to.

  - ### isWrite

    boolean isWrite()
    Returns the value of the write property associated with this block

  - ### setWrite

    void setWrite(boolean w)
    Sets the write property associated with this block.
    Parameters:
      `w` - the value to set the write property to.

  - ### isExecute

    boolean isExecute()
    Returns the value of the execute property associated with this block

  - ### setExecute

    void setExecute(boolean e)
    Sets the execute property associated with this block.
    Parameters:
      `e` - the value to set the execute property to.

  - ### setPermissions

    void setPermissions(boolean read, boolean write, boolean execute)
    Sets the read, write, execute permissions on this block
    Parameters:
      `read` - the read permission
      `write` - the write permission
      `execute` - the execute permission

  - ### isVolatile

    boolean isVolatile()
    Returns the value of the volatile property associated with this block. This attribute is generally associated with block of I/O regions of memory.

  - ### setVolatile

    void setVolatile(boolean v)
    Sets the volatile property associated with this block.
    Parameters:
      `v` - the value to set the volatile property to.

  - ### getSourceName

    String getSourceName()
    Get the name of the source of this memory block.
    Returns:
      source name

  - ### setSourceName

    void setSourceName(String sourceName)
    Sets the name of the source file that provided the data.
    Parameters:
      `sourceName` - the name of the source file.

  - ### getByte

    byte getByte(Address addr) throws MemoryAccessException
    Returns the byte at the given address in this block.
    Parameters:
      `addr` - the address.
    Throws:
      `MemoryAccessException` - if any of the requested bytes are uninitialized.
      `IllegalArgumentException` - if the Address is not in this block.

  - ### getBytes

    int getBytes(Address addr, byte[] b) throws MemoryAccessException
    Tries to get b.length bytes from this block at the given address. May return fewer bytes if the requested length is beyond the end of the block.
    Parameters:
      `addr` - the address from which to get the bytes.
      `b` - the byte array to populate.
    Returns:
      the number of bytes actually populated.
    Throws:
      `MemoryAccessException` - if any of the requested bytes are uninitialized.
      `IllegalArgumentException` - if the Address is not in this block.

  - ### getBytes

    int getBytes(Address addr, byte[] b, int off, int len) throws IndexOutOfBoundsException, MemoryAccessException
    Tries to get len bytes from this block at the given address and put them into the given byte array at the specified offet. May return fewer bytes if the requested length is beyond the end of the block.
    Parameters:
      `addr` - the address from which to get the bytes.
      `b` - the byte array to populate.
      `off` - the offset into the byte array.
      `len` - the number of bytes to get.
    Returns:
      the number of bytes actually populated.
    Throws:
      `IndexOutOfBoundsException` - if invalid offset is specified
      `MemoryAccessException` - if any of the requested bytes are uninitialized.
      `IllegalArgumentException` - if the Address is not in this block.

  - ### putByte

    void putByte(Address addr, byte b) throws MemoryAccessException
    Puts the given byte at the given address in this block.
    Parameters:
      `addr` - the address.
    Throws:
      `MemoryAccessException` - if the block is uninitialized
      `IllegalArgumentException` - if the Address is not in this block.

  - ### putBytes

    int putBytes(Address addr, byte[] b) throws MemoryAccessException
    Tries to put b.length bytes from the specified byte array to this block. All the bytes may not be put if the requested length is beyond the end of the block.
    Parameters:
      `addr` - the address of where to put the bytes.
      `b` - the byte array containing the bytes to write.
    Returns:
      the number of bytes actually written.
    Throws:
      `MemoryAccessException` - if the block is uninitialized
      `IllegalArgumentException` - if the Address is not in this block.

  - ### putBytes

    int putBytes(Address addr, byte[] b, int off, int len) throws IndexOutOfBoundsException, MemoryAccessException
    Tries to put len bytes from the specified byte array to this block. All the bytes may not be written if the requested length is beyond the end of the block.
    Parameters:
      `addr` - the address of where to put the bytes.
      `b` - the byte array containing the bytes to write.
      `off` - the offset into the byte array.
      `len` - the number of bytes to write.
    Returns:
      the number of bytes actually written.
    Throws:
      `IndexOutOfBoundsException` - if invalid offset is specified
      `MemoryAccessException` - if the block is uninitialized
      `IllegalArgumentException` - if the Address is not in this block.

  - ### getType

    MemoryBlockType getType()
    Get the type for this block: DEFAULT, BIT_MAPPED, or BYTE_MAPPED (see `MemoryBlockType`).
    Returns:
      memory block type

  - ### isInitialized

    boolean isInitialized()
    Return whether this block has been initialized.

    WARNING: A mapped memory block may have a mix of intialized, uninitialized, and undefined regions. The value returned by this method for a mapped memory block is always false even if some regions are initialized.

    Returns:
      true if block is fully initialized and not a memory-mapped-block, else false

  - ### isMapped

    boolean isMapped()
    Returns true if this is either a bit-mapped or byte-mapped block
    Returns:
      true if this is either a bit-mapped or byte-mapped block

  - ### isExternalBlock

    default boolean isExternalBlock()
    Returns true if this is a reserved EXTERNAL memory block based upon its name (see `EXTERNAL_BLOCK_NAME`). Checks for individual addresses may be done using `Memory.isExternalBlockAddress(Address)`.

    Note that EXTERNAL blocks always resides within a memory space and never within the artifial `AddressSpace.EXTERNAL_SPACE` which is not a memory space. This can be a source of confusion. An EXTERNAL memory block exists to facilitate relocation processing for some external symbols which require a real memory address.

    Returns:
      true if this is a reserved EXTERNAL memory block

  - ### isOverlay

    boolean isOverlay()
    Returns true if this is an overlay block (i.e., contained within overlay space).
    Returns:
      true if this is an overlay block

  - ### isLoaded

    boolean isLoaded()
    Returns true if this memory block is a real loaded block (i.e. RAM) and not a special block containing file header data such as debug sections.
    Returns:
      true if this is a loaded block and not a "special" block such as a file header.

  - ### getSourceInfos

    List<MemoryBlockSourceInfo> getSourceInfos()
    Returns a list of `MemoryBlockSourceInfo` objects for this block. A block may consist of multiple sequences of bytes from different sources. Each such source of bytes is described by its respective SourceInfo object. Blocks may have multiple sources after two or more memory blocks have been joined together and the underlying byte sources can't be joined.
    Returns:
      a list of SourceInfo objects, one for each different source of bytes in this block.