# Ghidra Framework APIs for Program Analysis: Program, Function, and Instruction Interfaces

> Master Ghidra framework APIs Program Function and Instruction to enhance your program analysis. Discover how these interfaces unlock deep binary insights and streamline reverse engineering.

- Repository: [National Security Agency/ghidra](https://github.com/NationalSecurityAgency/ghidra)
- Tags: api-reference
- Published: 2026-03-04

---

**The three essential Ghidra framework APIs for program analysis are the `Program` interface (top-level binary container), `Function` interface (routine representation), and `Instruction` interface (disassembled machine code), all accessed through the `Listing` facade in the `ghidra.program.model.listing` package.**

The National Security Agency's Ghidra binary analysis platform exposes a comprehensive Java API for automated reverse engineering. Understanding the core `Program`, `Function`, and `Instruction` interfaces is essential for developing scripts, analyzers, and plugins that interact with disassembled binaries at the framework level.

## Core Ghidra Program Analysis APIs

Ghidra's analysis engine centers on four primary interfaces defined in the `SoftwareModeling` framework. These abstractions provide read-only views of the program database, with modifications handled through transaction-aware methods.

### Program Interface – The Top-Level Container

The **`Program`** interface represents a single loaded binary image and serves as the root of the object model. Defined in [`Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Program.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Program.java) (lines 40‑127), this interface provides access to the memory map, symbol table, function manager, and program-wide properties.

Key capabilities include:
- Retrieving the **`Listing`** via `program.getListing()` to access code units
- Obtaining the **`FunctionManager`** via `program.getFunctionManager()` to enumerate routines
- Querying language specifications via `program.getLanguage()` and image base addresses
- Accessing the data type manager through `program.getDataTypeManager()`

### Function Interface – Routine Representation

The **`Function`** interface models a single entry-point routine within the binary. Located in [`Function.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Function.java) (lines 33‑170), it exposes the function body, signature, calling convention, and parameter storage.

Critical methods include:
- `getName()` – Returns the function's symbol name
- `getSignature()` – Provides the **`FunctionSignature`** including return type and parameters
- `getBody()` – Returns an **`AddressSetView`** defining the function's address ranges
- `updateFunction(...)` – Modifies calling convention, return type, or parameters

This interface also manages thunk relationships and stack purge sizes, making it essential for control-flow and data-flow analyses.

### Instruction Interface – Disassembled Machine Code

The **`Instruction`** interface represents a single disassembled machine instruction. Found in [`Instruction.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Instruction.java) (lines 30‑138), it provides access to raw bytes, operands, control flow, and p-code (intermediate representation).

Key functionality includes:
- `getMnemonicString()` – Returns the assembly mnemonic
- `getRegister(int opIndex)` – Extracts register operands
- `getPcode(boolean includeOverrides)` – Generates p-code operations for semantic analysis
- `getFlowType()` and `getFallThrough()` – Determine control-flow behavior

This interface is the primary touchpoint for instruction-level analysis, including operand decoding, delay slot handling, and cross-reference generation.

### Listing Interface – The Unified Facade

The **`Listing`** interface acts as the central bridge between `Program` and individual code units. Defined in [`Listing.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Listing.java) (lines 88‑236), it unifies instructions, data, undefined bytes, and comments under a single query interface.

Essential methods include:
- `getInstructionAt(Address)` – Retrieves an instruction by address
- `getFunctions(boolean forward)` – Returns a **`FunctionIterator`** for enumerating routines
- `getInstructions(AddressSetView, boolean)` – Iterates instructions within an address range
- `createInstruction(...)` – Creates new instructions during analysis

Access this facade via `program.getListing()`; it is the entry point for most analysis scripts.

## Practical Implementation Examples

The following Java snippets demonstrate common patterns when scripting against the Ghidra framework APIs. These examples work in the Script Manager or as plugin code, relying solely on the public interfaces.

### Enumerating All Functions and Signatures

```java
// Assume 'program' is the current Program instance provided by Ghidra
Listing listing = program.getListing();
FunctionIterator funcIter = listing.getFunctions(true); // forward order

while (funcIter.hasNext()) {
    Function func = funcIter.next();
    String name = func.getName();
    String sig  = func.getSignature().getPrototypeString(false, true);
    println(name + " : " + sig);
}

```

This pattern uses **`Program.getListing()`**, **`Listing.getFunctions(boolean)`**, and **`Function.getSignature()`** to extract prototype strings.

### Walking Instructions Within a Function

```java
// Get a function by entry address (example address)
Address entry = program.getAddressFactory().getAddress("0x00401000");
Function f = program.getFunctionManager().getFunctionAt(entry);
if (f == null) {
    println("No function at " + entry);
    return;
}

// Iterate over the function body
AddressSetView body = f.getBody();
InstructionIterator it = listing.getInstructions(body, true);
while (it.hasNext()) {
    Instruction ins = it.next();
    println(ins.getAddress() + "  " + ins.getMnemonicString());

    // Print any pure register operands
    for (int i = 0; i < ins.getNumOperands(); i++) {
        Register reg = ins.getRegister(i);
        if (reg != null) {
            println("   operand " + i + " -> " + reg.getName());
        }
    }
}

```

Key API calls here include **`Program.getFunctionManager()`**, **`Function.getBody()`**, and **`Instruction.getRegister(int)`**.

### Generating P-code for Semantic Analysis

```java
// Pick an arbitrary address
Address addr = program.getAddressFactory().getAddress("0x00401120");
Instruction ins = listing.getInstructionAt(addr);
if (ins == null) {
    println("No instruction at " + addr);
    return;
}

// Retrieve p-code (without flow overrides)
PcodeOp[] ops = ins.getPcode(false);
println("P-code for " + ins.getAddress() + ":");
for (PcodeOp op : ops) {
    println("   " + op);
}

```

This demonstrates **`Listing.getInstructionAt(Address)`** and **`Instruction.getPcode(boolean)`** for retrieving intermediate representation operations.

## Source Code Architecture and Key Files

The following files in the NationalSecurityAgency/ghidra repository define the backbone of the program analysis API:

- **[`Program.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Program.java)** – [`Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Program.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Program.java) defines the top-level program model with accessors for memory, symbols, and the listing.

- **[`Function.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Function.java)** – [`Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Function.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Function.java) specifies routine representation, signature handling, and parameter APIs.

- **[`Instruction.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Instruction.java)** – [`Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Instruction.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Instruction.java) declares operand access, flow types, and p-code generation methods.

- **[`Listing.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Listing.java)** – [`Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Listing.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/listing/Listing.java) provides the façade for creating and querying code units.

- **[`FunctionManager.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/FunctionManager.java)** – Interface definition for the global function map, with concrete implementation in `ghidra/program/database/function/FunctionManagerDB`.

- **[`ProgramBasedDataTypeManager.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/ProgramBasedDataTypeManager.java)** – [`Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/data/ProgramBasedDataTypeManager.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/data/ProgramBasedDataTypeManager.java) manages data types tied to specific program instances.

These interfaces are implemented in the `ghidra.program.database` package (e.g., `ProgramDB`), ensuring scripts work against any concrete program representation without modification.

## Summary

- The **`Program`** interface is the root container for binary images, providing access to memory, symbols, and the `Listing` facade via methods like `getListing()` and `getFunctionManager()`.
- The **`Function`** interface represents individual routines with entry points, bodies (`AddressSetView`), and signatures, accessible through `program.getFunctionManager().getFunctionAt()`.
- The **`Instruction`** interface exposes disassembled machine code, operands, control flow, and p-code generation through `listing.getInstructionAt()` and `instruction.getPcode()`.
- The **`Listing`** interface serves as the unified entry point for iterating functions and instructions, creating code units, and managing comments.
- All APIs are defined as Java interfaces in `ghidra.program.model.listing`, with concrete database-backed implementations in the `ghidra.program.database` package.

## Frequently Asked Questions

### What is the relationship between Program and Listing in Ghidra?

The **`Listing`** is a component owned by the **`Program`**. Access it via `program.getListing()` to retrieve code units (instructions and data) and create or delete them. While `Program` manages the binary-wide context (memory, symbols, functions), `Listing` provides the granular view of disassembled content at specific addresses.

### How do I access function parameters using the Ghidra API?

First obtain a **`Function`** object via `program.getFunctionManager().getFunctionAt(address)` or through the `Listing`. Then call `function.getSignature()` to retrieve the **`FunctionSignature`**, which exposes parameters through `getArguments()`. Each parameter provides its name, data type, and storage location (register or stack offset).

### Can I modify instructions programmatically using these APIs?

Direct modification of `Instruction` objects is restricted because the interfaces are read-only. To create or modify instructions, use the **`Listing`** interface methods such as `createInstruction(Address, InstructionPrototype)` or `clearCodeUnits()`. These methods handle transactions, locking, and undo/redo bookkeeping automatically.

### Where are the concrete implementations of these interfaces located?

While the API contracts reside in `ghidra.program.model.listing`, the concrete database-backed implementations live in `ghidra.program.database`. For example, `ProgramDB` implements **`Program`**, and `FunctionDB` implements **`Function`**. This separation allows scripts to run against flat programs, database-backed programs, or in-memory test fixtures without code changes.