Package ghidra.program.model.symbol

# Interface Symbol

All Known Implementing Classes:
  `ClassSymbol`, `CodeSymbol`, `FunctionSymbol`, `GlobalSymbol`, `GlobalVariableSymbolDB`, `LibrarySymbol`, `NamespaceSymbol`, `SymbolDB`, `VariableSymbolDB`

public interface Symbol
Interface for a symbol, which associates a string value with an address.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `delete()`
  Delete the symbol and its associated resources.
  `Address`
  `getAddress()`
  `long`
  `getID()`
  `String`
  `getName()`
  `String`
  `getName(boolean includeNamespace)`
  Returns the symbol name, optionally prepended with the namespace path.
  `Object`
  `getObject()`
  `Namespace`
  `getParentNamespace()`
  Return the parent namespace for this symbol.
  `Symbol`
  `getParentSymbol()`
  Returns namespace symbol of the namespace containing this symbol
  `String[]`
  `getPath()`
  Gets the full path name for this symbol as an ordered array of strings ending with the symbol name.
  `Program`
  `getProgram()`
  Get the program associated with this symbol
  `ProgramLocation`
  `getProgramLocation()`
  `int`
  `getReferenceCount()`
  `Reference[]`
  `getReferences()`
  Returns all memory references to the address of this symbol.
  `Reference[]`
  `getReferences(TaskMonitor monitor)`
  Returns all memory references to the address of this symbol.
  `SourceType`
  `getSource()`
  Gets the source of this symbol.
  `SymbolType`
  `getSymbolType()`
  Returns this symbol's type
  `boolean`
  `hasMultipleReferences()`
  `boolean`
  `hasReferences()`
  `boolean`
  `isDeleted()`
  Determine if this symbol object has been deleted.
  `boolean`
  `isDescendant(Namespace namespace)`
  Returns true if the given namespace symbol is a descendant of this symbol.
  `boolean`
  `isDynamic()`
  `boolean`
  `isExternal()`
  Returns true if this an external symbol.
  `boolean`
  `isExternalEntryPoint()`
  `boolean`
  `isGlobal()`
  `boolean`
  `isPinned()`
  Returns true if the symbol is pinned to its current address.
  `boolean`
  `isPrimary()`
  `boolean`
  `isValidParent(Namespace parent)`
  Determines if the given parent is valid for this Symbol.
  `void`
  `setName(String newName, SourceType source)`
  Sets the name this symbol.
  `void`
  `setNameAndNamespace(String newName, Namespace newNamespace, SourceType source)`
  Sets the symbols name and namespace.
  `void`
  `setNamespace(Namespace newNamespace)`
  Sets the symbols namespace
  `void`
  `setPinned(boolean pinned)`
  Sets whether or not this symbol is pinned to its associated address.
  `boolean`
  `setPrimary()`
  Sets this symbol to be primary.
  `void`
  `setSource(SourceType source)`
  Sets the source of this symbol.

- ## Method Details

  - ### getAddress

    Address getAddress()
    Returns:
      the address for the symbol.

  - ### getName

    String getName()
    Returns:
      the name of this symbol.

  - ### getPath

    String[] getPath()
    Gets the full path name for this symbol as an ordered array of strings ending with the symbol name. The global symbol will return an empty array.
    Returns:
      the array indicating the full path name for this symbol.

  - ### getProgram

    Program getProgram()
    Get the program associated with this symbol
    Returns:
      the program associated with this symbol.

  - ### getName

    String getName(boolean includeNamespace)
    Returns the symbol name, optionally prepended with the namespace path.
    Parameters:
      `includeNamespace` - if true, the namespace path is prepended to the name.
    Returns:
      formatted name

  - ### getParentNamespace

    Namespace getParentNamespace()
    Return the parent namespace for this symbol.
    Returns:
      the namespace that contains this symbol.

  - ### getParentSymbol

    Symbol getParentSymbol()
    Returns namespace symbol of the namespace containing this symbol
    Returns:
      parent namespace symbol

  - ### isDescendant

    boolean isDescendant(Namespace namespace)
    Returns true if the given namespace symbol is a descendant of this symbol.
    Parameters:
      `namespace` - to test as descendant symbol of this Symbol
    Returns:
      true if this symbol is an ancestor of the given namespace symbol

  - ### isValidParent

    boolean isValidParent(Namespace parent)
    Determines if the given parent is valid for this Symbol. Specified namespace must belong to the same symbol table as this symbol.
    Parameters:
      `parent` - prospective parent namespace for this symbol
    Returns:
      true if parent is valid

  - ### getSymbolType

    SymbolType getSymbolType()
    Returns this symbol's type
    Returns:
      symbol type

  - ### getReferenceCount

    int getReferenceCount()
    Returns:
      the number of References to this symbol.

  - ### hasMultipleReferences

    boolean hasMultipleReferences()
    Returns:
      true if this symbol has more than one reference to it.

  - ### hasReferences

    boolean hasReferences()
    Returns:
      true if this symbol has at least one reference to it.

  - ### getReferences

    Reference[] getReferences(TaskMonitor monitor)
    Returns all memory references to the address of this symbol. If you do not have a `TaskMonitor` instance, then you can pass `TaskMonitor.DUMMY` or `null`.
    Parameters:
      `monitor` - the monitor that is used to report progress and to cancel this potentially long-running call
    Returns:
      all memory references to the address of this symbol.

  - ### getReferences

    Reference[] getReferences()
    Returns all memory references to the address of this symbol.
    Returns:
      all memory references to the address of this symbol
    See Also:
      - `getReferences(TaskMonitor)`

  - ### getProgramLocation

    ProgramLocation getProgramLocation()
    Returns:
      a program location corresponding to this symbol

  - ### setName

    void setName(String newName, SourceType source) throws DuplicateNameException, InvalidInputException
    Sets the name this symbol. If this symbol is dynamic, then the name is set and the symbol is no longer dynamic.
    Parameters:
      `newName` - the new name for this symbol.
      `source` - the source of this symbol
      Some symbol types, such as function symbols, can set the source to Symbol.DEFAULT.
    Throws:
      `DuplicateNameException` - if name already exists as the name of another symbol or alias.
      `InvalidInputException` - if alias contains blank characters, is zero length, or is null
      `IllegalArgumentException` - if you try to set the source to DEFAULT for a symbol type that doesn't allow it.

  - ### setNamespace

    void setNamespace(Namespace newNamespace) throws DuplicateNameException, InvalidInputException, CircularDependencyException
    Sets the symbols namespace
    Parameters:
      `newNamespace` - new parent namespace
    Throws:
      `DuplicateNameException` - if newNamespace already contains a symbol with this symbol's name
      `InvalidInputException` - is newNamespace is not a valid parent for this symbol
      `CircularDependencyException` - if this symbol is an ancestor of newNamespace

  - ### setNameAndNamespace

    void setNameAndNamespace(String newName, Namespace newNamespace, SourceType source) throws DuplicateNameException, InvalidInputException, CircularDependencyException
    Sets the symbols name and namespace. This is provided to allow the caller to avoid a name conflict by creating an autonomous action.
    Parameters:
      `newName` - new symbol name
      `newNamespace` - new parent namespace
      `source` - the source of this symbol
      Some symbol types, such as function symbols, can set the source to Symbol.DEFAULT.
    Throws:
      `DuplicateNameException` - if newNamespace already contains a symbol with this symbol's name
      `InvalidInputException` - is newNamespace is not a valid parent for this symbol
      `CircularDependencyException` - if this symbol is an ancestor of newNamespace

  - ### delete

    boolean delete()
    Delete the symbol and its associated resources. Any references symbol associations will be discarded.
    Returns:
      true if successful

  - ### isPinned

    boolean isPinned()
    Returns true if the symbol is pinned to its current address. If it is pinned, then moving or removing the memory associated with that address will not affect this symbol.
    Returns:
      true if the symbol is pinned to its current address.

  - ### setPinned

    void setPinned(boolean pinned)

    Sets whether or not this symbol is pinned to its associated address.

    If the symbol is pinned then moving or removing the memory associated with its address will not cause this symbol to be removed and will not cause its address to change. If the symbol is not pinned, then removing the memory at its address will also remove this symbol.

    Likewise, moving a memory block containing a symbol that is not anchored will change the address for that symbol to keep it associated with the same byte in the memory block.

    Parameters:
      `pinned` - true indicates this symbol is anchored to its address. false indicates this symbol is not anchored to its address.

  - ### isDynamic

    boolean isDynamic()
    Returns:
      true if this symbol is a dynamic symbol (not actually defined in the database).

  - ### isExternal

    boolean isExternal()
    Returns true if this an external symbol.
    Returns:
      true if this an external symbol.
    See Also:
      - `Address.isExternalAddress()`

  - ### isPrimary

    boolean isPrimary()
    Returns:
      true if this symbol is primary

  - ### setPrimary

    boolean setPrimary()
    Sets this symbol to be primary. All other symbols at the same address will be set to !primary. Only applies to non-function symbols.
    Returns:
      returns true if the symbol was not primary and now it is, otherwise false

  - ### isExternalEntryPoint

    boolean isExternalEntryPoint()
    Returns:
      true if the symbol is at an address set as a external entry point.

  - ### getID

    long getID()
    Returns:
      this symbol's ID.

  - ### getObject

    Object getObject()
    Returns:
      object associated with this symbol or null if symbol has been deleted

  - ### isGlobal

    boolean isGlobal()
    Returns:
      true if the symbol is global

  - ### setSource

    void setSource(SourceType source)
    Sets the source of this symbol. `SourceType`
    Parameters:
      `source` - the new source of this symbol

  - ### getSource

    SourceType getSource()
    Gets the source of this symbol. `SourceType`
    Returns:
      the source of this symbol

  - ### isDeleted

    boolean isDeleted()
    Determine if this symbol object has been deleted. NOTE: the symbol could be deleted at anytime due to asynchronous activity.
    Returns:
      true if symbol has been deleted, false if not.