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)
Returns the code unit that starts at the given address.CodeUnit cu = listing.getCodeUnitAt(addr);
if (cu != null) {
println(cu.getMnemonicString());
}
getCodeUnitContaining(Address addr)
Returns the code unit that contains the given address.CodeUnit cu = listing.getCodeUnitContaining(addr);
getCodeUnitAfter(Address addr)
Returns the next code unit starting after the given address.
getCodeUnitBefore(Address addr)
Returns the previous code unit starting before the given address.
Iterate Code Units
getCodeUnits(boolean forward)
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)
Returns an iterator starting at the specified address.
getCodeUnits(AddressSetView addrSet, boolean forward)
Returns an iterator over code units within the given address set.
Instruction Access
Get Instructions
getInstructionAt(Address addr)
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)
Returns the instruction that contains the given address.
getInstructionAfter(Address addr)
Returns the next instruction after the given address.
getInstructionBefore(Address addr)
Returns the previous instruction before the given address.
Iterate Instructions
getInstructions(boolean forward)
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)
Returns an iterator starting at the specified address.
getInstructions(AddressSetView addrSet, boolean forward)
Returns an iterator over instructions within the given address set.
Data Access
Get 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)
Returns the data object that contains the given address.
getDataAfter(Address addr)
Returns the next data object after the given address.
getDataBefore(Address addr)
Returns the previous data object before the given address.
Get Defined Data
getDefinedDataAt(Address addr)
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)
Returns the defined data containing the given address.
getDefinedDataAfter(Address addr)
Returns the next defined data after the given address.
getDefinedDataBefore(Address addr)
Returns the previous defined data before the given address.
Iterate Data
Returns an iterator over all data (defined and undefined) in the program.
getDefinedData(boolean forward)
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)
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)
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)
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)
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)
Clears code units with cancellation support.
isUndefined(Address start, Address end)
Checks if the given range consists entirely of undefined data.
Returns the comment of the specified type at the given address.Comment types: EOL, PRE, POST, PLATE, REPEATABLEString comment = listing.getComment(CommentType.EOL, addr);
if (comment != null) {
println("EOL Comment: " + comment);
}
Returns all comments at the given address.
Sets a comment at the specified address.listing.setComment(addr, CommentType.EOL, "This is the entry point");
listing.setComment(addr, CommentType.PRE, "Function prologue");
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)
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)
Creates a function in the specified namespace.
Get Functions
getFunctionAt(Address entryPoint)
Returns the function at the given entry point.Function func = listing.getFunctionAt(addr);
if (func != null) {
println("Function: " + func.getName());
}
getFunctionContaining(Address addr)
Returns the function containing the given address.
getGlobalFunctions(String name)
Returns all global functions with the given name.
Iterate Functions
getFunctions(boolean forward)
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)
Returns an iterator over functions with entry points in the address set.
Remove Functions
removeFunction(Address entryPoint)
Removes the function at the given entry point.listing.removeFunction(addr);
Statistics
Returns the total number of code units in the listing.
Returns the total number of instructions in the listing.
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
