IDA Domain API

https://ida-domain.docs.hex-rays.com/
Admin
This repository contains documentation for the ida-domain_hex-rays project, which is related to...
Tokens:138,086
Snippets:1,714
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Implement MicroInstructionOptimizer

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Example of creating and installing a custom instruction optimizer.

```python
class MyOpt(MicroInstructionOptimizer):
    def optimize(self, block, insn, optflags):
        ...
        return 1  # number of changes

opt = MyOpt()
opt.install()
```

--------------------------------

### Verify Installation

Source: https://ida-domain.docs.hex-rays.com/getting_started

Test the installation by importing the Database module.

```python
# test_install.py
try:
    from ida_domain import Database
    print("✓ Installation successful!")
except ImportError as e:
    print(f"✗ Installation failed: {e}")
```

--------------------------------

### Install IDA Domain Package

Source: https://ida-domain.docs.hex-rays.com/getting_started

Create a virtual environment and install the ida-domain package using pip.

```bash
# Create and activate virtual environment
python -m venv ida-env
source ida-env/bin/activate  # On Windows: ida-env\Scripts\activate

# Install the package
pip install ida-domain
```

--------------------------------

### MicrocodeLifter.install

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Installs the custom instruction lifter.

```APIDOC
## install()

### Description
Installs the custom instruction lifter to handle unsupported processor instructions.

### Signature
`install() -> None`
```

--------------------------------

### idcstart

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Indicates the start of IDC engine work.

```python
idcstart() -> None
```

--------------------------------

### dbg_process_start

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when a process starts.

```APIDOC
## dbg_process_start(pid: pid_t, tid: thid_t, ea: ea_t, modinfo_name: str, modinfo_base: ea_t, modinfo_size: asize_t) -> None

### Description
Called when a process has started.

### Parameters
- **pid** (pid_t) - Process ID
- **tid** (thid_t) - Thread ID
- **ea** (ea_t) - Address
- **modinfo_name** (str) - Module info name
- **modinfo_base** (ea_t) - Module info base address
- **modinfo_size** (asize_t) - Module info size
```

--------------------------------

### dbg_process_start hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when a process starts.

```python
dbg_process_start(
    pid: pid_t,
    tid: thid_t,
    ea: ea_t,
    modinfo_name: str,
    modinfo_base: ea_t,
    modinfo_size: asize_t,
) -> None
```

--------------------------------

### Retrieve All Instructions

Source: https://ida-domain.docs.hex-rays.com/ref/instructions

Get an iterator over all instructions present in the database.

```python
get_all() -> Iterator[insn_t]
```

--------------------------------

### ev_get_macro_insn_head

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Calculates the start of a macro instruction.

```APIDOC
## ev_get_macro_insn_head(head, ip)

### Description
Calculate the start of a macro instruction if IP points to the middle of an instruction.

### Parameters
- **head** (ea_t *) - Output answer; BADADDR means normal instruction.
- **ip** (ea_t) - Instruction address.

### Returns
- **int** - 0 if unimplemented, 1 if implemented.
```

--------------------------------

### Create new instruction

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Example of using the create method to instantiate a new microcode instruction.

```python
insn = MicroInstruction.create(
    ea=0x401000,
    opcode=MicroOpcode.MOV,
    left=MicroOperand.reg(mreg, 4),
    dest=MicroOperand.number(0, 4),
)
```

--------------------------------

### ev_may_be_func

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Checks if a function can start at this instruction.

```APIDOC
## ev_may_be_func

### Description
Checks if a function can start at this instruction.

### Parameters
- **insn** (insn_t const *) - Required - The instruction.
- **state** (int) - Required - Autoanalysis phase. 0 for creating functions, 1 for creating chunks.

### Returns
- **int** - Probability (1..100).
```

--------------------------------

### dbg_thread_start hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when a thread starts.

```python
dbg_thread_start(pid: pid_t, tid: thid_t, ea: ea_t) -> None
```

--------------------------------

### ev_out_segstart hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Produces the start of a segment in disassembled output.

```python
ev_out_segstart(
    outctx: 'outctx_t *', seg: 'segment_t *'
) -> int
```

--------------------------------

### pre_structural

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when structure analysis is starting.

```APIDOC
## pre_structural(ct: control_graph_t *, cfunc: cfunc_t, g: simple_graph_t) -> int

### Description
Structure analysis is starting.

### Parameters
- **ct** (control_graph_t *) - Control graph.
- **cfunc** (cfunc_t) - The current function.
- **g** (simple_graph_t) - Control flow graph.

### Returns
- **int** - Microcode error codes code; MERR_BLOCK means that the analysis has been performed by a plugin.
```

--------------------------------

### ev_out_header hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Produces the start of the disassembled text.

```python
ev_out_header(outctx: 'outctx_t *') -> int
```

--------------------------------

### Get instruction text

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Returns the text representation of the instruction.

```python
to_text(remove_tags: bool = True) -> str
```

--------------------------------

### Get Entry Point Names

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Returns an iterator over all entry point names.

```python
get_names() -> Iterator[str]
```

--------------------------------

### dbg_started_loading_bpts hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when breakpoint information starts loading from the IDB.

```python
dbg_started_loading_bpts() -> None
```

--------------------------------

### ev_setup_til hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Optional callback to initialize default type libraries after a file is loaded.

```python
ev_setup_til() -> int
```

--------------------------------

### Quick Usage Example

Source: https://ida-domain.docs.hex-rays.com/

Demonstrates opening a database and iterating over functions to count instructions using the IDA Domain API.

```python
import argparse

from ida_domain import Database

parser = argparse.ArgumentParser(description='Quick Usage Example')
parser.add_argument('-f', '--input-file', type=str, required=True)
args = parser.parse_args()

# Open any binary format IDA supports
with Database() as db:
    if db.open(args.input_file):
        # Pythonic iteration over functions
        for func in db.functions:
            print(f'{func.name}: {len(list(db.functions.get_instructions(func)))} instructions')
```

--------------------------------

### Get bytes at address

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Reads a specified number of bytes starting from the given address.

```python
get_bytes_at(ea: ea_t, size: int) -> Optional[bytes]
```

--------------------------------

### Main entry point

Source: https://ida-domain.docs.hex-rays.com/examples

Parses command line arguments and initiates the database traversal process.

```python
def main():
    """Main entry point with argument parsing."""
    parser = argparse.ArgumentParser(description='IDA Database Traversal Example')
    parser.add_argument(
        '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
    )
    args = parser.parse_args()
    traverse_database(args.input_file)


if __name__ == '__main__':
    main()
```

--------------------------------

### Get Item Bounds

Source: https://ida-domain.docs.hex-rays.com/ref/heads

Retrieves the start and end addresses of the item containing the specified effective address.

```python
bounds(ea: ea_t) -> tuple[ea_t, ea_t]
```

--------------------------------

### Get previous head

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Retrieves the start of the previous data item before the specified address, optionally bounded by min_ea.

```python
get_previous_head(
    ea: ea_t, min_ea: ea_t = None
) -> Optional[ea_t]
```

--------------------------------

### Handle pre-structural analysis

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered at the start of structure analysis.

```python
pre_structural(
    ct: 'control_graph_t *',
    cfunc: cfunc_t,
    g: simple_graph_t,
) -> int
```

--------------------------------

### Database Initialization and Access

Source: https://ida-domain.docs.hex-rays.com/usage

Demonstrates how to initialize a Database object, open an IDB file, and access entity collections like functions and segments.

```APIDOC
## Database Access

### Description
Initializes a database connection and retrieves collections of analysis entities.

### Usage
```python
db = Database()
db.open('/path/to/your/database.idb')
db.functions.get_all()
db.segments.get_all()
db.entries.get_all()
```
```

--------------------------------

### Get next head

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Retrieves the start of the next data item after the specified address, optionally bounded by max_ea.

```python
get_next_head(
    ea: ea_t, max_ea: ea_t = None
) -> Optional[ea_t]
```

--------------------------------

### ready_to_run

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Called when all UI elements are initialized.

```python
ready_to_run() -> None
```

--------------------------------

### Get Strings in Range

Source: https://ida-domain.docs.hex-rays.com/ref/strings

Retrieves an iterator for strings located between a start and end address. Raises errors for invalid addresses or range parameters.

```python
get_between(
    start_ea: ea_t, end_ea: ea_t
) -> Iterator[StringItem]
```

--------------------------------

### Get Entry Point by Ordinal

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Retrieves an entry point using its ordinal number.

```python
get_by_ordinal(ordinal: int) -> Optional[EntryInfo]
```

--------------------------------

### create_qword_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Creates qword data items at consecutive addresses starting from the specified address.

```python
create_qword_at(
    ea: ea_t, count: int = 1, force: bool = False
) -> bool
```

--------------------------------

### Generate IDA Command Line Arguments

Source: https://ida-domain.docs.hex-rays.com/ref/database

Example showing how to instantiate the class and generate the command line string using build_args().

```python
opts = IdaCommandOptions(
    auto_analysis=False,
    processor="arm",
    script_file="myscript.py",
    script_args=["arg1", "arg2"],
    debug_flags=["queue", "debugger"]
)
args = opts.build_args()
```

--------------------------------

### find_first_use

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Finds the first instruction after a start point that uses specific locations.

```APIDOC
## find_first_use(locations: MicroLocationSet, start: MicroInstruction, end: Optional[MicroInstruction] = None) -> Optional[MicroInstruction]

### Description
Find the first instruction after start that uses locations. Note: locations is modified during the search.
```

--------------------------------

### get_comment

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Get comment for function.

```APIDOC
## get_comment(func: func_t, repeatable: bool = False) -> str

### Description
Get comment for function.

### Parameters
- **func** (func_t) - The function to get comment from.
- **repeatable** (bool) - If True, retrieves repeatable comment. Default: False.

### Returns
- **str** - Comment text, or empty string if no comment exists.
```

--------------------------------

### Initialize Instructions Class

Source: https://ida-domain.docs.hex-rays.com/ref/instructions

Instantiate the Instructions class with a reference to an active IDA database.

```python
Instructions(database: Database)
```

--------------------------------

### initing_database

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when database initialization begins.

```python
initing_database() -> None
```

--------------------------------

### Database Lifecycle Management

Source: https://ida-domain.docs.hex-rays.com/ref/database

Demonstrates opening and closing databases in library and IDA modes. Use the context manager for automatic cleanup.

```python
# Library mode: Open and automatically close a database
with Database.open("path/to/file.exe", save_on_close=True) as db:
    print(f"Loaded: {db.path}")
# Database is automatically closed here

# Library mode: Manual control
db = Database.open("path/to/file.exe", save_on_close=True)
db.close()

# IDA mode: Get handle to current database
db = Database.open()  # or Database.open(None)
```

--------------------------------

### Get Entry Point by Address

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Finds an entry point at a specific linear address.

```python
get_at(ea: ea_t) -> Optional[EntryInfo]
```

--------------------------------

### Initialize PseudocodeVisitor

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Visitor for expressions and instructions. Use for stateful traversal.

```python
PseudocodeVisitor(flags: int = CV_FAST)
```

```python
class CollectAll(PseudocodeVisitor):
    def __init__(self):
        super().__init__()
        self.items = []

    def visit_expression(self, expr):
        self.items.append(expr)
        return 0

    def visit_instruction(self, insn):
        self.items.append(insn)
        return 0
```

--------------------------------

### MicroInstructionVisitor initialization

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Constructor for the instruction visitor class.

```python
MicroInstructionVisitor()
```

--------------------------------

### Initialize ViewHooks

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Instantiate the ViewHooks convenience class.

```python
ViewHooks()
```

--------------------------------

### ev_delay_slot_insn

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Get delay slot instruction.

```APIDOC
## ev_delay_slot_insn

### Description
Get delay slot instruction.

### Parameters
- **ea** (ea_t) - Instruction address in question.
- **bexec** (bool) - Execute slot if jumping.
- **fexec** (bool) - Execute slot if not jumping.

### Returns
- **PyObject*** - 1 for a positive answer, <=0 for ordinary instruction.
```

--------------------------------

### MicroInstructionVisitor methods

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Methods for visiting instructions during traversal.

```python
visit(insn: MicroInstruction) -> int
```

```python
visit_minsn() -> int
```

--------------------------------

### Entries.get_at

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Retrieves an entry point by its linear address.

```APIDOC
## get_at(ea: ea_t) -> Optional[EntryInfo]

### Description
Searches for an entry point at the specified linear address.

### Parameters
- **ea** (ea_t) - Required - Linear address to search for

### Returns
- **EntryInfo** - The entry point at the specified address, or None if not found
```

--------------------------------

### get_string_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Gets a string from the specified address.

```APIDOC
## get_string_at(ea: ea_t, max_length: Optional[int] = None) -> Optional[str]

### Description
Gets a string from the specified address.

### Parameters
- **ea** (ea_t) - Required - The effective address.
- **max_length** (Optional[int]) - Optional - Maximum string length to read.

### Returns
- **Optional[str]** - The string if it was successfully extracted or None in case of error.

### Raises
- **InvalidEAError** - If the effective address is invalid.
- **InvalidParameterError** - If max_length is specified but not positive.
```

--------------------------------

### create_qword_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Creates qword data items at consecutive addresses starting from the specified address.

```APIDOC
## create_qword_at(ea: ea_t, count: int = 1, force: bool = False) -> bool

### Description
Creates qword data items at consecutive addresses starting from the specified address.

### Parameters
- **ea** (ea_t) - Required - The effective address to start creating qwords.
- **count** (int) - Optional - Number of consecutive qword elements to create (default: 1).
- **force** (bool) - Optional - Forces creation overriding an existing item if there is one (default: False).

### Returns
- **bool** - True if successful, False otherwise.

### Raises
- **InvalidEAError** - If the effective address is invalid.
- **InvalidParameterError** - If count is not positive.
```

--------------------------------

### is_head(ea: ea_t) -> bool

Source: https://ida-domain.docs.hex-rays.com/ref/heads

Checks if the specified address is the start of an item.

```APIDOC
## is_head(ea: ea_t) -> bool

### Description
Check if the given address is a head (start of an item).

### Parameters
- **ea** (ea_t) - Required - Address to check.

### Returns
- **bool** - True if the address is a head, False otherwise.

### Raises
- **InvalidEAError** - If the effective address is not in the database range.
```

--------------------------------

### Entries.add

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Adds a new entry point to the IDA database.

```APIDOC
## add(address: ea_t, name: str, ordinal: Optional[int] = None, make_code: bool = True) -> bool

### Description
Adds a new entry point to the database at the specified address.

### Parameters
- **address** (ea_t) - Required - Linear address of the entry point
- **name** (str) - Required - Name for the entry point
- **ordinal** (Optional[int]) - Optional - Ordinal number (if None, uses address as ordinal)
- **make_code** (bool) - Optional - Whether to convert bytes to instructions (default: True)

### Returns
- **bool** - True if successful
```

--------------------------------

### get_flags_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Gets the flags for the specified address.

```APIDOC
## get_flags_at(ea: ea_t) -> ByteFlags

### Description
Gets the flags for the specified address masked with IVL and MS_VAL.

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **ByteFlags** - ByteFlags enum value representing the flags.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### get_flags

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Get function attribute flags.

```APIDOC
## get_flags(func: func_t) -> FunctionFlags

### Description
Get function attribute flags.

### Parameters
- **func** (func_t) - Function object.

### Returns
- **FunctionFlags** - FunctionFlags enum with all active flags.
```

--------------------------------

### SignatureFiles.create

Source: https://ida-domain.docs.hex-rays.com/ref/signature_files

Creates a new signature file instance.

```APIDOC
## SignatureFiles.create

### Description
Creates a new signature file object for use within the database context.
```

--------------------------------

### get_callers

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Gets all functions that call this function.

```APIDOC
## get_callers(func: func_t) -> List[func_t]

### Description
Gets all functions that call this function.

### Parameters
- **func** (func_t) - The function instance.

### Returns
- **List[func_t]** - List of calling functions.
```

--------------------------------

### get_callees

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Gets all functions called by this function.

```APIDOC
## get_callees(func: func_t) -> List[func_t]

### Description
Gets all functions called by this function.

### Parameters
- **func** (func_t) - The function instance.

### Returns
- **List[func_t]** - List of called functions.
```

--------------------------------

### Open and Explore an IDA Database

Source: https://ida-domain.docs.hex-rays.com/examples

Demonstrates opening an existing database and accessing basic properties like address ranges, metadata, and function counts.

```python
"""
Database exploration example for IDA Domain API.

This example demonstrates how to open an IDA database and explore its basic properties.
"""

import argparse
from dataclasses import asdict

import ida_domain
from ida_domain import Database
from ida_domain.database import IdaCommandOptions


def explore_database(db_path):
    """Explore basic database information."""
    ida_options = IdaCommandOptions(auto_analysis=True, new_database=False)
    with Database.open(db_path, ida_options) as db:
        # Get basic information
        print(f'Address range: {hex(db.minimum_ea)} - {hex(db.maximum_ea)}')

        # Get metadata
        print('Database metadata:')
        metadata_dict = asdict(db.metadata)
        for key, value in metadata_dict.items():
            print(f'  {key}: {value}')

        # Count functions
        function_count = 0
        for _ in db.functions:
            function_count += 1
        print(f'Total functions: {function_count}')


def main():
    """Main entry point with argument parsing."""
    parser = argparse.ArgumentParser(description='Database exploration example')
    parser.add_argument(
        '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
    )
    args = parser.parse_args()
    explore_database(args.input_file)


if __name__ == '__main__':
    main()
```

--------------------------------

### Analyze a file with Domain API

Source: https://ida-domain.docs.hex-rays.com/migration-guide

Demonstrates opening a database in headless mode using IdaCommandOptions to configure analysis and plugin settings.

```python
from pathlib import Path
from ida_domain import Database
from ida_domain.database import IdaCommandOptions

def analyze_file(input_path: Path, save=True):
    """Open and analyze a file using the Domain API."""
    opts = IdaCommandOptions(
        auto_analysis=True,       # Enable auto-analysis
        load_resources=True,      # Load Windows resources (helps find embedded PEs)
        # Disable Lumina via plugin options
        plugin_options="lumina:host=0.0.0.0;secondary_lumina:host=0.0.0.0",
    )

    with Database.open(str(input_path), args=opts, save_on_close=save) as db:
        for f in db.functions.get_all():
            print(db.functions.get_name(f))
```

--------------------------------

### ev_may_be_func

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Checks if a function can start at the specified instruction.

```C++
ev_may_be_func(insn: 'insn_t const *', state: int) -> int
```

--------------------------------

### Visit all instructions

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Recursively visits all sub-instructions in the tree using a visitor.

```python
for_all_instructions(
    visitor: MicroInstructionVisitor,
) -> int
```

--------------------------------

### Configure entry_point attribute

Source: https://ida-domain.docs.hex-rays.com/ref/database

Sets the entry point address for the database.

```python
entry_point: Optional[int] = None

```

--------------------------------

### is_head_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Checks if the address is the start of a data item.

```APIDOC
## is_head_at(ea: ea_t) -> bool

### Description
Checks if the address is the start of a data item.

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **bool** - True if head, False otherwise.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### get_lines_rendering_info hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Get lines rendering information.

```python
get_lines_rendering_info(
    out: lines_rendering_output_t,
    widget: 'TWidget const *',
    info: lines_rendering_input_t,
) -> None
```

--------------------------------

### Initialize FuncDetails

Source: https://ida-domain.docs.hex-rays.com/ref/types

Constructor for the function details object.

```python
FuncDetails()
```

--------------------------------

### Install MicrocodeLifter

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Registers a custom instruction lifter for handling unsupported processor instructions.

```python
install() -> None
```

--------------------------------

### Get Entry Point by Index

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Retrieves an entry point based on its index in the entry table.

```python
get_at_index(index: int) -> EntryInfo
```

--------------------------------

### create_struct_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Creates struct data items at consecutive addresses starting from the specified address.

```python
create_struct_at(
    ea: ea_t, count: int, tid: int, force: bool = False
) -> bool
```

```python
tif = db.types.parse_one_declaration(None, 'struct Point {int x; int y;};')
db.bytes.create_struct_at(ea, 1, tif.get_tid())
```

--------------------------------

### Initialize Entries

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Constructor for the Entries class requiring a database reference.

```python
Entries(database: Database)
```

--------------------------------

### ev_get_procmod

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Gets the processor module object pointer.

```APIDOC
## ev_get_procmod()

### Description
Get pointer to the processor module object.

### Returns
- **int** - Processor module object pointer as size_t.
```

--------------------------------

### Define CLI Entry Point for IDA Scripts

Source: https://ida-domain.docs.hex-rays.com/examples

Uses argparse to define input parameters for binary analysis scripts.

```python
def main():
    """Main entry point with argument parsing."""
    parser = argparse.ArgumentParser(description='Byte analysis example for IDA Domain API')
    parser.add_argument(
        '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
    )
    parser.add_argument(
        '-s',
        '--search-pattern',
        help='Text pattern to search for in the binary',
        type=str,
        default=None,
    )
    parser.add_argument(
        '-p',
        '--patch-demo',
        action='store_true',
        help='Demonstrate patching operations (modifies database temporarily)',
    )
    parser.add_argument(
        '-m',
        '--max-results',
        type=int,
        default=20,
        help='Maximum number of results to display (default: 20)',
    )

    args = parser.parse_args()
    analyze_bytes(args.input_file, args.search_pattern, args.patch_demo, args.max_results)


if __name__ == '__main__':
    main()
```

--------------------------------

### ev_get_frame_retsize

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Gets the size of the function return address.

```APIDOC
## ev_get_frame_retsize(frsize, pfn)

### Description
Get size of function return address in bytes.

### Parameters
- **frsize** (int *) - Out, frame size.
- **pfn** (func_t const *) - The function.

### Returns
- **int** - 1 if ok, 0 if not implemented.
```

--------------------------------

### to_text

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Get the decompiled pseudocode as text lines.

```APIDOC
## to_text(remove_tags=True)

### Description
Get the decompiled pseudocode as text lines.

### Parameters
- **remove_tags** (bool) - Optional. If True, strips IDA color/formatting tags.

### Returns
- **List[str]** - A list of strings, each a line of pseudocode.
```

--------------------------------

### Find return instructions

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Retrieves all return instructions in the pseudocode.

```python
find_return_instructions() -> List[PseudocodeInstruction]

```

--------------------------------

### get_original_word_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Get original word value (that was before patching).

```APIDOC
## get_original_word_at(ea: ea_t) -> Optional[int]

### Description
Get original word value (that was before patching).

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **Optional[int]** - The original word value, or None if an error occurs.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### Initialize StringListConfig

Source: https://ida-domain.docs.hex-rays.com/ref/strings

Configuration object for building the internal string list.

```python
StringListConfig(
    string_types: list[StringType] = lambda: [C](),
    min_len: int = 5,
    only_ascii_7bit: bool = True,
    only_existing: bool = False,
    ignore_instructions: bool = False,
)
```

--------------------------------

### get_original_qword_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Get original qword value (that was before patching).

```APIDOC
## get_original_qword_at(ea: ea_t) -> Optional[int]

### Description
Get original qword value (that was before patching).

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **Optional[int]** - The original qword value, or None if an error occurs.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### Database Initialization

Source: https://ida-domain.docs.hex-rays.com/ref/database

Initializes the Database class. Direct instantiation is discouraged in favor of Database.open().

```python
Database(hooks: Optional[HooksList] = None)
```

--------------------------------

### get_original_dword_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Get original dword value (that was before patching).

```APIDOC
## get_original_dword_at(ea: ea_t) -> Optional[int]

### Description
Get original dword value (that was before patching).

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **Optional[int]** - The original dword value, or None if an error occurs.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### create_struct_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Creates struct data items at consecutive addresses starting from the specified address.

```APIDOC
## create_struct_at(ea: ea_t, count: int, tid: int, force: bool = False) -> bool

### Description
Creates struct data items at consecutive addresses starting from the specified address.

### Parameters
- **ea** (ea_t) - Required - The effective address to start creating structs.
- **count** (int) - Required - Number of consecutive struct elements to create.
- **tid** (int) - Required - Structure type ID.
- **force** (bool) - Optional - Forces creation overriding an existing item if there is one (default: False).

### Returns
- **bool** - True if successful, False otherwise.

### Raises
- **InvalidEAError** - If the effective address is invalid.
- **InvalidParameterError** - If count is not positive or tid is invalid.
```

--------------------------------

### get_original_byte_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Get original byte value (that was before patching).

```APIDOC
## get_original_byte_at(ea: ea_t) -> Optional[int]

### Description
Get original byte value (that was before patching).

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **Optional[int]** - The original byte value, or None if an error occurs.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### Initialize DecompilerHooks

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Instantiate the convenience class for handling decompiler events.

```python
DecompilerHooks()
```

--------------------------------

### Implement FindAssignedVars Visitor

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Example implementation of a visitor that identifies variables within assignment expressions.

```python
class FindAssignedVars(PseudocodeParentVisitor):
    def visit_expression(self, expr):
        if expr.is_variable:
            parent = self.parent_expression()
            if parent and parent.is_assignment:
                ...
        return 0
```

--------------------------------

### for_all_instructions

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Iterates over all instructions in the block using a visitor.

```APIDOC
## for_all_instructions(visitor: MicroInstructionVisitor) -> int

### Description
Visit all instructions in this block (including sub-instructions). Returns non-zero if the visitor stopped early.
```

--------------------------------

### SignatureFiles.get_index

Source: https://ida-domain.docs.hex-rays.com/ref/signature_files

Gets the index of an applied signature file.

```APIDOC
## get_index(path: Path) -> int

### Description
Get index of applied signature file.

### Parameters
- **path** (Path) - Required - Path to the signature file.

### Returns
- **int** - Index of applied signature file, -1 if not found.
```

--------------------------------

### create_word_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Creates word data items at consecutive addresses starting from the specified address.

```python
create_word_at(
    ea: ea_t, count: int = 1, force: bool = False
) -> bool
```

--------------------------------

### get_chunks

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Get all chunks (main and tail) of a function.

```APIDOC
## get_chunks(func: func_t) -> Iterator[FunctionChunk]

### Description
Get all chunks (main and tail) of a function.

### Parameters
- **func** (func_t) - The function to analyze.

### Yields
- **FunctionChunk** - FunctionChunk objects representing each chunk.
```

--------------------------------

### Enumerate Entry Points

Source: https://ida-domain.docs.hex-rays.com/migration-guide

Migrates from tuple-based entry point extraction to using the EntryInfo dataclass.

```python
@dataclass(frozen=True)
class EntryInfo:
    ordinal: int        # export ordinal number
    address: int        # address of entry point
    name: str           # entry point name
    forwarder_name: str # forwarder name (or empty string)

    def has_forwarder(self) -> bool: ...
```

```python
def extract_exports():
    for _, ordinal, ea, name in idautils.Entries():
        forwarded_name = ida_entry.get_entry_forwarder(ordinal)
        if forwarded_name is None:
            yield Export(name), ea
        else:
            yield Export(forwarded_name), ea
```

```python
def extract_exports(db: Database):
    for entry in db.entries.get_all():
        if entry.has_forwarder():
            yield Export(entry.forwarder_name), entry.address
        else:
            yield Export(entry.name), entry.address
```

--------------------------------

### get_chunk_at

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Get function chunk at exact address.

```APIDOC
## get_chunk_at(ea: int) -> Optional[func_t]

### Description
Get function chunk at exact address.

### Parameters
- **ea** (int) - Address within function chunk.

### Returns
- **Optional[func_t]** - Function chunk or None.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### ev_init

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Callback triggered when the IDP module is loaded.

```APIDOC
## ev_init(idp_modname)

### Description
The IDP module is just loaded.

### Parameters
- **idp_modname** (str) - Processor module name.

### Returns
- **int** - <0 on failure.
```

--------------------------------

### shift_operand

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Shifts the operand start by a specified number of bytes.

```APIDOC
## shift_operand(offset: int) -> bool

### Description
Shift the operand start by offset bytes. Positive offsets move toward higher bytes (shrink from the low end), negative offsets move toward lower bytes (grow from the high end).

### Parameters
- **offset** (int) - Number of bytes to shift.

### Returns
- **bool** - True on success.
```

--------------------------------

### SignatureFiles.create

Source: https://ida-domain.docs.hex-rays.com/ref/signature_files

Creates signature files (.pat and .sig) from the current database.

```APIDOC
## create(pat_only: bool = False) -> List[str] | None

### Description
Create signature files (.pat and .sig) from current database.

### Parameters
- **pat_only** (bool) - Optional - If true, generate only PAT file.

### Returns
- **List[str] | None** - A list containing paths to the generated files. Returns None in case of failure.
```

--------------------------------

### Get operand size

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Returns the operand size in bytes.

```python
size: int

```

--------------------------------

### Initialize PseudocodeDo

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Wrapper for an IDA cdo_t do-while loop structure.

```python
PseudocodeDo(
    raw: cdo_t,
    _parent_insn: Optional[PseudocodeInstruction] = None,
)
```

```python
body: PseudocodeInstruction
```

```python
condition: PseudocodeExpression
```

```python
raw_do: cdo_t
```

--------------------------------

### Initialize PseudocodeWhile

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Wrapper for IDA cwhile_t objects.

```python
PseudocodeWhile(
    raw: cwhile_t,
    _parent_insn: Optional[PseudocodeInstruction] = None,
)
```

--------------------------------

### get_between(start: ea_t, end: ea_t) -> Iterator[insn_t]

Source: https://ida-domain.docs.hex-rays.com/ref/instructions

Retrieves instructions between the specified addresses.

```APIDOC
## get_between(start: ea_t, end: ea_t) -> Iterator[insn_t]

### Description
Retrieves instructions between the specified addresses.

### Parameters
- **start** (ea_t) - Required - Start of the address range.
- **end** (ea_t) - Required - End of the address range.

### Returns
- **Iterator[insn_t]** - An instruction iterator.

### Raises
- **InvalidEAError** - If start or end are not within database bounds.
- **InvalidParameterError** - If start >= end.
```

--------------------------------

### Add Entry Point

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Adds a new entry point to the database with optional ordinal and code conversion settings.

```python
add(
    address: ea_t,
    name: str,
    ordinal: Optional[int] = None,
    make_code: bool = True,
) -> bool
```

--------------------------------

### Get microcode graph

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Retrieves the underlying MicroGraph object.

```python
get_graph() -> MicroGraph
```

--------------------------------

### get_instructions

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Retrieves all instructions within the given function.

```APIDOC
## get_instructions(func: func_t) -> Iterator[insn_t]

### Description
Retrieves all instructions within the given function.

### Parameters
- **func** (func_t) - The function instance.

### Returns
- **Iterator[insn_t]** - An iterator over all instructions in the function.
```

--------------------------------

### ev_get_dbr_opnum

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Gets the operand number for debugger reference view.

```APIDOC
## ev_get_dbr_opnum(opnum, insn)

### Description
Get the number of the operand to be displayed in the debugger reference view.

### Parameters
- **opnum** (int *) - Operand number (output, -1 means no such operand).
- **insn** (insn_t const *) - The instruction.

### Returns
- **int** - 0 if unimplemented, 1 if implemented.
```

--------------------------------

### Implement custom expression visitor

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Example of extending PseudocodeExpressionVisitor to collect call expressions.

```python
class FindCalls(PseudocodeExpressionVisitor):
    def __init__(self):
        super().__init__()
        self.calls = []

    def visit_expression(self, expr):
        if expr.is_call:
            self.calls.append(expr)
        return 0

visitor = FindCalls()
visitor.apply_to(decomp.body)
```

--------------------------------

### Execute build_args method

Source: https://ida-domain.docs.hex-rays.com/ref/database

Constructs the command line arguments string from configured options.

```python
build_args() -> str

```

--------------------------------

### get_previous_address

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Gets the previous valid address before the specified address.

```APIDOC
## get_previous_address(ea: ea_t) -> Optional[ea_t]

### Description
Gets the previous valid address before the specified address.

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **Optional[ea_t]** - Previous valid address.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### get_next_address

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Gets the next valid address after the specified address.

```APIDOC
## get_next_address(ea: ea_t) -> Optional[ea_t]

### Description
Gets the next valid address after the specified address.

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **Optional[ea_t]** - Next valid address or None.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### walk_instructions

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Iterates over all instructions in the subtree rooted at the current instruction.

```APIDOC
## walk_instructions()

### Description
Iterate over all instructions in the subtree rooted at this instruction.

### Signature
`walk_instructions() -> Iterator[PseudocodeInstruction]`
```

--------------------------------

### Initialize and build a union type

Source: https://ida-domain.docs.hex-rays.com/ref/types

Demonstrates the workflow for creating a union, adding members with primitive types, and finalizing the construction.

```python
>>> builder = db.types.create_union("MyUnion") builder.add_member("as_int", db.types.create_primitive(4)) builder.add_member("as_float", db.types.create_primitive(4)) my_union = builder.build()
```

--------------------------------

### get_data_size_at

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Gets the size of the data item at the specified address.

```APIDOC
## get_data_size_at(ea: ea_t) -> int

### Description
Gets the size of the data item at the specified address.

### Parameters
- **ea** (ea_t) - Required - The effective address.

### Returns
- **int** - Size of the data item in bytes.

### Raises
- **InvalidEAError** - If the effective address is invalid.
```

--------------------------------

### Get function signature

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Retrieves the type signature of the function.

```python
get_signature(func: func_t) -> Optional[str]
```

--------------------------------

### Initialize PseudocodeInstruction

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Constructor for creating a wrapper around an IDA cinsn_t instruction node.

```python
PseudocodeInstruction(
    raw: cinsn_t, _parent: Optional[Any] = None
)
```

--------------------------------

### Get function name

Source: https://ida-domain.docs.hex-rays.com/ref/functions

Retrieves the name of the function as a string.

```python
get_name(func: func_t) -> str
```

--------------------------------

### Create byte data at address

Source: https://ida-domain.docs.hex-rays.com/ref/bytes

Creates one or more byte data items starting at the given address.

```python
create_byte_at(
    ea: ea_t, count: int = 1, force: bool = False
) -> bool
```

--------------------------------

### Initialize Pseudocode

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Constructor for the Pseudocode interface.

```python
Pseudocode(database: Database)
```

--------------------------------

### ev_init hook

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Triggered when the IDP module is initially loaded.

```python
ev_init(idp_modname: str) -> int
```

--------------------------------

### Get Forwarders

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Returns an iterator of ForwarderInfo for all entries that have forwarders.

```python
get_forwarders() -> Iterator[ForwarderInfo]
```

--------------------------------

### Initialize PseudocodeFunction

Source: https://ida-domain.docs.hex-rays.com/ref/pseudocode

Constructor signature for the PseudocodeFunction wrapper.

```python
PseudocodeFunction(raw: cfuncptr_t)
```

--------------------------------

### Uninstall MicrocodeLifter

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Removes a previously installed custom instruction lifter.

```python
uninstall() -> None
```

--------------------------------

### Get Total Entry Point Count

Source: https://ida-domain.docs.hex-rays.com/ref/entries

Returns the total number of entry points defined in the program.

```python
get_count() -> int
```

--------------------------------

### Get Hex-Rays Version

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Retrieves the current decompiler version string.

```python
get_hexrays_version() -> str
```

--------------------------------

### Manage Type Information Libraries with IDA Domain

Source: https://ida-domain.docs.hex-rays.com/examples

Demonstrates creating a new type library from C declarations, importing types from an external library, and exporting existing database types to a file.

```python
#!/usr/bin/env python3
"""
Types example for IDA Domain API.

This example demonstrates how to work with IDA's type information libraries.
"""

import argparse
import tempfile
from pathlib import Path

import ida_domain
from ida_domain import Database


def print_section_header(title: str, char: str = '=') -> None:
    """Print a formatted section header for better output organization."""
    print(f'\n{char * 60}')
    print(f' {title}')
    print(f'{char * 60}')


def print_subsection_header(title: str) -> None:
    """Print a formatted subsection header."""
    print(f'\n--- {title} ---')


declarations = """
typedef unsigned char uint8_t;
typedef unsigned int uint32_t;

struct STRUCT_EXAMPLE
{
    char *text;
    unsigned int length;
    uint32_t reserved;
};

"""


def create_types(db: Database, library_path: Path):
    """Create a type library and fill it with types parsed from declaration"""

    til = db.types.create_library(library_path, 'Example type information library')
    db.types.parse_declarations(til, declarations)
    db.types.save_library(til, library_path)
    db.types.unload_library(til)


def import_types(db: Database, library_path: Path):
    """Import all types from external library"""

    til = db.types.load_library(library_path)

    print_subsection_header(f'Type names from external library {library_path}')
    for name in db.types.get_all(library=til):
        print(name)

    print_subsection_header('Type information objects in local library (before import)')
    for item in sorted(list(db.types), key=lambda i: i.get_ordinal()):
        print(f'{item.get_ordinal()}. {item}')

    db.types.import_from_library(til)

    print_subsection_header('Type information objects in local library (after import)')
    for item in sorted(list(db.types), key=lambda i: i.get_ordinal()):
        print(f'{item.get_ordinal()}. {item}')

    db.types.unload_library(til)


def export_types(db: Database, library_path: Path):
    """Export all types from database to external library"""

    til = db.types.create_library(library_path, 'Exported type library')
    db.types.export_to_library(til)
    db.types.save_library(til, library_path)
    db.types.unload_library(til)

    print_subsection_header(f'Types exported to {library_path}')
    til = db.types.load_library(library_path)
    for t in db.types.get_all(library=til):
        print(t)
    db.types.unload_library(til)


def main():
    parser = argparse.ArgumentParser(
        description=f'IDA Domain usage example, version {ida_domain.__version__}'
    )
    parser.add_argument(
        '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
    )
    args = parser.parse_args()

    library_dir = Path(tempfile.gettempdir()) / 'ida_domain_example'
    library_dir.mkdir(parents=True, exist_ok=True)
    library_create_path = library_dir / 'new.til'
    library_import_path = library_dir / 'new.til'
    library_export_path = library_dir / 'exported.til'

    print_section_header('Working with type information libraries')

    with Database.open(args.input_file) as db:
        create_types(db, library_create_path)
        import_types(db, library_import_path)
        export_types(db, library_export_path)


if __name__ == '__main__':
    main()
```

--------------------------------

### Get operand type

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Returns the operand type as a MicroOperandType enum.

```python
type: MicroOperandType

```

--------------------------------

### Initialize BitfieldDetails

Source: https://ida-domain.docs.hex-rays.com/ref/types

Constructor for the BitfieldDetails class.

```python
BitfieldDetails()
```

--------------------------------

### SignatureFiles.apply

Source: https://ida-domain.docs.hex-rays.com/ref/signature_files

Applies signature files to the current database.

```APIDOC
## apply(path: Path, probe_only: bool = False) -> List[FileInfo]

### Description
Applies signature files to the current database. Returns a list of FileInfo objects containing application details.

### Parameters
- **path** (Path) - Required - Path to the signature file or directory with sig files.
- **probe_only** (bool) - Optional - If true, signature files are only probed (apply operation is undone).

### Returns
- **List[FileInfo]** - A list of FileInfo objects containing application details.
```

--------------------------------

### Get sub-instruction

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Returns the nested MicroInstruction for mop_d operands, or None.

```python
sub_instruction: Optional[MicroInstruction]

```

--------------------------------

### Get register name

Source: https://ida-domain.docs.hex-rays.com/ref/microcode

Returns the human-readable micro-register name, or None.

```python
register_name: Optional[str]

```

--------------------------------

### create_desktop_widget

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Creates a widget to be placed in the widget tree during desktop creation.

```APIDOC
## create_desktop_widget(title, cfg)

### Description
Create a widget to be placed in the widget tree (at desktop-creation time).

### Parameters
- **title** (str) - Required - The widget title.
- **cfg** (jobj_wrapper_t) - Required - Configuration object.

### Returns
- **PyObject*** - The created widget, or None.
```

--------------------------------

### ev_lower_func_type

Source: https://ida-domain.docs.hex-rays.com/ref/hooks

Get function arguments to convert to pointers when lowering prototype.

```APIDOC
## ev_lower_func_type

### Description
Get function arguments to convert to pointers when lowering prototype. The processor module can also modify 'fti' for non-standard conversions.

### Parameters
- **argnums** (intvec_t *) - Required - Output, numbers of arguments to convert to pointers.
- **fti** (func_type_data_t) - Required - Inout, function type details.

### Returns
- **int** - 0 if not implemented, 1 if argnums was filled, 2 if argnums was filled and fti substantially changed.
```
Tokens:
Raw