Interface SymbolTable
- All Known Implementing Classes:
SymbolManager
A Symbol is an association between an Address, a String name. In addition, symbols may have one or more References.
A Reference is a 4-tuple of a source address, destination address, type, and either a mnemonic or operand index
Any address in a program can have more than one symbol associated to it. At any given time, one and only one symbol will be designated as the primary.
A symbol can be either global or local. Local symbols belong to some namespace other than the global namespace.
Label and Function symbols do not have to have unique names with a namespace. All other symbols must be unique within a namespace and be unique with all other symbols that must be unique. In other words you can have a several functions named "foo" and several labels named "foo" in the same namespace. But you can't have a class named "foo" and a namespace named "foo". But you can have a class named "foo" and and many functions and labels named "foo" all in the same namespace.
A symbol can also be designated as dynamic. Which means the name is generated on-the-fly by the system based on its context.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addExternalEntryPoint
(Address addr) Sets the given address to be an external entry point.convertNamespaceToClass
(Namespace namespace) Converts the given namespace to a class namespacecreateClass
(Namespace parent, String name, SourceType source) Create a class namespace in the given parent namespace.createExternalLibrary
(String name, SourceType source) Creates a Library namespace with the given name.createLabel
(Address addr, String name, Namespace namespace, SourceType source) Create a label symbol with the given name associated to the given Address and namespace.createLabel
(Address addr, String name, SourceType source) Create a label symbol with the given name associated to the given Address.createNameSpace
(Namespace parent, String name, SourceType source) Creates a new namespace.getAllSymbols
(boolean includeDynamicSymbols) Returns an iterator over all symbols, including Dynamic symbols if includeDynamicSymbols is true.getChildren
(Symbol parentSymbol) Returns an iterator over all symbols that have the given symbol as its parent.Returns all Class Namespaces defined within the program in an arbitrary ordering.getClassSymbol
(String name, Namespace namespace) Returns the class symbol with the given name in the given namespace.Returns an iterator over all defined symbols in no particular order.long
getDynamicSymbolID
(Address addr) Get the unique symbol ID for a dynamic symbol associated with the specified addr.Get forward/back iterator over addresses that are entry points.getExternalSymbol
(String name) Returns the external symbol with the given name.Returns an iterator over all defined external symbols in no particular order.getExternalSymbols
(String name) Returns all the external symbols with the given name.getGlobalSymbol
(String name, Address addr) Get the global symbol with the given name and address.getGlobalSymbols
(String name) Returns a list of all global symbols with the given name.Get an iterator over all the label history objects.getLabelHistory
(Address addr) Get the label history objects for the given address.getLabelOrFunctionSymbols
(String name, Namespace namespace) Returns all the label or function symbols that have the given name in the given namespace.getLibrarySymbol
(String name) Returns the library symbol with the given name.getLocalVariableSymbol
(String name, Namespace namespace) Returns the local variable symbol with the given name in the given namespace.getNamespace
(Address addr) Returns the lowest level Namespace within which the specified address is contained.getNamespace
(String name, Namespace namespace) Returns the namespace with the given name in the given parent namespace.getNamespaceSymbol
(String name, Namespace namespace) Returns a generic namespace symbol with the given name in the given namespace.int
Returns the total number of symbols in the table.getOrCreateNameSpace
(Namespace parent, String name, SourceType source) Gets an existing namespace with the given name in the given parent.getParameterSymbol
(String name, Namespace namespace) Returns the parameter symbol with the given name in the given namespace.getPrimarySymbol
(Address addr) Returns the primary symbol at the specified address.getPrimarySymbolIterator
(boolean forward) Get iterator over all primary symbols.getPrimarySymbolIterator
(Address startAddr, boolean forward) Get iterator over only primary symbols starting at the specifiedstartAddr
getPrimarySymbolIterator
(AddressSetView asv, boolean forward) Get an iterator over symbols at addresses in the given addressSetgetSymbol
(long symbolID) Get the symbol for the given symbol ID.Returns the symbol that this reference is associated with.Get the symbol with the given name, address, and namespace.Get iterator over all label symbols.getSymbolIterator
(boolean forward) Returns an iterator over all symbols.getSymbolIterator
(Address startAddr, boolean forward) Get iterator over all symbols starting at the specifiedstartAddr
getSymbolIterator
(String searchStr, boolean caseSensitive) Returns a an iterator over all symbols that match the given search string.getSymbols
(long namespaceID) Returns an iterator over all the symbols in the given namespaceSymbol[]
getSymbols
(Address addr) Returns all the symbols at the given address.getSymbols
(AddressSetView set, SymbolType type, boolean forward) Returns all the symbols of the given type within the given address set.getSymbols
(Namespace namespace) Returns an iterator over all the symbols in the given namespacegetSymbols
(String name) Returns all the symbols with the given name.getSymbols
(String name, Namespace namespace) Returns a list of all symbols with the given name in the given namespace.getSymbolsAsIterator
(Address addr) Returns a symbol iterator over all the symbols at the given address.Symbol[]
getUserSymbols
(Address addr) Returns an array of all user defined symbols at the given addressgetVariableSymbol
(String name, Function function) Returns a symbol that is either a parameter or local variable.boolean
hasLabelHistory
(Address addr) Return true if there is a history of label changes at the given address.boolean
Return true if there exists a symbol at the given address.boolean
isExternalEntryPoint
(Address addr) Returns true if the given address has been set as an external entry point.void
Removes the given address as an external entry point.boolean
Removes the specified symbol from the symbol table.
-
Method Details
-
createLabel
Create a label symbol with the given name associated to the given Address. The symbol will be global and be of type SymbolType.CODE. Label Symbols do not have to have unique names. If this is the first symbol defined for the address it becomes the primary.- Parameters:
addr
- the address at which to create a symbolname
- the name of the symbol.source
- the source of this symbol
Some symbol types, such as function symbols, can set the source to Symbol.DEFAULT.- Returns:
- new code or function symbol
- Throws:
InvalidInputException
- thrown if names contains white space, is zero length, or is null for non-default source.IllegalArgumentException
- if you try to set the source to DEFAULT for a symbol type that doesn't allow it, or an improper addr is specified
-
createLabel
Symbol createLabel(Address addr, String name, Namespace namespace, SourceType source) throws InvalidInputException Create a label symbol with the given name associated to the given Address and namespace. The symbol will be of type SymbolType.CODE. If this is the first symbol defined for the address it becomes the primary symbol. If a symbol with that name already exists at the address, it will be returned instead with its namespace changed to the new namespace unless the new symbol is in the global space, in which case the namespace will remain as is.- Parameters:
addr
- the address at which to create a symbolname
- the name of the symbol.namespace
- the namespace of the symbol.source
- the source of this symbol
Some symbol types, such as function symbols, can set the source to Symbol.DEFAULT.- Returns:
- new code or function symbol
- Throws:
InvalidInputException
- thrown if names contains white space, is zero length, or is null for non-default source. Also thrown if invalid parentNamespace is specified.IllegalArgumentException
- if you try to set the source to DEFAULT for a symbol type that doesn't allow it, specify an improper addr, or specify a namespace which does not correspond to this symbol table's program.
-
removeSymbolSpecial
Removes the specified symbol from the symbol table. If removing any non-function symbol the behavior will be the same as invokingSymbol.delete()
on the symbol. Use of this method for non-function symbols is discouraged.WARNING! If removing a function symbol the behavior differs from directly invoking
Symbol.delete()
on the function symbol.When removing a function symbol this method has the following behavior:
- If the function is a default symbol (e.g., FUN_12345678) this method has no affect and will return null
- otherwise if another label exists at the function entry point, that label will be removed and the function will be renamed with that labels name
- If no other labels exist at the function entry, the function will be renamed to the default function name
- Parameters:
sym
- the symbol to be removed.- Returns:
- false, if removal of the symbol fails
-
getSymbol
Get the symbol for the given symbol ID.- Parameters:
symbolID
- the id of the symbol to be retrieved.- Returns:
- null if there is no symbol with the given ID.
-
getSymbol
Get the symbol with the given name, address, and namespace.Note that for a symbol to be uniquely specified, all these parameters are required. Any method that queries for symbols using just one or two of these parameters will return a list of symbols. This method will not return a default thunk (i.e., thunk function symbol with default source type) since it mirrors the name and parent namespace of the function it thunks.
- Parameters:
name
- the name of the symbol to retrieveaddr
- the address of the symbol to retrievenamespace
- the namespace of the symbol to retrieve. May be null which indicates global namespace.- Returns:
- the symbol which matches the specified criteria or null if not found
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.- See Also:
-
getGlobalSymbol
Get the global symbol with the given name and address. Note that this results in a single Symbol because of an additional restriction that allows only one symbol with a given name at the same address and namespace (in this case the global namespace).This is just a convenience method for
getSymbol(String, Address, Namespace)
where the namespace is the global namespace.NOTE: This method will not return a default thunk (i.e., thunk function symbol with default source type) since it mirrors the name and parent namespace of the function it thunks.
- Parameters:
name
- the name of the symbol to retrieveaddr
- the address of the symbol to retrieve- Returns:
- the symbol which matches the specified criteria in the global namespace or null if not found
- See Also:
-
getGlobalSymbols
Returns a list of all global symbols with the given name.NOTE: This method will not return default thunks (i.e., thunk function symbol with default source type).
- Parameters:
name
- the name of the symbols to retrieve.- Returns:
- a list of all global symbols with the given name.
-
getLabelOrFunctionSymbols
Returns all the label or function symbols that have the given name in the given namespace.NOTE: This method will not return a default thunk (i.e., thunk function symbol with default source type) since it mirrors the name and parent namespace of the function it thunks.
- Parameters:
name
- the name of the symbols to search for.namespace
- the namespace to search. If null, then the global namespace is assumed.- Returns:
- a list of all the label or function symbols with the given name in the given namespace.
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getNamespaceSymbol
Returns a generic namespace symbol with the given name in the given namespace.- Parameters:
name
- the name of the namespace symbol to retrieve.namespace
- the namespace containing the symbol to retrieve.- Returns:
- a generic namespace symbol with the given name in the given namespace.
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getLibrarySymbol
Returns the library symbol with the given name.- Parameters:
name
- the name of the library symbol to retrieve.- Returns:
- the library symbol with the given name.
-
getClassSymbol
Returns the class symbol with the given name in the given namespace.- Parameters:
name
- the name of the class.namespace
- the namespace to search for the class.- Returns:
- the class symbol with the given name in the given namespace.
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getParameterSymbol
Returns the parameter symbol with the given name in the given namespace.- Parameters:
name
- the name of the parameter.namespace
- the namespace (function) to search for the class.- Returns:
- the parameter symbol with the given name in the given namespace.
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getLocalVariableSymbol
Returns the local variable symbol with the given name in the given namespace.- Parameters:
name
- the name of the local variable.namespace
- the namespace (function) to search for the class.- Returns:
- the local variable symbol with the given name in the given namespace.
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getSymbols
Returns a list of all symbols with the given name in the given namespace.NOTE: The resulting iterator will not return default thunks (i.e., thunk function symbol with default source type).
- Parameters:
name
- the name of the symbols to retrieve.namespace
- the namespace to search for symbols.- Returns:
- all symbols which satisfy specified criteria
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getVariableSymbol
Returns a symbol that is either a parameter or local variable. There can be only one because these symbol types have a unique name requirement.- Parameters:
name
- the name of the variable.function
- the function to search.- Returns:
- a parameter or local variable symbol with the given name.
-
getNamespace
Returns the namespace with the given name in the given parent namespace. The namespace returned can be either a generic namespace or a class or library. It does not include functions.- Parameters:
name
- the name of the namespace to be retrieved.namespace
- the parent namespace of the namespace to be retrieved.- Returns:
- the namespace with the given name in the given parent namespace.
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getSymbols
Returns all the symbols with the given name.NOTE: The resulting iterator will not return default thunks (i.e., thunk function symbol with default source type). It will also not work for default local variables and parameters.
- Parameters:
name
- the name of symbols to search for.- Returns:
- array of symbols with the given name
-
getAllSymbols
Returns an iterator over all symbols, including Dynamic symbols if includeDynamicSymbols is true.- Parameters:
includeDynamicSymbols
- if true, the iterator will include dynamicSymbols- Returns:
- symbol iterator
-
getSymbol
Returns the symbol that this reference is associated with.- Parameters:
ref
- the reference to find the associated symbol for.- Returns:
- referenced symbol
-
getPrimarySymbol
Returns the primary symbol at the specified address. This method will always return null if the address specified is neither a Memory address nor an External address.- Parameters:
addr
- the address at which to retrieve the primary symbol- Returns:
- symbol, or null if no symbol at that address
-
getSymbols
Returns all the symbols at the given address. When addr is a memory address the primary symbol will be returned in array slot 0. WARNING! Use of this method with a Variable address is highly discouraged since a single Variable address could be used multiple times by many functions. Note that unless all the symbols are needed at once, you should consider using thegetSymbolsAsIterator(Address)
method instead.- Parameters:
addr
- the address at which to retrieve all symbols.- Returns:
- a zero-length array when no symbols are defined at address.
- See Also:
-
getSymbolsAsIterator
Returns a symbol iterator over all the symbols at the given address. Use this instead ofgetSymbols(Address)
when you do not need to get all symbols, but rather are searching for a particular symbol. This method prevents all symbols at the given address from being loaded up front.- Parameters:
addr
- the address at which to retrieve all symbols- Returns:
- an iterator over all the symbols at the given address
- See Also:
-
getUserSymbols
Returns an array of all user defined symbols at the given address- Parameters:
addr
- the address at which to retrieve all user defined symbols.- Returns:
- all symbols at specified address
-
getSymbols
Returns an iterator over all the symbols in the given namespaceNOTE: The resulting iterator will not return default thunks (i.e., thunk function symbol with default source type).
- Parameters:
namespace
- the namespace to search for symbols.- Returns:
- symbol iterator
- Throws:
IllegalArgumentException
- amespace which does not correspond to this symbol table's program.
-
getSymbols
Returns an iterator over all the symbols in the given namespaceNOTE: This method will not return a default thunk (i.e., thunk function symbol with default source type).
- Parameters:
namespaceID
- the namespace ID to search for symbols.- Returns:
- symbol iterator
-
hasSymbol
Return true if there exists a symbol at the given address.- Parameters:
addr
- address to check for an existing symbol- Returns:
- true if any symbol exists
-
getDynamicSymbolID
Get the unique symbol ID for a dynamic symbol associated with the specified addr. The generation of this symbol ID does not reflect the presence of a dynamic symbol at the specified addr. This symbol ID should not be permanently stored since the encoding may change between software releases.- Parameters:
addr
- dynamic symbol address- Returns:
- unique symbol ID
-
getSymbolIterator
Returns a an iterator over all symbols that match the given search string.NOTE: The iterator is in the forward direction only and will not return default thunk functions. The resulting iterator will not return default thunks (i.e., thunk function symbol with default source type).
- Parameters:
searchStr
- the string to search for (may contain * to match any sequence or ? to match a single char)caseSensitive
- flag to determine if the search is case sensitive or not.- Returns:
- symbol iterator
-
getSymbols
Returns all the symbols of the given type within the given address set.- Parameters:
set
- the address set in which to look for symbols of the given type (required).type
- the SymbolType to look for.forward
- the direction within the addressSet to search- Returns:
- symbol iterator
-
getNumSymbols
int getNumSymbols()Returns the total number of symbols in the table.- Returns:
- total number of symbols
-
getSymbolIterator
SymbolIterator getSymbolIterator()Get iterator over all label symbols. Labels are defined on memory locations.- Returns:
- symbol iterator
-
getDefinedSymbols
SymbolIterator getDefinedSymbols()Returns an iterator over all defined symbols in no particular order.- Returns:
- symbol iterator
-
getExternalSymbol
Returns the external symbol with the given name.- Parameters:
name
- the name of the symbol to be retrieved.- Returns:
- symbol, or null if no external symbol has that name
-
getExternalSymbols
Returns all the external symbols with the given name.- Parameters:
name
- the name of symbols to search for.- Returns:
- array of external symbols with the given name
-
getExternalSymbols
SymbolIterator getExternalSymbols()Returns an iterator over all defined external symbols in no particular order.- Returns:
- symbol iterator
-
getSymbolIterator
Returns an iterator over all symbols.- Parameters:
forward
- true means the iterator is in the forward direction- Returns:
- symbol iterator
-
getSymbolIterator
Get iterator over all symbols starting at the specifiedstartAddr
- Parameters:
startAddr
- the address at which to begin the iteration.forward
- true means the iterator is in the forward direction- Returns:
- symbol iterator
-
getPrimarySymbolIterator
Get iterator over all primary symbols.- Parameters:
forward
- true means the iterator is in the forward direction- Returns:
- symbol iterator
-
getPrimarySymbolIterator
Get iterator over only primary symbols starting at the specifiedstartAddr
- Parameters:
startAddr
- the address at which to begin the iteration.forward
- true means the iterator is in the forward direction- Returns:
- symbol iterator
-
getPrimarySymbolIterator
Get an iterator over symbols at addresses in the given addressSet- Parameters:
asv
- the set of address over which to iterate symbols (required).forward
- true means the iterator is in the forward direction- Returns:
- symbol iterator
-
addExternalEntryPoint
Sets the given address to be an external entry point.- Parameters:
addr
- the address to set as an external entry point.
-
removeExternalEntryPoint
Removes the given address as an external entry point.- Parameters:
addr
- the address to remove as an external entry point.
-
isExternalEntryPoint
Returns true if the given address has been set as an external entry point.- Parameters:
addr
- address to test for external entry point.- Returns:
- true if specified address has been marked as an entry point, else false
-
getExternalEntryPointIterator
AddressIterator getExternalEntryPointIterator()Get forward/back iterator over addresses that are entry points.- Returns:
- entry-point address iterator
-
getLabelHistory
Get the label history objects for the given address. The history object records changes made to labels at some address.- Parameters:
addr
- address of the label change- Returns:
- array of history objects
-
getLabelHistory
Iterator<LabelHistory> getLabelHistory()Get an iterator over all the label history objects.- Returns:
- label history iterator
-
hasLabelHistory
Return true if there is a history of label changes at the given address.- Parameters:
addr
- the address to check for symbol history.- Returns:
- true if label history exists for specified address, else false
-
getNamespace
Returns the lowest level Namespace within which the specified address is contained.- Parameters:
addr
- the address for which to finds its enclosing namespace.- Returns:
- namespace which contains specified address
-
getClassNamespaces
Iterator<GhidraClass> getClassNamespaces()Returns all Class Namespaces defined within the program in an arbitrary ordering.- Returns:
- iterator of
GhidraClass
-
createClass
GhidraClass createClass(Namespace parent, String name, SourceType source) throws DuplicateNameException, InvalidInputException Create a class namespace in the given parent namespace.- Parameters:
parent
- parent namespace (may be null for global namespace)name
- name of the namespacesource
- the source of this class namespace's symbol- Returns:
- new class namespace
- Throws:
DuplicateNameException
- thrown if another non function or label symbol exists with the given nameInvalidInputException
- throw if the name has invalid characters or is nullIllegalArgumentException
- if you try to set the source to 'Symbol.DEFAULT' or specify a parent Namespace which does not correspond to this symbol table's program.
-
getChildren
Returns an iterator over all symbols that have the given symbol as its parent.NOTE: The resulting iterator will not return default thunks (i.e., thunk function symbol with default source type).
- Parameters:
parentSymbol
- the parent symbol- Returns:
- symbol iterator
-
createExternalLibrary
Library createExternalLibrary(String name, SourceType source) throws DuplicateNameException, InvalidInputException Creates a Library namespace with the given name.- Parameters:
name
- the name of the new Library namespacesource
- the source of this external library's symbol- Returns:
- the new Library namespace.
- Throws:
InvalidInputException
- if the name is invalid.IllegalArgumentException
- if you try to set the source to 'Symbol.DEFAULT'.DuplicateNameException
- thrown if another non function or label symbol exists with the given name
-
createNameSpace
Namespace createNameSpace(Namespace parent, String name, SourceType source) throws DuplicateNameException, InvalidInputException Creates a new namespace.- Parameters:
parent
- the parent namespace for the new namespace (may be null for global namespace)name
- the name of the new namespacesource
- the source of this namespace's symbol- Returns:
- the new Namespace object.
- Throws:
DuplicateNameException
- thrown if another non function or label symbol exists with the given nameInvalidInputException
- if the name is invalid.IllegalArgumentException
- if you try to set the source to 'Symbol.DEFAULT' or specify a parent Namespace which does not correspond to this symbol table's program.
-
convertNamespaceToClass
Converts the given namespace to a class namespace- Parameters:
namespace
- the namespace to convert- Returns:
- the new class
- Throws:
IllegalArgumentException
- if the given parent namespace is from a different program than that of this symbol tableConcurrentModificationException
- if the given parent namespace has been deletedIllegalArgumentException
- namespace does not correspond to this symbol table's program or namespace not allowed (e.g., global or library namespace).
-
getOrCreateNameSpace
Namespace getOrCreateNameSpace(Namespace parent, String name, SourceType source) throws DuplicateNameException, InvalidInputException Gets an existing namespace with the given name in the given parent. If no namespace exists, then one will be created.- Parameters:
parent
- the parent namespacename
- the namespace namesource
- the source type for the namespace if one is created- Returns:
- the namespace
- Throws:
DuplicateNameException
- thrown if another non function or label symbol exists with the given nameInvalidInputException
- if the name is invalidIllegalArgumentException
- if the given parent namespace is from a different program than that of this symbol tableConcurrentModificationException
- if the given parent namespace has been deleted
-