FlatProgramAPI

Overview

The FlatProgramAPI class provides a flattened, simplified interface to Ghidra’s Program API. It is the parent class of GhidraScript and provides hundreds of convenience methods for common program analysis tasks.

Stability Guarantee: Methods in this class should never be removed or have their signatures changed, as doing so would break existing user scripts.

Construction

// Usually accessed via GhidraScript inheritance
public class MyScript extends GhidraScript {
    // FlatProgramAPI methods are available directly
}

// Direct instantiation
FlatProgramAPI api = new FlatProgramAPI(program);
FlatProgramAPI api = new FlatProgramAPI(program, monitor);

Core Properties

Property	Type	Description
`currentProgram`	`Program`	The program being analyzed
`monitor`	`TaskMonitor`	Monitor for tracking progress and cancellation

Memory Operations

Creating Memory Blocks

public MemoryBlock createMemoryBlock(String name, Address start, 
    InputStream input, long length, boolean overlay) throws Exception

Creates a new memory block. If input is null, creates an uninitialized block.

// Create initialized block
byteInputStream = new ByteArrayInputStream(bytes);
MemoryBlock block = createMemoryBlock(".text", addr("0x1000"), 
    byteInputStream, 0x1000, false);

// Create uninitialized block
MemoryBlock uninit = createMemoryBlock(".bss", addr("0x2000"), 
    null, 0x500, false);

public MemoryBlock createMemoryBlock(String name, Address start, 
    byte[] bytes, boolean overlay) throws Exception

Creates a memory block from a byte array.

byte[] data = {0x55, 0x48, (byte)0x89, (byte)0xe5};
MemoryBlock block = createMemoryBlock(".text", addr("0x1000"), data, false);

Accessing Memory Blocks

public MemoryBlock getMemoryBlock(String name)
public MemoryBlock getMemoryBlock(Address address)

Returns a memory block by name or containing the specified address.

MemoryBlock textBlock = getMemoryBlock(".text");
MemoryBlock block = getMemoryBlock(currentAddress);

public MemoryBlock[] getMemoryBlocks()

Returns all memory blocks in the program.

for (MemoryBlock block : getMemoryBlocks()) {
    println(block.getName() + ": " + block.getStart() + " - " + block.getEnd());
}

public void removeMemoryBlock(MemoryBlock block) throws Exception

Removing a memory block deletes ALL annotations (disassembly, comments, etc.) in that block.

Symbol and Label Operations

Creating Labels

public Symbol createLabel(Address address, String name, boolean makePrimary) 
    throws Exception

public Symbol createLabel(Address address, String name, boolean makePrimary,
    SourceType sourceType) throws Exception
    
public Symbol createLabel(Address address, String name, Namespace namespace,
    boolean makePrimary, SourceType sourceType) throws Exception

Creates a label at the specified address.

// Create a simple label
createLabel(addr("0x1000"), "main", true);

// Create with source type
createLabel(addr("0x1000"), "main", true, SourceType.USER_DEFINED);

// Create in namespace
Namespace ns = getNamespace(null, "MyNamespace");
createLabel(addr("0x2000"), "helper", ns, true, SourceType.USER_DEFINED);

public boolean removeSymbol(Address address, String name)

Deletes a symbol with the specified name at the specified address.

removeSymbol(addr("0x1000"), "old_name");

Symbol Lookup

public Symbol getSymbolAt(Address address)
public Symbol getSymbolAt(Address address, String name, Namespace namespace)

Returns the primary symbol at an address, or a specific symbol by name and namespace.

Symbol sym = getSymbolAt(currentAddress);
if (sym != null) {
    println("Symbol: " + sym.getName());
}

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

Returns all symbols with the given name in the specified namespace.

List<Symbol> symbols = getSymbols("init", null); // global namespace
for (Symbol s : symbols) {
    println(s.getAddress().toString());
}

public Symbol getSymbolAfter(Address address)
public Symbol getSymbolBefore(Address address)

Returns the next/previous non-default primary symbol.

Entry Points

public void addEntryPoint(Address address)

Adds an entry point at the specified address.

addEntryPoint(addr("0x1000"));

public void removeEntryPoint(Address address)

Removes the entry point at the specified address.

Comments

Setting Comments

public boolean setPlateComment(Address address, String comment)
public boolean setPreComment(Address address, String comment)
public boolean setPostComment(Address address, String comment)
public boolean setEOLComment(Address address, String comment)
public boolean setRepeatableComment(Address address, String comment)

Sets different types of comments at the specified address.

setPlateComment(addr("0x1000"), "Main entry point");
setPreComment(addr("0x1000"), "Initialize stack frame");
setEOLComment(addr("0x1004"), "Save base pointer");
setRepeatableComment(addr("0x1008"), "Common initialization");

Getting Comments

public String getPlateComment(Address address)
public String getPreComment(Address address)
public String getPostComment(Address address)
public String getEOLComment(Address address)
public String getRepeatableComment(Address address)

Retrieves the raw text of comments. Returns null if no comment exists.

String comment = getEOLComment(currentAddress);
if (comment != null) {
    println("Comment: " + comment);
}

Disassembly and Code

Disassembly

public boolean disassemble(Address address)

Starts disassembling at the specified address. The disassembler follows code flows.

if (disassemble(addr("0x1000"))) {
    println("Successfully disassembled at 0x1000");
}

Clearing Code

public void clearListing(Address address) throws CancelledException
public void clearListing(Address start, Address end) throws CancelledException
public void clearListing(AddressSetView set) throws CancelledException

Clears code units (instructions or data) at the specified location.

clearListing(addr("0x1000"));
clearListing(addr("0x1000"), addr("0x1100"));

public boolean clearListing(AddressSetView set, boolean code, boolean symbols,
    boolean comments, boolean properties, boolean functions, boolean registers,
    boolean equates, boolean userReferences, boolean analysisReferences,
    boolean importReferences, boolean defaultReferences, boolean bookmarks)

Selectively clears specific types of information from an address set.

Instruction Operations

Accessing Instructions

public Instruction getFirstInstruction()
public Instruction getLastInstruction()
public Instruction getFirstInstruction(Function function)
public Instruction getInstructionAt(Address address)
public Instruction getInstructionContaining(Address address)
public Instruction getInstructionBefore(Address address)
public Instruction getInstructionAfter(Address address)

Accesses instructions in the program.

Instruction instr = getInstructionAt(currentAddress);
if (instr != null) {
    println("Mnemonic: " + instr.getMnemonicString());
    println("Operands: " + instr.getDefaultOperandRepresentation(0));
}

// Iterate through instructions
Instruction current = getFirstInstruction();
while (current != null && !monitor.isCancelled()) {
    println(current.getAddress() + ": " + current.toString());
    current = getInstructionAfter(current.getMaxAddress());
}

Data Operations

Accessing Data

public Data getFirstData()
public Data getLastData()
public Data getDataAt(Address address)
public Data getDataContaining(Address address)
public Data getDataBefore(Address address)
public Data getDataAfter(Address address)

Accesses defined data in the program.

Creating Data

public Data createData(Address address, DataType datatype)
    throws CodeUnitInsertionException

Creates a new data object at the specified address.

DataType dt = new DWordDataType();
Data data = createData(addr("0x2000"), dt);

Convenience Data Creation Methods

public Data createByte(Address address) throws Exception
public Data createWord(Address address) throws Exception
public Data createDWord(Address address) throws Exception
public Data createQWord(Address address) throws Exception
public Data createFloat(Address address) throws Exception
public Data createDouble(Address address) throws Exception
public Data createChar(Address address) throws Exception

Quickly create common data types.

createDWord(addr("0x2000"));
createQWord(addr("0x2004"));
createFloat(addr("0x200C"));

public void createDwords(Address start, int count) throws Exception

Creates multiple dwords starting at an address.

createDwords(addr("0x3000"), 10); // Create 10 dwords

Function Operations

Creating Functions

public Function createFunction(Address entryPoint, String name)

Creates a function at the entry point with the specified name.

Function func = createFunction(addr("0x1000"), "myFunction");
if (func != null) {
    println("Created function: " + func.getName());
}

Accessing Functions

public Function getFirstFunction()
public Function getLastFunction()
public Function getFunctionAt(Address entryPoint)
public Function getFunctionContaining(Address address)
public Function getFunctionBefore(Address address)
public Function getFunctionAfter(Address address)
public List<Function> getGlobalFunctions(String name)

Accesses functions in the program.

Function func = getFunctionContaining(currentAddress);
if (func != null) {
    println("Current function: " + func.getName());
    println("Entry point: " + func.getEntryPoint());
}

// Find all functions named "init"
List<Function> initFuncs = getGlobalFunctions("init");
for (Function f : initFuncs) {
    println(f.getEntryPoint().toString());
}

Removing Functions

public void removeFunction(Function function)
public void removeFunctionAt(Address entryPoint)

Removes a function from the program.

removeFunctionAt(addr("0x1000"));

Search Operations

Byte Pattern Search

public Address find(Address start, byte value)
public Address find(Address start, byte[] values)

Finds the first occurrence of a byte or byte sequence.

// Find single byte
Address found = find(addr("0x1000"), (byte)0x55);

// Find byte sequence
byte[] pattern = {0x55, 0x48, (byte)0x89, (byte)0xe5};
Address found = find(addr("0x1000"), pattern);

public Address findBytes(Address start, String byteString)
public Address[] findBytes(Address start, String byteString, int matchLimit)
public Address[] findBytes(Address start, String byteString, int matchLimit, int alignment)

Finds byte patterns using regular expressions.

// Simple search
Address addr = findBytes(addr("0x1000"), "\\x55\\x48");

// Regex search: 0x50 followed by 0-10 bytes, then 0x55
Address[] matches = findBytes(addr("0x1000"), "\\x50.{0,10}\\x55", 10);

// Search with alignment (only match on even addresses)
Address[] aligned = findBytes(addr("0x1000"), "\\xC3", 50, 2);

public Address[] findBytes(AddressSetView set, String byteString, 
    int matchLimit, int alignment)

Searches for byte patterns within a specific address set.

String Search

public Address find(String text)

Searches for text in the program listing (comments, labels, mnemonics, operands).

Address result = find("main");
if (result != null) {
    println("Found 'main' at: " + result);
}

public List<FoundString> findStrings(AddressSetView addressSet, 
    int minimumStringLength, int alignment, boolean requireNullTermination,
    boolean includeAllCharWidths)

Searches for ASCII strings in program memory.

List<FoundString> strings = findStrings(null, 5, 1, true, false);
for (FoundString fs : strings) {
    println(fs.getAddress() + ": " + fs.getString(currentProgram.getMemory()));
}

public List<FoundString> findPascalStrings(AddressSetView addressSet,
    int minimumStringLength, int alignment, boolean includePascalUnicode)

Searches for Pascal-style strings (length-prefixed).

Analysis Operations

public void analyzeAll(Program program)

Performs complete analysis of the entire program. This method blocks until analysis completes.

analyzeAll(currentProgram);

public void analyzeChanges(Program program)

Analyzes only pending changes to the program. This method blocks until analysis completes.

// Make changes to program
createFunction(addr("0x1000"), "newFunc");

// Analyze the changes
analyzeChanges(currentProgram);

Namespace Operations

public Namespace getNamespace(Namespace parent, String namespaceName)

Returns a namespace with the given name.

public Namespace createNamespace(Namespace parent, String namespaceName)
    throws DuplicateNameException, InvalidInputException

Creates a new namespace.

Namespace ns = createNamespace(null, "MyNamespace");
createLabel(addr("0x1000"), "func", ns, true, SourceType.USER_DEFINED);

public GhidraClass createClass(Namespace parent, String className)
    throws DuplicateNameException, InvalidInputException

Creates a new class (special type of namespace).

Data Type Operations

public DataType[] getDataTypes(String name)

Searches for data types by name.

DataType[] types = getDataTypes("IMAGE_DOS_HEADER");
if (types.length > 0) {
    createData(addr("0x400000"), types[0]);
}

Address Operations

public AddressSet createAddressSet()

Creates a new mutable address set.

AddressSet set = createAddressSet();
set.add(addr("0x1000"), addr("0x2000"));
set.add(addr("0x3000"), addr("0x4000"));

public AddressFactory getAddressFactory()

Returns the address factory for the current program.

Transaction Management

protected void start()
protected void end(boolean commit)

Manages transactions on the current program.

When using GhidraScript, transactions are automatically managed. Only use these methods when working directly with FlatProgramAPI.

FlatProgramAPI api = new FlatProgramAPI(program);
api.start();
try {
    api.createLabel(addr("0x1000"), "test", true);
    api.end(true); // commit
} catch (Exception e) {
    api.end(false); // rollback
}

Utility Methods

public File getProgramFile()

Returns the File that the program was originally imported from.

File file = getProgramFile();
println("Program imported from: " + file.getAbsolutePath());

public Program getCurrentProgram()

Returns the current program.

public TaskMonitor getMonitor()

Returns the current task monitor.

Constants

public static final int MAX_REFERENCES_TO = 0x1000;

Maximum number of references to process.

Complete Example

// Complete script demonstrating FlatProgramAPI usage
// @category Examples

import ghidra.app.script.GhidraScript;
import ghidra.program.model.listing.*;
import ghidra.program.model.symbol.*;
import ghidra.program.model.address.*;

public class FlatAPIExample extends GhidraScript {

    @Override
    public void run() throws Exception {
        // Memory operations
        for (MemoryBlock block : getMemoryBlocks()) {
            println("Block: " + block.getName());
        }
        
        // Find byte patterns
        byte[] pattern = {0x55, 0x48, (byte)0x89, (byte)0xe5};
        Address found = find(null, pattern);
        if (found != null) {
            println("Found pattern at: " + found);
            disassemble(found);
        }
        
        // Create function
        Function func = createFunction(found, "discovered_func");
        if (func != null) {
            setPlateComment(found, "Automatically discovered function");
        }
        
        // Find strings
        List<FoundString> strings = findStrings(null, 5, 1, true, false);
        println("Found " + strings.size() + " strings");
        
        // Analyze changes
        analyzeChanges(currentProgram);
    }
}

​Overview

​Construction

​Core Properties

​Memory Operations

​Creating Memory Blocks

​Accessing Memory Blocks

​Symbol and Label Operations

​Creating Labels

​Symbol Lookup

​Entry Points

​Comments

​Setting Comments

​Getting Comments

​Disassembly and Code

​Disassembly

​Clearing Code

​Instruction Operations

​Accessing Instructions

​Data Operations

​Accessing Data

​Creating Data

​Convenience Data Creation Methods

​Function Operations

​Creating Functions

​Accessing Functions

​Removing Functions

​Search Operations

​Byte Pattern Search

​String Search

​Analysis Operations

​Namespace Operations

​Data Type Operations

​Address Operations

​Transaction Management

​Utility Methods

​Constants

​Complete Example

​See Also

Overview

Construction

Core Properties

Memory Operations

Creating Memory Blocks

Accessing Memory Blocks

Symbol and Label Operations

Creating Labels

Symbol Lookup

Entry Points

Comments

Setting Comments

Getting Comments

Disassembly and Code

Disassembly

Clearing Code

Instruction Operations

Accessing Instructions

Data Operations

Accessing Data

Creating Data

Convenience Data Creation Methods

Function Operations

Creating Functions

Accessing Functions

Removing Functions

Search Operations

Byte Pattern Search

String Search

Analysis Operations

Namespace Operations

Data Type Operations

Address Operations

Transaction Management

Utility Methods

Constants

Complete Example

See Also