Package ghidra.program.model.pcode

# Class HighSymbol

java.lang.Object
ghidra.program.model.pcode.HighSymbol

Direct Known Subclasses:
  `EquateSymbol`, `HighCodeSymbol`, `HighExternalSymbol`, `HighFunctionShellSymbol`, `HighFunctionSymbol`, `HighLabelSymbol`, `UnionFacetSymbol`

public class HighSymbol extends Object
A symbol within the decompiler's model of a particular function. The symbol has a name and a data-type along with other properties. The symbol is mapped to one or more storage locations by attaching a SymbolEntry for each mapping.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected int`
  `category`
  `protected int`
  `categoryIndex`
  `protected PcodeDataTypeManager`
  `dtmanage`
  `protected SymbolEntry[]`
  `entryList`
  `protected HighFunction`
  `function`
  `static final long`
  `ID_BASE`
  `protected String`
  `name`
  `protected DataType`
  `type`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `HighSymbol(long uniqueId, String nm, DataType tp, boolean tlock, boolean nlock, PcodeDataTypeManager manage)`
  Construct a symbol that is not attached to a function model.
  `protected`
  `HighSymbol(long uniqueId, String nm, DataType tp, HighFunction func)`
  Construct a base symbol, given a name and data-type.
  `protected`
  `HighSymbol(HighFunction func)`
  Constructor for use with restoreXML

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addMapEntry(SymbolEntry entry)`
  `void`
  `decode(Decoder decoder)`
  Decode this symbol object and its associated mappings from the stream.
  `protected void`
  `decodeHeader(Decoder decoder)`
  `static HighSymbol`
  `decodeMapSym(Decoder decoder, boolean isGlobal, HighFunction high)`
  Restore a full HighSymbol from the next <mapsym> element in the stream.
  `void`
  `encode(Encoder encoder)`
  Encode the symbol description as an element to the stream.
  `protected void`
  `encodeHeader(Encoder encoder)`
  Encode attributes for the base symbol element
  `static void`
  `encodeMapSym(Encoder encoder, HighSymbol sym)`
  Encode the given symbol with all its mapping as a <mapsym> element to the stream.
  `int`
  `getCategoryIndex()`
  For parameters (category=0), this method returns the position of the parameter within the function prototype.
  `DataType`
  `getDataType()`
  `protected int`
  `getFirstUseOffset()`
  Get the first code Address (expressed as a different in bytes from the starting address of the function) where this symbol's storage actually holds the value of the symbol.
  `SymbolEntry`
  `getFirstWholeMap()`
  `HighFunction`
  `getHighFunction()`
  Get the function model of which this symbol is a part.
  `HighVariable`
  `getHighVariable()`
  Get the HighVariable associate with this symbol if any.
  `long`
  `getId()`
  Get id associated with this symbol.
  `int`
  `getMutability()`
  Return one of - MutabilitySettingsDefinition.NORMAL - MutabilitySettingsDefinition.VOLATILE - MutabilitySettingsDefinition.CONSTANT
  `String`
  `getName()`
  Get the base name of this symbol
  `Namespace`
  `getNamespace()`
  Fetch the namespace owning this symbol, if it exists.
  `Address`
  `getPCAddress()`
  Get the first code Address, within the function, where this symbol's storage actually holds the value of the symbol.
  `Program`
  `getProgram()`
  Get the Program object containing the function being modeled.
  `int`
  `getSize()`
  `VariableStorage`
  `getStorage()`
  `Symbol`
  `getSymbol()`
  Fetch the corresponding database Symbol if it exists.
  `boolean`
  `isGlobal()`
  Is this symbol in the global scope or some other global namespace
  `boolean`
  `isHiddenReturn()`
  `boolean`
  `isIsolated()`
  If this returns true, the decompiler will not speculatively merge this with other variables.
  `boolean`
  `isNameLocked()`
  If this returns true, this symbol's name is "locked".
  `boolean`
  `isParameter()`
  Is this symbol a parameter for a function
  `boolean`
  `isThisPointer()`
  `boolean`
  `isTypeLocked()`
  If this returns true, this symbol's data-type is "locked", meaning it is considered unchangeable during decompilation.
  `protected void`
  `setCategory(int cat, int index)`
  Set the category and associated index for this symbol.
  `void`
  `setNameLock(boolean namelock)`
  Set whether this symbol's name is considered "locked".
  `void`
  `setTypeLock(boolean typelock)`
  Set whether this symbol's data-type is considered "locked".

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

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

- ## Field Details

  - ### ID_BASE

    public static final long ID_BASE
    See Also:
      - Constant Field Values

  - ### name

    protected String name

  - ### type

    protected DataType type

  - ### function

    protected HighFunction function

  - ### category

    protected int category

  - ### categoryIndex

    protected int categoryIndex

  - ### entryList

    protected SymbolEntry[] entryList

  - ### dtmanage

    protected PcodeDataTypeManager dtmanage

- ## Constructor Details

  - ### HighSymbol

    protected HighSymbol(HighFunction func)
    Constructor for use with restoreXML
    Parameters:
      `func` - is the HighFunction using the symbol

  - ### HighSymbol

    protected HighSymbol(long uniqueId, String nm, DataType tp, HighFunction func)
    Construct a base symbol, given a name and data-type. Mappings must be attached separately.
    Parameters:
      `uniqueId` - is the id to associate with the new symbol
      `nm` - is the given name
      `tp` - is the given data-type
      `func` - is the function model owning the new symbol

  - ### HighSymbol

    protected HighSymbol(long uniqueId, String nm, DataType tp, boolean tlock, boolean nlock, PcodeDataTypeManager manage)
    Construct a symbol that is not attached to a function model. The symbol is given a name, data-type, and other basic attributes. Mappings must be attached separately.
    Parameters:
      `uniqueId` - is the id to associate with the new symbol
      `nm` - is the given name
      `tp` - is the given data-type
      `tlock` - is true if the symbol is type locked
      `nlock` - is true if the symbol is name locked
      `manage` - is a PcodeDataTypeManager to facilitate XML marshaling

- ## Method Details

  - ### addMapEntry

    protected void addMapEntry(SymbolEntry entry)

  - ### getId

    public long getId()
    Get id associated with this symbol.
    Returns:
      the id

  - ### getSymbol

    public Symbol getSymbol()
    Fetch the corresponding database Symbol if it exists.
    Returns:
      the matching Symbol object or null

  - ### getNamespace

    public Namespace getNamespace()
    Fetch the namespace owning this symbol, if it exists.
    Returns:
      the Namespace object or null

  - ### getHighVariable

    public HighVariable getHighVariable()
    Get the HighVariable associate with this symbol if any. The symbol may have multiple partial HighVariables associated with it. This method returns the biggest one, which may not be the same size as the symbol itself.
    Returns:
      the associated HighVariable or null

  - ### getName

    public String getName()
    Get the base name of this symbol
    Returns:
      the name

  - ### getProgram

    public Program getProgram()
    Get the Program object containing the function being modeled.
    Returns:
      the Program

  - ### getDataType

    public DataType getDataType()
    Returns:
      the data-type associate with this symbol

  - ### getSize

    public int getSize()
    Returns:
      the number of bytes consumed by the storage for this symbol

  - ### getPCAddress

    public Address getPCAddress()
    Get the first code Address, within the function, where this symbol's storage actually holds the value of the symbol. If there is more than one mapping for the symbol, this returns the code Address for the first mapping. A null value indicates that the storage is valid over the whole function (at least). If the value is non-null, the symbol storage may be used for other purposes at prior locations.
    Returns:
      the first use code Address or null

  - ### getFirstUseOffset

    protected int getFirstUseOffset()
    Get the first code Address (expressed as a different in bytes from the starting address of the function) where this symbol's storage actually holds the value of the symbol. A value of 0 indicates that the storage is valid across the entire function. A negative value indicates the storage is an input to the function.
    Returns:
      the first-use offset of this symbol's storage

  - ### getHighFunction

    public HighFunction getHighFunction()
    Get the function model of which this symbol is a part.
    Returns:
      the HighFunction owning this symbol

  - ### setCategory

    protected void setCategory(int cat, int index)
    Set the category and associated index for this symbol. The category indicates a specific sub-class of symbols. Currently -1=none, 0=parameter, 1=equate
    Parameters:
      `cat` - is the category
      `index` - is the category index ("slot" for parameters)

  - ### setTypeLock

    public void setTypeLock(boolean typelock)
    Set whether this symbol's data-type is considered "locked". If it is "locked", this symbol's data-type is considered unchangeable during decompilation. The data-type will be forced into the decompiler's model of the function to the extent possible.
    Parameters:
      `typelock` - is true if the data-type should be considered "locked".

  - ### setNameLock

    public void setNameLock(boolean namelock)
    Set whether this symbol's name is considered "locked". If it is "locked", the decompiler will use the name when labeling the storage described by this symbol.
    Parameters:
      `namelock` - is true if the name should be considered "locked".

  - ### isTypeLocked

    public boolean isTypeLocked()
    If this returns true, this symbol's data-type is "locked", meaning it is considered unchangeable during decompilation. The data-type will be forced into the decompiler's model of the function to the extent possible.
    Returns:
      true if the data-type is considered "locked".

  - ### isNameLocked

    public boolean isNameLocked()
    If this returns true, this symbol's name is "locked". meaning the decompiler is forced to use the name when labeling the storage described by this symbol.
    Returns:
      true if the name is considered "locked".

  - ### isIsolated

    public boolean isIsolated()
    If this returns true, the decompiler will not speculatively merge this with other variables. Currently, being isolated is equivalent to being typelocked.
    Returns:
      true if this will not be merged with other variables

  - ### getMutability

    public int getMutability()
    Return one of - MutabilitySettingsDefinition.NORMAL - MutabilitySettingsDefinition.VOLATILE - MutabilitySettingsDefinition.CONSTANT
    Returns:
      the mutability setting

  - ### isParameter

    public boolean isParameter()
    Is this symbol a parameter for a function
    Returns:
      true if this is a parameter

  - ### getCategoryIndex

    public int getCategoryIndex()
    For parameters (category=0), this method returns the position of the parameter within the function prototype.
    Returns:
      the category index for this symbol

  - ### isGlobal

    public boolean isGlobal()
    Is this symbol in the global scope or some other global namespace
    Returns:
      true if this is global

  - ### isThisPointer

    public boolean isThisPointer()
    Returns:
      true if symbol is a "this" pointer for a class method

  - ### isHiddenReturn

    public boolean isHiddenReturn()
    Returns:
      true is symbol holds a pointer to where a function's return value should be stored

  - ### getFirstWholeMap

    public SymbolEntry getFirstWholeMap()
    Returns:
      the first mapping object attached to this symbol

  - ### getStorage

    public VariableStorage getStorage()
    Returns:
      the storage associated with this symbol (associated with the first mapping)

  - ### encodeHeader

    protected void encodeHeader(Encoder encoder) throws IOException
    Encode attributes for the base symbol element
    Parameters:
      `encoder` - is the stream encoder
    Throws:
      `IOException` - for errors in the underlying stream

  - ### encode

    public void encode(Encoder encoder) throws IOException
    Encode the symbol description as an element to the stream. This does NOT save the mappings.
    Parameters:
      `encoder` - is the stream encoder
    Throws:
      `IOException` - for errors in the underlying stream

  - ### decodeHeader

    protected void decodeHeader(Decoder decoder) throws DecoderException
    Throws:
      `DecoderException`

  - ### decode

    public void decode(Decoder decoder) throws DecoderException
    Decode this symbol object and its associated mappings from the stream.
    Parameters:
      `decoder` - is the stream decoder
    Throws:
      `DecoderException` - for invalid encodings

  - ### decodeMapSym

    public static HighSymbol decodeMapSym(Decoder decoder, boolean isGlobal, HighFunction high) throws DecoderException
    Restore a full HighSymbol from the next <mapsym> element in the stream. This method acts as a HighSymbol factory, instantiating the correct class based on the particular elements.
    Parameters:
      `decoder` - is the stream decoder
      `isGlobal` - is true if this symbol is being read into a global scope
      `high` - is the function model that will own the new symbol
    Returns:
      the new symbol
    Throws:
      `DecoderException` - for invalid encodings

  - ### encodeMapSym

    public static void encodeMapSym(Encoder encoder, HighSymbol sym) throws IOException
    Encode the given symbol with all its mapping as a <mapsym> element to the stream.
    Parameters:
      `encoder` - is the stream encoder
      `sym` - is the given symbol
    Throws:
      `IOException` - for errors in the underlying stream