Symbol Table API

Interface for managing symbols, labels, and references in a Ghidra program

The SymbolTable manages the symbols defined in a program. A symbol is an association between an address and a string name, optionally within a namespace.

Overview

The Symbol Table provides:

• Symbol Management - Create, retrieve, and delete symbols
• Labels - Named locations in memory
• Functions - Function symbols and signatures
• Namespaces - Hierarchical organization
• References - Cross-references between symbols
• External Symbols - Symbols from external libraries

Key Concepts

Symbol Types

• Label - Simple named location
• Function - Function entry point
• Parameter - Function parameter
• Local Variable - Function local variable
• Class - Class namespace
• Namespace - Generic namespace
• Library - External library

Primary vs Non-Primary

Any address can have multiple symbols. One symbol is designated as the primary symbol, which is the default symbol displayed for that address.

Global vs Local

Symbols can be global (in the global namespace) or local (in another namespace like a function or class).

Dynamic Symbols

Dynamic symbols are generated automatically by the system based on context (e.g., FUN_00401000 for unnamed functions).

Creating Symbols

Create Labels

createLabel(Address addr, String name, SourceType source) · Symbol

Creates a label in the global namespace.

Symbol symbol = symbolTable.createLabel(
    addr("00401000"),
    "main",
    SourceType.USER_DEFINED
);
println("Created symbol: " + symbol.getName());

createLabel(Address addr, String name, Namespace namespace, SourceType source) · Symbol

Creates a label in a specific namespace.

Namespace myClass = symbolTable.createClass(null, "MyClass", SourceType.USER_DEFINED);
Symbol method = symbolTable.createLabel(
    addr("00402000"),
    "doSomething",
    myClass,
    SourceType.USER_DEFINED
);

Source Types

• SourceType.USER_DEFINED - Created by the user
• SourceType.IMPORTED - Imported from external source
• SourceType.ANALYSIS - Created by analysis
• SourceType.DEFAULT - System-generated default symbol

Retrieving Symbols

Get by ID

getSymbol(long symbolID) · Symbol

Returns the symbol with the specified ID.

Symbol symbol = symbolTable.getSymbol(symbolID);

Get by Address

getPrimarySymbol(Address addr) · Symbol

Returns the primary symbol at the specified address.

Symbol symbol = symbolTable.getPrimarySymbol(addr);
if (symbol != null) {
    println("Primary symbol at " + addr + ": " + symbol.getName());
}

getSymbols(Address addr) · Symbol[]

Returns all symbols at the specified address.

Symbol[] symbols = symbolTable.getSymbols(addr);
for (Symbol symbol : symbols) {
    println("  " + symbol.getName() + " [" + symbol.getSymbolType() + "]");
}

The primary symbol is at index 0 in the array.

getSymbolsAsIterator(Address addr) · SymbolIterator

Returns an iterator over symbols at the address (excludes dynamic symbols).

Use this instead of getSymbols() when searching for a specific symbol to avoid loading all symbols.

getUserSymbols(Address addr) · Symbol[]

Returns defined symbols at the address (excludes dynamic symbols).

Get by Name

getSymbol(String name, Address addr, Namespace namespace) · Symbol

Returns the symbol with the specified name, address, and namespace.

Symbol symbol = symbolTable.getSymbol("main", addr, globalNamespace);

All three parameters are required to uniquely identify a symbol.

getGlobalSymbol(String name, Address addr) · Symbol

Returns the global symbol with the specified name and address.

Symbol symbol = symbolTable.getGlobalSymbol("main", addr("00401000"));

getGlobalSymbols(String name) · List<Symbol>

Returns all global symbols with the specified name.

List<Symbol> symbols = symbolTable.getGlobalSymbols("printf");
for (Symbol symbol : symbols) {
    println("printf at " + symbol.getAddress());
}

getLabelOrFunctionSymbols(String name, Namespace namespace) · List<Symbol>

Returns all label or function symbols with the specified name in the namespace.

List<Symbol> symbols = symbolTable.getLabelOrFunctionSymbols("method", myClass);

Get by Reference

getSymbol(Reference ref) · Symbol

Returns the symbol associated with a reference.

Reference ref = refMgr.getReference(fromAddr, toAddr, 0);
Symbol symbol = symbolTable.getSymbol(ref);

Iterating Symbols

All Symbols

getAllSymbols(boolean includeDynamicSymbols) · SymbolIterator

Returns an iterator over all symbols.

SymbolIterator iter = symbolTable.getAllSymbols(false);
while (iter.hasNext()) {
    Symbol symbol = iter.next();
    println(symbol.getName() + " @ " + symbol.getAddress());
}

getSymbolIterator() · SymbolIterator

Returns an iterator over all label symbols.

getDefinedSymbols() · SymbolIterator

Returns an iterator over all defined symbols (excludes dynamic labels).

By Name

getSymbols(String name) · SymbolIterator

Returns an iterator over all symbols with the specified name.

SymbolIterator iter = symbolTable.getSymbols("strcmp");
while (iter.hasNext()) {
    Symbol symbol = iter.next();
    println("Found strcmp at " + symbol.getAddress());
}

getSymbolIterator(String searchStr, boolean caseSensitive) · SymbolIterator

Returns symbols matching a wildcard query (* and ? supported).

// Find all symbols starting with "str"
SymbolIterator iter = symbolTable.getSymbolIterator("str*", true);
while (iter.hasNext()) {
    Symbol symbol = iter.next();
    println(symbol.getName());
}

scanSymbolsByName(String startName) · SymbolIterator

Returns symbols in lexicographical order starting from the specified name.

By Namespace

getSymbols(Namespace namespace) · SymbolIterator

Returns all symbols in the specified namespace.

SymbolIterator iter = symbolTable.getSymbols(myClass);
while (iter.hasNext()) {
    Symbol symbol = iter.next();
    println("  " + symbol.getName());
}

getSymbols(String name, Namespace namespace) · List<Symbol>

Returns symbols with the specified name in the namespace.

By Type

getSymbols(AddressSetView addressSet, SymbolType type, boolean forward) · SymbolIterator

Returns symbols of the specified type within the address set.

AddressSet set = new AddressSet(startAddr, endAddr);
SymbolIterator iter = symbolTable.getSymbols(
    set,
    SymbolType.FUNCTION,
    true
);

By Address

getSymbolIterator(boolean forward) · SymbolIterator

Returns symbols in address order.

getSymbolIterator(Address startAddr, boolean forward) · SymbolIterator

Returns symbols starting from the specified address.

getPrimarySymbolIterator(boolean forward) · SymbolIterator

Returns primary symbols in address order.

SymbolIterator iter = symbolTable.getPrimarySymbolIterator(true);
while (iter.hasNext()) {
    Symbol symbol = iter.next();
    println(symbol.getAddress() + ": " + symbol.getName());
}

getPrimarySymbolIterator(AddressSetView addressSet, boolean forward) · SymbolIterator

Returns primary symbols within the address set.

Removing Symbols

removeSymbolSpecial(Symbol sym) · boolean

Removes the specified symbol.

For non-function symbols, behaves the same as Symbol.delete().

For function symbols:

• Default function symbols (e.g., FUN_12345678) are not removed
• If no other labels exist at the entry point, function is renamed to default
• If another label exists, that label is removed and function is renamed to it

Symbol symbol = symbolTable.getGlobalSymbol("oldLabel", addr);
if (symbol != null) {
    symbolTable.removeSymbolSpecial(symbol);
}

Namespace Management

Create Namespaces

createNameSpace(Namespace parent, String name, SourceType source) · Namespace

Creates a new generic namespace.

Namespace ns = symbolTable.createNameSpace(
    null,  // global namespace
    "MyNamespace",
    SourceType.USER_DEFINED
);

createClass(Namespace parent, String name, SourceType source) · GhidraClass

Creates a new class namespace.

GhidraClass myClass = symbolTable.createClass(
    null,
    "MyClass",
    SourceType.USER_DEFINED
);

// Add members to the class
symbolTable.createLabel(
    addr("00402000"),
    "member",
    myClass,
    SourceType.USER_DEFINED
);

createExternalLibrary(String name, SourceType source) · Library

Creates a new external library namespace.

Library lib = symbolTable.createExternalLibrary(
    "kernel32.dll",
    SourceType.IMPORTED
);

Get Namespaces

getNamespace(String name, Namespace namespace) · Namespace

Returns the namespace with the specified name in the parent namespace.

getNamespace(Address addr) · Namespace

Returns the deepest namespace containing the specified address.

getOrCreateNameSpace(Namespace parent, String name, SourceType source) · Namespace

Gets or creates a namespace.

Namespace ns = symbolTable.getOrCreateNameSpace(
    null,
    "Utils",
    SourceType.USER_DEFINED
);

Namespace Queries

getNamespaceSymbol(String name, Namespace namespace) · Symbol

Returns the generic namespace symbol.

getClassSymbol(String name, Namespace namespace) · Symbol

Returns the class symbol.

getLibrarySymbol(String name) · Symbol

Returns the library symbol.

getClassNamespaces() · Iterator<GhidraClass>

Returns an iterator over all class namespaces.

Iterator<GhidraClass> iter = symbolTable.getClassNamespaces();
while (iter.hasNext()) {
    GhidraClass cls = iter.next();
    println("Class: " + cls.getName());
}

External Symbols

getExternalSymbols() · SymbolIterator

Returns all external symbols.

SymbolIterator iter = symbolTable.getExternalSymbols();
while (iter.hasNext()) {
    Symbol symbol = iter.next();
    println("External: " + symbol.getName());
}

getExternalSymbol(String name) · Symbol

Returns the first external symbol with the specified name.

getExternalSymbols(String name) · SymbolIterator

Returns all external symbols with the specified name.

Entry Points

addExternalEntryPoint(Address addr) · void

Adds an address to the external entry points.

symbolTable.addExternalEntryPoint(addr("00401000"));

removeExternalEntryPoint(Address addr) · void

Removes an address from the external entry points.

isExternalEntryPoint(Address addr) · boolean

Checks if the address is an external entry point.

if (symbolTable.isExternalEntryPoint(addr)) {
    println(addr + " is an entry point");
}

getExternalEntryPointIterator() · AddressIterator

Returns an iterator over all external entry point addresses.

Label History

getLabelHistory(Address addr) · LabelHistory[]

Returns the label history for the specified address.

LabelHistory[] history = symbolTable.getLabelHistory(addr);
for (LabelHistory h : history) {
    println(h.getModificationDate() + ": " + h.getLabelString());
}

getLabelHistory() · Iterator<LabelHistory>

Returns an iterator over the complete label history.

hasLabelHistory(Address addr) · boolean

Checks if there is label history at the address.

Symbol Queries

hasSymbol(Address addr) · boolean

Checks if any symbol exists at the address.

if (symbolTable.hasSymbol(addr)) {
    Symbol symbol = symbolTable.getPrimarySymbol(addr);
    println("Symbol: " + symbol.getName());
}

getNumSymbols() · int

Returns the total number of symbols.

int numSymbols = symbolTable.getNumSymbols();
println("Total symbols: " + numSymbols);

getDynamicSymbolID(Address addr) · long

Returns the unique symbol ID for a dynamic symbol at the address.

This ID should not be permanently stored as the encoding may change between releases.

Example Usage

Creating and Managing Symbols

public void manageSymbols(Program program) throws Exception {
    SymbolTable symbolTable = program.getSymbolTable();
    
    // Create a label
    Symbol mainSymbol = symbolTable.createLabel(
        addr("00401000"),
        "main",
        SourceType.USER_DEFINED
    );
    
    // Create a class and add members
    GhidraClass myClass = symbolTable.createClass(
        null,
        "MyClass",
        SourceType.USER_DEFINED
    );
    
    Symbol method = symbolTable.createLabel(
        addr("00402000"),
        "doSomething",
        myClass,
        SourceType.USER_DEFINED
    );
    
    println("Created method: " + method.getName(true));
    // Output: MyClass::doSomething
}

Searching for Symbols

public void findSymbols(Program program) {
    SymbolTable symbolTable = program.getSymbolTable();
    
    // Find all symbols matching a pattern
    SymbolIterator iter = symbolTable.getSymbolIterator("str*", true);
    while (iter.hasNext()) {
        Symbol symbol = iter.next();
        println(symbol.getName() + " @ " + symbol.getAddress());
    }
    
    // Find all functions
    SymbolIterator funcIter = symbolTable.getSymbols(
        program.getMemory(),
        SymbolType.FUNCTION,
        true
    );
    while (funcIter.hasNext()) {
        Symbol funcSymbol = funcIter.next();
        println("Function: " + funcSymbol.getName());
    }
}

Analyzing Symbol Usage

public void analyzeSymbolReferences(Program program, Address addr) {
    SymbolTable symbolTable = program.getSymbolTable();
    ReferenceManager refMgr = program.getReferenceManager();
    
    Symbol symbol = symbolTable.getPrimarySymbol(addr);
    if (symbol != null) {
        println("Symbol: " + symbol.getName());
        println("Type: " + symbol.getSymbolType());
        println("Namespace: " + symbol.getParentNamespace().getName());
        
        // Get references TO this symbol
        Reference[] refs = refMgr.getReferencesTo(addr);
        println("References to " + symbol.getName() + ": " + refs.length);
        
        for (Reference ref : refs) {
            println("  From: " + ref.getFromAddress());
        }
    }
}

Package Location

ghidra.program.model.symbol.SymbolTable

Related Interfaces

• Symbol - Symbol operations
• Namespace - Namespace interface
• ReferenceManager - Reference management