ReferenceManager API

API reference for managing references in Ghidra programs

Overview

The ReferenceManager interface provides methods for creating, retrieving, and managing references between code units in a Ghidra program. References include memory references, stack references, register references, and external references.

Interface

Package: ghidra.program.model.symbol
Location: Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/symbol/ReferenceManager.java

public interface ReferenceManager

Constants

MNEMONIC

Operand index which corresponds to the instruction/data mnemonic.

public static final int MNEMONIC = Reference.MNEMONIC;

Adding References

addReference()

Adds a memory, stack, register, or external reference.

public Reference addReference(Reference reference);

Parameters:

• reference - Reference to be added

Returns: New reference

---

addMemoryReference()

Adds a memory reference. The first memory reference on an operand becomes primary by default.

public Reference addMemoryReference(Address fromAddr, Address toAddr, RefType type,
        SourceType source, int opIndex);

Parameters:

• fromAddr - Address of the code unit where the reference occurs
• toAddr - Address of the location being referenced (memory, stack, or register)
• type - Reference type (how the location is being referenced)
• source - The source of this reference (e.g., SourceType.USER_DEFINED, SourceType.ANALYSIS)
• opIndex - The operand index

Returns: New memory reference

Throws: IllegalArgumentException if unsupported RefType is specified

All non-memory references will be removed from the specified operand.

---

addOffsetMemReference()

Adds an offset memory reference.

public Reference addOffsetMemReference(Address fromAddr, Address toAddr, boolean toAddrIsBase,
        long offset, RefType type, SourceType source, int opIndex);

Parameters:

• fromAddr - Address for the “from” location
• toAddr - Address of the location being referenced
• toAddrIsBase - If true, toAddr is treated as base address; else treated as (base+offset)
• offset - Value added to a base address to get the toAddr
• type - Reference type
• source - The source of this reference
• opIndex - The operand index

Returns: New offset reference

---

addShiftedMemReference()

Adds a shifted memory reference where the “to” address is computed as a value shifted by some number of bits.

public Reference addShiftedMemReference(Address fromAddr, Address toAddr, int shiftValue,
        RefType type, SourceType source, int opIndex);

Parameters:

• fromAddr - Source/from memory address
• toAddr - Destination/to memory address
• shiftValue - Number of bits to shift
• type - Reference type
• source - The source of this reference
• opIndex - The operand index

Returns: New shifted reference

---

addStackReference()

Adds a reference to a stack location.

public Reference addStackReference(Address fromAddr, int opIndex, int stackOffset, RefType type,
        SourceType source);

Parameters:

• fromAddr - “From” address within a function
• opIndex - Operand index
• stackOffset - Stack offset of the reference
• type - Reference type
• source - The source of this reference

Returns: New stack reference

If a reference already exists for the fromAddr and opIndex, it will be replaced.

---

addRegisterReference()

Adds a reference to a register.

public Reference addRegisterReference(Address fromAddr, int opIndex, Register register,
        RefType type, SourceType source);

Parameters:

• fromAddr - “From” address
• opIndex - Operand index
• register - Register to add the reference to
• type - Reference type
• source - The source of this reference

Returns: New register reference

---

addExternalReference() - By Library Name

Adds an external reference to an external symbol by library name.

public Reference addExternalReference(Address fromAddr, String libraryName, String extLabel,
        Address extAddr, SourceType source, int opIndex, RefType type)
        throws InvalidInputException, DuplicateNameException;

Parameters:

• fromAddr - From memory address (source of the reference)
• libraryName - Name of external program
• extLabel - Label within the external program (may be null if extAddr is not null)
• extAddr - Memory address within the external program (may be null)
• source - The source of this reference
• opIndex - Operand index
• type - Reference type

Returns: New external space reference

Throws:

• InvalidInputException - If libraryName is invalid or null, or invalid extLabel specified
• DuplicateNameException - If another non-Library namespace has the same name
• IllegalArgumentException - If invalid extAddr was specified

---

addExternalReference() - By Namespace

Adds an external reference using an external namespace.

public Reference addExternalReference(Address fromAddr, Namespace extNamespace, String extLabel,
        Address extAddr, SourceType source, int opIndex, RefType type)
        throws InvalidInputException, DuplicateNameException;

Parameters:

• fromAddr - From memory address
• extNamespace - External namespace containing the named external label
• extLabel - Label within the external program (may be null if extAddr is not null)
• extAddr - Address within the external program (may be null)
• source - The source of this reference
• opIndex - Operand index
• type - Reference type

Returns: New external space reference

Throws:

• InvalidInputException - If invalid extLabel specified
• DuplicateNameException - If another non-Library namespace has the same name
• IllegalArgumentException - If invalid extAddr was specified

---

addExternalReference() - By External Location

Adds an external reference using an ExternalLocation object.

public Reference addExternalReference(Address fromAddr, int opIndex, ExternalLocation location,
        SourceType source, RefType type) throws InvalidInputException;

Parameters:

• fromAddr - From memory address
• opIndex - Operand index
• location - External location
• source - The source of this reference
• type - Reference type

Returns: External reference

Throws: InvalidInputException if the input is invalid

---

Removing References

removeAllReferencesFrom() - Address Range

Removes all references where “from address” is in the given range.

public void removeAllReferencesFrom(Address beginAddr, Address endAddr);

Parameters:

• beginAddr - The first address in the range
• endAddr - The last address in the range

---

removeAllReferencesFrom() - Single Address

Removes all stack, external, and memory references from the given address.

public void removeAllReferencesFrom(Address fromAddr);

Parameters:

• fromAddr - The address of the code unit from which to remove all references

---

removeAllReferencesTo()

Removes all stack, external, and memory references to the given address.

public void removeAllReferencesTo(Address toAddr);

Parameters:

• toAddr - The address for which all references to should be removed

---

delete()

Deletes the given reference object.

public void delete(Reference ref);

Parameters:

• ref - The reference to be deleted

---

Retrieving References

getReference()

Returns the reference with the given from and to addresses and operand index.

public Reference getReference(Address fromAddr, Address toAddr, int opIndex);

Parameters:

• fromAddr - The address of the code unit making the reference
• toAddr - The address being referred to
• opIndex - The operand index

Returns: Reference which satisfies the criteria or null

---

getReferencesFrom() - All References

Returns all references “from” the specified address.

public Reference[] getReferencesFrom(Address addr);

Parameters:

• addr - Address of code-unit making the references

Returns: Array of all references “from” the specified address

---

getReferencesFrom() - By Operand

Returns all references “from” the given fromAddr and operand.

public Reference[] getReferencesFrom(Address fromAddr, int opIndex);

Parameters:

• fromAddr - The address from which to get references
• opIndex - The operand from which to get references

Returns: All references from the given fromAddr and operand

---

getReferencesTo() - Address

Returns an iterator over all references that have the given address as their “to” address.

public ReferenceIterator getReferencesTo(Address addr);

Parameters:

• addr - The address that all references in the iterator refer to

Returns: Reference iterator over all references to the specified address

---

getReferencesTo() - Variable

Returns all references to the given variable.

public Reference[] getReferencesTo(Variable var);

Parameters:

• var - Variable to retrieve references to

Returns: Array of variable references, or zero-length array if no references exist

Only data references to storage are considered.

---

getFlowReferencesFrom()

Returns all flow references from the given address.

public Reference[] getFlowReferencesFrom(Address addr);

Parameters:

• addr - The address of the code unit to get all flows from

Returns: All flow references from the given address

---

getExternalReferences()

Returns an iterator over all external space references.

public ReferenceIterator getExternalReferences();

Returns: Reference iterator over all external space references

---

getPrimaryReferenceFrom()

Returns the primary reference from the given address and operand index.

public Reference getPrimaryReferenceFrom(Address addr, int opIndex);

Parameters:

• addr - From address
• opIndex - Operand index

Returns: The primary reference from the specified address and opIndex, or null

---

Reference Iterators

getReferenceIterator()

Returns a forward iterator over references starting with the specified fromAddr.

public ReferenceIterator getReferenceIterator(Address startAddr);

Parameters:

• startAddr - The first from address to consider

Returns: A forward memory reference iterator

---

getReferenceSourceIterator() - Starting Address

Returns an iterator over addresses that are the “from” address in a reference.

public AddressIterator getReferenceSourceIterator(Address startAddr, boolean forward);

Parameters:

• startAddr - Address to position iterator
• forward - true to iterate in forward direction

Returns: Address iterator where references from exist

---

getReferenceSourceIterator() - Address Set

Returns an iterator over “from” addresses restricted by the given address set.

public AddressIterator getReferenceSourceIterator(AddressSetView addrSet, boolean forward);

Parameters:

• addrSet - The set of addresses to restrict the iterator (or null for all addresses)
• forward - true to iterate in forward direction

Returns: Address iterator where references from exist constrained by addrSet

---

getReferenceDestinationIterator() - Starting Address

Returns an iterator over addresses that are the “to” address in a reference.

public AddressIterator getReferenceDestinationIterator(Address startAddr, boolean forward);

Parameters:

• startAddr - Start of iterator
• forward - true to iterate in forward direction

Returns: Address iterator where references to exist

---

getReferenceDestinationIterator() - Address Set

Returns an iterator over “to” addresses restricted by the given address set.

public AddressIterator getReferenceDestinationIterator(AddressSetView addrSet, boolean forward);

Parameters:

• addrSet - The set of addresses to restrict the iterator (or null for all addresses)
• forward - true to iterate in forward direction

Returns: Address iterator where references to exist constrained by addrSet

---

Query Methods

hasReferencesFrom() - By Operand

Checks if there are any memory references at the given address and operand index.

public boolean hasReferencesFrom(Address fromAddr, int opIndex);

Parameters:

• fromAddr - The address of the code unit being tested
• opIndex - The index of the operand being tested

Returns: true if one or more references are defined

This is a rather inefficient method as it must examine all references from the specified fromAddr.

---

hasReferencesFrom() - Address

Checks if there are any memory references at the given address.

public boolean hasReferencesFrom(Address fromAddr);

Parameters:

• fromAddr - The address of the code unit being tested

Returns: true if one or more references are defined

---

hasReferencesTo()

Checks if a memory reference exists with the given “to” address.

public boolean hasReferencesTo(Address toAddr);

Parameters:

• toAddr - Address being referred to

Returns: true if specified toAddr has one or more references to it

---

hasFlowReferencesFrom()

Checks if the given address has flow references from it.

public boolean hasFlowReferencesFrom(Address addr);

Parameters:

• addr - The address to test for flow references

Returns: true if the address has flow references from it

---

Reference Counts

getReferenceCountTo()

Returns the number of references to the specified address.

public int getReferenceCountTo(Address toAddr);

Parameters:

• toAddr - The address being referenced

Returns: The number of references to the specified address

---

getReferenceCountFrom()

Returns the number of references from the specified address.

public int getReferenceCountFrom(Address fromAddr);

Parameters:

• fromAddr - The address of the code unit making the reference

Returns: The number of references from the specified address

---

getReferenceDestinationCount()

Returns the number of references for “to” addresses.

public int getReferenceDestinationCount();

Returns: The total number of reference destinations

---

getReferenceSourceCount()

Returns the number of references for “from” addresses.

public int getReferenceSourceCount();

Returns: The total number of reference sources

---

Modifying References

setPrimary()

Sets the reference’s primary attribute.

public void setPrimary(Reference ref, boolean isPrimary);

Parameters:

• ref - The reference to modify
• isPrimary - true to make the reference primary, false to make it non-primary

---

updateRefType()

Updates the reference type on a memory reference.

public Reference updateRefType(Reference ref, RefType refType);

Parameters:

• ref - Reference to be updated
• refType - New reference type

Returns: Updated reference

---

setAssociation()

Associates the given reference with the given symbol.

public void setAssociation(Symbol s, Reference ref);

Parameters:

• s - The symbol to associate with the given reference
• ref - The reference to associate with the given symbol

Throws: IllegalArgumentException if the reference doesn’t exist or its “to” address doesn’t match the symbol’s address

Applies to memory references only where a specified label symbol must have an address matching the reference to-address. Stack and register reference associations to variable symbols are always inferred.

---

removeAssociation()

Removes any symbol associations with the given reference.

public void removeAssociation(Reference ref);

Parameters:

• ref - The reference for which any symbol association is to be removed

Throws: IllegalArgumentException if the reference doesn’t exist

---

Variable Methods

getReferencedVariable()

Returns the referenced function variable.

public Variable getReferencedVariable(Reference reference);

Parameters:

• reference - Variable reference

Returns: Function variable or null if variable not found

---

getReferenceLevel()

Returns the reference level for references to the given address.

public byte getReferenceLevel(Address toAddr);

Parameters:

• toAddr - The address at which to find the highest reference level

Returns: Reference level for specified to address

---

Usage Examples

Adding Memory References

import ghidra.program.model.symbol.*;
import ghidra.program.model.address.*;
import ghidra.program.model.listing.Program;

public void addMemoryRef(Program program) {
    ReferenceManager refMgr = program.getReferenceManager();
    
    try {
        Address fromAddr = program.getAddressFactory().getAddress("0x401000");
        Address toAddr = program.getAddressFactory().getAddress("0x402000");
        
        // Add a data reference
        Reference ref = refMgr.addMemoryReference(
            fromAddr,
            toAddr,
            RefType.DATA,
            SourceType.USER_DEFINED,
            0  // operand index
        );
        
        System.out.println("Created reference: " + ref);
        
    } catch (Exception e) {
        e.printStackTrace();
    }
}

Adding External References

import ghidra.util.exception.*;

public void addExternalRef(Program program) {
    ReferenceManager refMgr = program.getReferenceManager();
    
    try {
        Address fromAddr = program.getAddressFactory().getAddress("0x401050");
        
        // Add reference to external function
        Reference ref = refMgr.addExternalReference(
            fromAddr,
            "KERNEL32.DLL",      // library name
            "CreateFileA",        // external label
            null,                 // external address (optional)
            SourceType.USER_DEFINED,
            0,                    // operand index
            RefType.UNCONDITIONAL_CALL
        );
        
        System.out.println("Created external reference: " + ref);
        
    } catch (InvalidInputException e) {
        System.err.println("Invalid input: " + e.getMessage());
    } catch (DuplicateNameException e) {
        System.err.println("Duplicate name: " + e.getMessage());
    }
}

Querying References

public void analyzeReferences(Program program, Address addr) {
    ReferenceManager refMgr = program.getReferenceManager();
    
    // Get all references FROM an address
    Reference[] refsFrom = refMgr.getReferencesFrom(addr);
    System.out.println("References from " + addr + ": " + refsFrom.length);
    
    for (Reference ref : refsFrom) {
        System.out.println("  -> " + ref.getToAddress() + 
                         " (" + ref.getReferenceType() + ")");
    }
    
    // Get all references TO an address
    ReferenceIterator refsTo = refMgr.getReferencesTo(addr);
    System.out.println("\nReferences to " + addr + ":");
    
    while (refsTo.hasNext()) {
        Reference ref = refsTo.next();
        System.out.println("  <- " + ref.getFromAddress() +
                         " (" + ref.getReferenceType() + ")");
    }
    
    // Check reference counts
    int countFrom = refMgr.getReferenceCountFrom(addr);
    int countTo = refMgr.getReferenceCountTo(addr);
    System.out.println("\nCounts: from=" + countFrom + ", to=" + countTo);
}

Iterating Over All References

public void scanAllReferences(Program program) {
    ReferenceManager refMgr = program.getReferenceManager();
    
    // Get iterator starting from first address
    Address startAddr = program.getMinAddress();
    AddressIterator iter = refMgr.getReferenceSourceIterator(startAddr, true);
    
    System.out.println("Addresses with references:");
    int count = 0;
    
    while (iter.hasNext()) {
        Address addr = iter.next();
        Reference[] refs = refMgr.getReferencesFrom(addr);
        System.out.println(addr + ": " + refs.length + " reference(s)");
        count++;
    }
    
    System.out.println("\nTotal addresses with references: " + count);
    System.out.println("Total reference sources: " + 
                     refMgr.getReferenceSourceCount());
    System.out.println("Total reference destinations: " + 
                     refMgr.getReferenceDestinationCount());
}

Working with Flow References

public void analyzeFlowReferences(Program program, Address addr) {
    ReferenceManager refMgr = program.getReferenceManager();
    
    if (refMgr.hasFlowReferencesFrom(addr)) {
        Reference[] flowRefs = refMgr.getFlowReferencesFrom(addr);
        
        System.out.println("Flow references from " + addr + ":");
        for (Reference ref : flowRefs) {
            System.out.println("  " + ref.getReferenceType() + 
                             " -> " + ref.getToAddress());
            
            if (ref.isPrimary()) {
                System.out.println("    (PRIMARY)");
            }
        }
    }
}

See Also

• Function Manager - Managing functions in a program
• Analyzers - Creating custom analyzers
• Decompiler - Decompiling functions