Listing API

Interface for creating, deleting, and retrieving code units, instructions, and data

The Listing interface provides all the methods needed to create, delete, retrieve, and modify code level constructs including CodeUnits, Instructions, Data, and Functions.

Overview

The Listing is the central component for working with disassembled code and data. It provides:

• Code Units - Instructions, defined data, and undefined data
• Instructions - Disassembled processor instructions
• Data - Typed data elements
• Functions - Function creation and management
• Comments - Code annotations

Code Unit Access

Get Code Units

getCodeUnitAt(Address addr) · CodeUnit

Returns the code unit that starts at the given address.

CodeUnit cu = listing.getCodeUnitAt(addr);
if (cu != null) {
    println(cu.getMnemonicString());
}

getCodeUnitContaining(Address addr) · CodeUnit

Returns the code unit that contains the given address.

CodeUnit cu = listing.getCodeUnitContaining(addr);

getCodeUnitAfter(Address addr) · CodeUnit

Returns the next code unit starting after the given address.

getCodeUnitBefore(Address addr) · CodeUnit

Returns the previous code unit starting before the given address.

Iterate Code Units

getCodeUnits(boolean forward) · CodeUnitIterator

Returns an iterator over all code units in the program.

CodeUnitIterator iter = listing.getCodeUnits(true);
while (iter.hasNext()) {
    CodeUnit cu = iter.next();
    // Process code unit
}

getCodeUnits(Address addr, boolean forward) · CodeUnitIterator

Returns an iterator starting at the specified address.

getCodeUnits(AddressSetView addrSet, boolean forward) · CodeUnitIterator

Returns an iterator over code units within the given address set.

Instruction Access

Get Instructions

getInstructionAt(Address addr) · Instruction

Returns the instruction that starts at the given address, or null if none exists.

Instruction inst = listing.getInstructionAt(addr);
if (inst != null) {
    String mnemonic = inst.getMnemonicString();
    int numOperands = inst.getNumOperands();
}

getInstructionContaining(Address addr) · Instruction

Returns the instruction that contains the given address.

getInstructionAfter(Address addr) · Instruction

Returns the next instruction after the given address.

getInstructionBefore(Address addr) · Instruction

Returns the previous instruction before the given address.

Iterate Instructions

getInstructions(boolean forward) · InstructionIterator

Returns an iterator over all instructions in the program.

InstructionIterator iter = listing.getInstructions(true);
while (iter.hasNext()) {
    Instruction inst = iter.next();
    println(inst.getAddress() + ": " + inst);
}

getInstructions(Address addr, boolean forward) · InstructionIterator

Returns an iterator starting at the specified address.

getInstructions(AddressSetView addrSet, boolean forward) · InstructionIterator

Returns an iterator over instructions within the given address set.

Data Access

Get Data

getDataAt(Address addr) · Data

Returns the data (defined or undefined) that starts at the given address.

Data data = listing.getDataAt(addr);
if (data != null && data.isDefined()) {
    DataType dt = data.getDataType();
    println("Data type: " + dt.getName());
}

getDataContaining(Address addr) · Data

Returns the data object that contains the given address.

getDataAfter(Address addr) · Data

Returns the next data object after the given address.

getDataBefore(Address addr) · Data

Returns the previous data object before the given address.

Get Defined Data

getDefinedDataAt(Address addr) · Data

Returns the defined data that starts at the given address, or null if no defined data exists.

Data data = listing.getDefinedDataAt(addr);

getDefinedDataContaining(Address addr) · Data

Returns the defined data containing the given address.

getDefinedDataAfter(Address addr) · Data

Returns the next defined data after the given address.

getDefinedDataBefore(Address addr) · Data

Returns the previous defined data before the given address.

Iterate Data

getData(boolean forward) · DataIterator

Returns an iterator over all data (defined and undefined) in the program.

getDefinedData(boolean forward) · DataIterator

Returns an iterator over only defined data in the program.

DataIterator iter = listing.getDefinedData(true);
while (iter.hasNext()) {
    Data data = iter.next();
    println(data.getAddress() + ": " + data.getDataType().getName());
}

Creating Code Units

Create Instructions

createInstruction(Address addr, InstructionPrototype prototype, MemBuffer memBuf, ProcessorContextView context, int length) · Instruction

Creates a new instruction at the given address.

Throws CodeUnitInsertionException if the new instruction would overlap an existing CodeUnit.

// Usually done by the disassembler
Instruction inst = listing.createInstruction(addr, prototype, memBuf, context, 0);

Create Data

createData(Address addr, DataType dataType) · Data

Creates a new defined data object at the given address.

DataTypeManager dtm = program.getDataTypeManager();
DataType intType = dtm.getDataType("/BuiltInTypes/int");

Data data = listing.createData(addr, intType);
println("Created data at " + addr);

createData(Address addr, DataType dataType, int length) · Data

Creates a new defined data object with a specified length.

DataType stringType = new StringDataType();
Data data = listing.createData(addr, stringType, 20);

Clearing Code Units

clearCodeUnits(Address startAddr, Address endAddr, boolean clearContext) · void

Clears any code units in the given range, returning everything to undefined bytes.

// Clear code units from startAddr to endAddr
listing.clearCodeUnits(startAddr, endAddr, false);

clearCodeUnits(Address startAddr, Address endAddr, boolean clearContext, TaskMonitor monitor) · void

Clears code units with cancellation support.

isUndefined(Address start, Address end) · boolean

Checks if the given range consists entirely of undefined data.

Comments

Get Comments

getComment(CommentType type, Address address) · String

Returns the comment of the specified type at the given address.

Comment types: EOL, PRE, POST, PLATE, REPEATABLE

String comment = listing.getComment(CommentType.EOL, addr);
if (comment != null) {
    println("EOL Comment: " + comment);
}

getAllComments(Address address) · CodeUnitComments

Returns all comments at the given address.

Set Comments

setComment(Address address, CommentType type, String comment) · void

Sets a comment at the specified address.

listing.setComment(addr, CommentType.EOL, "This is the entry point");
listing.setComment(addr, CommentType.PRE, "Function prologue");

Iterate Comments

getCommentAddressIterator(CommentType type, AddressSetView addrSet, boolean forward) · AddressIterator

Returns an iterator over addresses that have the specified comment type.

AddressIterator iter = listing.getCommentAddressIterator(
    CommentType.EOL, 
    program.getMemory(), 
    true
);
while (iter.hasNext()) {
    Address addr = iter.next();
    String comment = listing.getComment(CommentType.EOL, addr);
    println(addr + ": " + comment);
}

Function Management

Create Functions

createFunction(String name, Address entryPoint, AddressSetView body, SourceType source) · Function

Creates a function with an entry point and body.

AddressSet body = new AddressSet(entryPoint, endAddr);
Function func = listing.createFunction(
    "myFunction",
    entryPoint,
    body,
    SourceType.USER_DEFINED
);

createFunction(String name, Namespace nameSpace, Address entryPoint, AddressSetView body, SourceType source) · Function

Creates a function in the specified namespace.

Get Functions

getFunctionAt(Address entryPoint) · Function

Returns the function at the given entry point.

Function func = listing.getFunctionAt(addr);
if (func != null) {
    println("Function: " + func.getName());
}

getFunctionContaining(Address addr) · Function

Returns the function containing the given address.

getGlobalFunctions(String name) · List<Function>

Returns all global functions with the given name.

Iterate Functions

getFunctions(boolean forward) · FunctionIterator

Returns an iterator over all functions.

FunctionIterator iter = listing.getFunctions(true);
while (iter.hasNext()) {
    Function func = iter.next();
    println(func.getName() + " @ " + func.getEntryPoint());
}

getFunctions(AddressSetView asv, boolean forward) · FunctionIterator

Returns an iterator over functions with entry points in the address set.

Remove Functions

removeFunction(Address entryPoint) · void

Removes the function at the given entry point.

listing.removeFunction(addr);

Statistics

getNumCodeUnits() · long

Returns the total number of code units in the listing.

getNumInstructions() · long

Returns the total number of instructions in the listing.

getNumDefinedData() · long

Returns the total number of defined data objects in the listing.

Example Usage

Analyzing Instructions

public void analyzeInstructions(Program program, AddressSet addressSet) {
    Listing listing = program.getListing();
    
    InstructionIterator iter = listing.getInstructions(addressSet, true);
    while (iter.hasNext()) {
        Instruction inst = iter.next();
        
        // Get instruction details
        String mnemonic = inst.getMnemonicString();
        Address addr = inst.getAddress();
        int length = inst.getLength();
        
        println(String.format("%s: %s (len=%d)", addr, mnemonic, length));
        
        // Process operands
        for (int i = 0; i < inst.getNumOperands(); i++) {
            println("  Op" + i + ": " + inst.getDefaultOperandRepresentation(i));
        }
    }
}

Working with Data

public void processData(Program program, Address start, Address end) {
    Listing listing = program.getListing();
    DataTypeManager dtm = program.getDataTypeManager();
    
    // Create an array of integers
    DataType intType = dtm.getDataType("/BuiltInTypes/int");
    ArrayDataType intArray = new ArrayDataType(intType, 10, 4);
    
    try {
        Data data = listing.createData(start, intArray);
        println("Created array at " + start);
        
        // Access array elements
        for (int i = 0; i < data.getNumComponents(); i++) {
            Data component = data.getComponent(i);
            println("Element " + i + ": " + component.getValue());
        }
    } catch (CodeUnitInsertionException e) {
        println("Error creating data: " + e.getMessage());
    }
}

Package Location

ghidra.program.model.listing.Listing

Related Interfaces

• Program API - Program access
• Memory API - Memory operations
• Symbol Table API - Symbol management
• Data Types API - Type definitions