Package ghidra.app.util.bin.format.golang.rtti

# Class GoSlice

java.lang.Object
ghidra.app.util.bin.format.golang.rtti.GoSlice

All Implemented Interfaces:
  `StructureMarkup<GoSlice>`

public class GoSlice extends Object implements StructureMarkup<GoSlice>
A structure that represents a golang slice instance (similar to a java ArrayList). Not to be confused with a `GoSliceType`, which is RTTI info about a slice type.

An initialized static image of a slice found in a go binary will tend to have len==cap (full).

Like java's type erasure for generics, a golang slice instance does not have type information about the elements found in the array blob (nor the size of the blob).

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GoSlice()`
  `GoSlice(long array, long len, long cap, GoRttiMapper programContext)`
  Creates an artificial slice instance using the supplied values.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `containsOffset(long offset, int sizeofElement)`
  Returns true if this slice contains the specified offset.
  `Address`
  `getArrayAddress()`
  Returns the address of the array blob
  `long`
  `getArrayEnd(Class<?> elementClass)`
  Returns the address of the end of the array.
  `long`
  `getArrayOffset()`
  Returns address of the array blob.
  `long`
  `getCap()`
  Returns the number of elements allocated in the array blob.
  `DataType`
  `getElementDataType()`
  Returns the `DataType` of elements of this slice, as detected by the type information contained in the struct field that contains this slice.
  `long`
  `getElementOffset(long elementSize, long elementIndex)`
  Returns the offset of the specified element
  `BinaryReader`
  `getElementReader(int elementSize, int elementIndex)`
  Returns a `BinaryReader` positioned at the specified slice element.
  `long`
  `getLen()`
  Returns the number of initialized elements
  `StructureContext<GoSlice>`
  `getStructureContext()`
  `String`
  `getStructureLabel()`
  Returns a string that can be used to place a label on the instance.
  `GoSlice`
  `getSubSlice(long startElement, long elementCount, long elementSize)`
  Return a artificial view of a portion of this slice's contents.
  `boolean`
  `isFull()`
  Returns true if this slice's element count is equal to the slice's capacity.
  `boolean`
  `isValid()`
  Returns true if this slice seems valid.
  `boolean`
  `isValid(int elementSize)`
  Returns true if this slice seems valid.
  `void`
  `markupArray(String sliceName, String namespaceName, DataType elementType, boolean ptr, MarkupSession session)`
  Marks up the memory occupied by the array elements with a name and a Ghidra ArrayDataType.
  `void`
  `markupArray(String sliceName, String namespaceName, Class<?> elementClazz, boolean ptr, MarkupSession session)`
  Marks up the memory occupied by the array elements with a name and a Ghidra ArrayDataType, which has elements who's type is determined by the specified structure class.
  `<T> List<T>`
  `markupArrayElements(Class<T> clazz, MarkupSession session)`
  Marks up each element of the array, useful when the elements are themselves structures.
  `void`
  `markupElementReferences(int elementSize, List<Address> targetAddrs, MarkupSession session)`
  Marks up each element of the array with an outbound reference to the corresponding address in the targetAddrs list.
  `<T> List<T>`
  `readList(BinaryReader.ReaderFunction<T> readFunc)`
  Reads the contents of the slice, treating each element as an instance of an object that can be read using the supplied reading function.
  `<T> List<T>`
  `readList(Class<T> clazz)`
  Reads the content of the slice, treating each element as an instance of the specified structure mapped class.
  `long`
  `readUIntElement(int intSize, int elementIndex)`
  Reads an unsigned int element from this slice.
  `long[]`
  `readUIntList(int intSize)`
  Treats this slice as a array of unsigned integers, of the specified intSize.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.app.util.bin.format.golang.structmapping.StructureMarkup

  `additionalMarkup, getExternalInstancesToMarkup, getStructureName, getStructureNamespace`

- ## Constructor Details

  - ### GoSlice

    public GoSlice()

  - ### GoSlice

    public GoSlice(long array, long len, long cap, GoRttiMapper programContext)
    Creates an artificial slice instance using the supplied values.
    Parameters:
      `array` - offset of the slice's data
      `len` - number of initialized elements in the slice
      `cap` - total number of elements in the data array
      `programContext` - the go binary that contains the slice

- ## Method Details

  - ### getElementDataType

    public DataType getElementDataType()
    Returns the `DataType` of elements of this slice, as detected by the type information contained in the struct field that contains this slice.

    Returns null if this slice instance was not nested (contained) in a structure. If the slice data type wasn't a specialized slice data type (it was "runtime.slice" instead of "[]element"), void data type will be returned.

    Returns:
      data type of the elements of this slice, if possible, or null

  - ### getSubSlice

    public GoSlice getSubSlice(long startElement, long elementCount, long elementSize)
    Return a artificial view of a portion of this slice's contents.
    Parameters:
      `startElement` - index of element that will be the new sub-slice's starting element
      `elementCount` - number of elements to include in new sub-slice
      `elementSize` - size of an individual element
    Returns:
      new `GoSlice` instance that is limited to a portion of this slice

  - ### isValid

    public boolean isValid()
    Returns true if this slice seems valid.
    Returns:
      boolean true if array blob is a valid memory location

  - ### isValid

    public boolean isValid(int elementSize)
    Returns true if this slice seems valid.
    Parameters:
      `elementSize` - size of elements in this slice
    Returns:
      boolean true if array blob is a valid memory location

  - ### getArrayOffset

    public long getArrayOffset()
    Returns address of the array blob.
    Returns:
      location of the array blob

  - ### getArrayAddress

    public Address getArrayAddress()
    Returns the address of the array blob
    Returns:
      address of the array blob

  - ### getArrayEnd

    public long getArrayEnd(Class<?> elementClass)
    Returns the address of the end of the array.
    Parameters:
      `elementClass` - structure mapped class
    Returns:
      location of the end of the array blob

  - ### getLen

    public long getLen()
    Returns the number of initialized elements
    Returns:
      number of initialized elements

  - ### getCap

    public long getCap()
    Returns the number of elements allocated in the array blob. (capacity)
    Returns:
      number of allocated elements in the array blob

  - ### isFull

    public boolean isFull()
    Returns true if this slice's element count is equal to the slice's capacity. This is typically true for all slices that are static.
    Returns:
      boolean true if this slice's element count is equal to capacity

  - ### containsOffset

    public boolean containsOffset(long offset, int sizeofElement)
    Returns true if this slice contains the specified offset.
    Parameters:
      `offset` - memory offset in question
      `sizeofElement` - size of elements in this slice
    Returns:
      true if this slice contains the specified offset

  - ### getElementOffset

    public long getElementOffset(long elementSize, long elementIndex)
    Returns the offset of the specified element
    Parameters:
      `elementSize` - size of elements in this slice
      `elementIndex` - index of desired element
    Returns:
      offset of element

  - ### readList

    public <T> List<T> readList(Class<T> clazz) throws IOException
    Reads the content of the slice, treating each element as an instance of the specified structure mapped class.
    Type Parameters:
      `T` - struct mapped type of element
    Parameters:
      `clazz` - element type
    Returns:
      list of instances
    Throws:
      `IOException` - if error reading an element

  - ### readList

    public <T> List<T> readList(BinaryReader.ReaderFunction<T> readFunc) throws IOException
    Reads the contents of the slice, treating each element as an instance of an object that can be read using the supplied reading function.
    Type Parameters:
      `T` - struct mapped type of element
    Parameters:
      `readFunc` - function that will read an instance from a BinaryReader
    Returns:
      list of instances
    Throws:
      `IOException` - if error reading an element

  - ### readUIntList

    public long[] readUIntList(int intSize) throws IOException
    Treats this slice as a array of unsigned integers, of the specified intSize.

    Parameters:
      `intSize` - size of integer
    Returns:
      array of longs, containing the (possibly smaller) integers contained in the slice
    Throws:
      `IOException` - if error reading

  - ### readUIntElement

    public long readUIntElement(int intSize, int elementIndex) throws IOException
    Reads an unsigned int element from this slice.
    Parameters:
      `intSize` - size of ints
      `elementIndex` - index of element
    Returns:
      unsigned int value
    Throws:
      `IOException` - if error reading element

  - ### getElementReader

    public BinaryReader getElementReader(int elementSize, int elementIndex)
    Returns a `BinaryReader` positioned at the specified slice element.
    Parameters:
      `elementSize` - size of elements in this slice
      `elementIndex` - index of desired element
    Returns:
      `BinaryReader` positioned at specified element

  - ### markupArray

    public void markupArray(String sliceName, String namespaceName, Class<?> elementClazz, boolean ptr, MarkupSession session) throws IOException
    Marks up the memory occupied by the array elements with a name and a Ghidra ArrayDataType, which has elements who's type is determined by the specified structure class.
    Parameters:
      `sliceName` - used to label the memory location
      `namespaceName` - namespace the label symbol should be placed in
      `elementClazz` - structure mapped class of the element of the array
      `ptr` - boolean flag, if true the element type is really a pointer to the supplied data type
      `session` - state and methods to assist marking up the program
    Throws:
      `IOException` - if error

  - ### markupArray

    public void markupArray(String sliceName, String namespaceName, DataType elementType, boolean ptr, MarkupSession session) throws IOException
    Marks up the memory occupied by the array elements with a name and a Ghidra ArrayDataType.
    Parameters:
      `sliceName` - used to label the memory location
      `namespaceName` - namespace the label symbol should be placed in
      `elementType` - Ghidra datatype of the array elements, null ok if ptr == true
      `ptr` - boolean flag, if true the element type is really a pointer to the supplied data type
      `session` - state and methods to assist marking up the program
    Throws:
      `IOException` - if error

  - ### markupArrayElements

    public <T> List<T> markupArrayElements(Class<T> clazz, MarkupSession session) throws IOException, CancelledException
    Marks up each element of the array, useful when the elements are themselves structures.
    Type Parameters:
      `T` - element type
    Parameters:
      `clazz` - structure mapped class of element
      `session` - state and methods to assist marking up the program
    Returns:
      list of element instances
    Throws:
      `IOException` - if error reading
      `CancelledException` - if cancelled

  - ### markupElementReferences

    public void markupElementReferences(int elementSize, List<Address> targetAddrs, MarkupSession session) throws IOException
    Marks up each element of the array with an outbound reference to the corresponding address in the targetAddrs list.

    Useful when marking up an array of offsets.

    The Listing UI doesn't show the outbound reference from each element (for arrays of primitive types), but the target will show the inbound reference.

    Parameters:
      `elementSize` - size of each element in the array
      `targetAddrs` - list of addresses, should be same size as this slice
      `session` - state and methods to assist marking up the program
    Throws:
      `IOException` - if error creating references

  - ### getStructureLabel

    public String getStructureLabel() throws IOException
    Description copied from interface: `StructureMarkup`
    Returns a string that can be used to place a label on the instance.

    This default implementation will query the `StructureMarkup.getStructureName()` method, and if it provides a value, will produce a string that looks like "name___mappingstructname", where "mappingstructname" will be the `structureName` value in the `@StructureMapping` annotation.

    Specified by:
      `getStructureLabel` in interface `StructureMarkup<GoSlice>`
    Returns:
      string to be used as a label, or null if there is not a valid label for the instance
    Throws:
      `IOException` - if error getting label

  - ### getStructureContext

    public StructureContext<GoSlice> getStructureContext()
    Specified by:
      `getStructureContext` in interface `StructureMarkup<GoSlice>`