Instructions

instructions

Classes:

• Instructions –

  Provides access to instruction-related operations using structured operand hierarchy.

Instructions

Instructions(database: Database)

Bases: DatabaseEntity

Provides access to instruction-related operations using structured operand hierarchy.

Can be used to iterate over all instructions in the opened database.

Parameters:

• database (Database) –

  Reference to the active IDA database.

Methods:

• breaks_sequential_flow –

  Check if the instruction stops sequential control flow.

• call_targets –

  Retrieves the direct call targets of the instruction.

• create –

  Forces creation of an instruction at the specified address.

• get_all –

  Retrieves an iterator over all instructions in the database.

• get_at –

  Decodes the instruction at the specified address.

• get_between –

  Retrieves instructions between the specified addresses.

• get_disassembly –

  Retrieves the disassembled string representation of the given instruction.

• get_mnemonic –

  Retrieves the mnemonic of the given instruction.

• get_next –

  Decodes the instruction that follows the one at ea in execution flow.

• get_operand –

  Get a specific operand from the instruction.

• get_operands –

  Get all operands from the instruction.

• get_operands_count –

  Retrieve the operands number of the given instruction.

• get_previous –

  Decodes the instruction that precedes the one at ea in execution flow.

• has_fall_through –

  Checks whether the instruction passes execution to the next one.

• has_operand –

  Checks whether operand index exists on the given instruction.

• is_call_instruction –

  Check if the instruction is a call instruction.

• is_conditional_jump –

  Checks whether the instruction is a conditional jump.

• is_indirect_jump_or_call –

  Check if the instruction passes execution using indirect jump or call

• is_jump –

  Checks whether the instruction is a jump.

• is_return –

  Checks whether the instruction is a return.

• is_valid –

  Checks if the given instruction is valid.

• jump_targets –

  Retrieves the direct jump targets of the instruction.

• text –

  Retrieves the tagged disassembly text of the given instruction.

Attributes:

• database (Database) –

  Get the database reference, guaranteed to be non-None when called from

• m_database –

database property

database: Database

Get the database reference, guaranteed to be non-None when called from methods decorated with @check_db_open.

Returns:

• Database –

  The active database instance.

Note

This property should only be used in methods decorated with @check_db_open, which ensures m_database is not None.

m_database instance-attribute

m_database = database

breaks_sequential_flow

breaks_sequential_flow(insn: insn_t) -> bool

Check if the instruction stops sequential control flow.

This includes return instructions, unconditional jumps, halt instructions, and any other instruction that doesn't pass execution to the next sequential instruction.

Parameters:

• insn (insn_t) –

  The instruction to analyze.

Returns:

• bool –

  True if this instruction has the CF_STOP flag set.

call_targets

call_targets(insn: insn_t) -> Iterator[ea_t]

Retrieves the direct call targets of the instruction.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• Iterator[ea_t] –

  An iterator over the called addresses.

create

create(ea: ea_t) -> int

Forces creation of an instruction at the specified address.

Parameters:

• ea (ea_t) –

  The effective address to convert to an instruction.

Returns:

• int –

  The length in bytes of the created instruction, or 0 if none was

• int –

  created.

Raises:

• InvalidEAError –

  If the effective address is invalid.

get_all

get_all() -> Iterator[insn_t]

Retrieves an iterator over all instructions in the database.

Returns:

• Iterator[insn_t] –

  An iterator over the instructions.

get_at

get_at(ea: ea_t) -> Optional[insn_t]

Decodes the instruction at the specified address.

Parameters:

• ea (ea_t) –

  The effective address of the instruction.

Returns:

• Optional[insn_t] –

  An insn_t instance, if fails returns None.

Raises:

• InvalidEAError –

  If the effective address is invalid.

get_between

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

Retrieves instructions between the specified addresses.

Parameters:

• start (ea_t) –

  Start of the address range.

• end (ea_t) –

  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.

get_disassembly

get_disassembly(
    insn: insn_t, remove_tags: bool = True
) -> Optional[str]

Retrieves the disassembled string representation of the given instruction.

Parameters:

• insn (insn_t) –

  The instruction to disassemble.

• remove_tags (bool, default: True ) –

  If True, removes IDA color/formatting tags from the output.

Returns:

• Optional[str] –

  The disassembly as string, if fails, returns None.

get_mnemonic

get_mnemonic(insn: insn_t) -> Optional[str]

Retrieves the mnemonic of the given instruction.

Parameters:

• insn (insn_t) –

  The instruction to analyze.

Returns:

• Optional[str] –

  A string representing the mnemonic of the given instruction.

• Optional[str] –

  If retrieving fails, returns None.

get_next

get_next(ea: ea_t) -> Optional[insn_t]

Decodes the instruction that follows the one at ea in execution flow.

Usually just the next instruction by address - nearly everything falls through, calls and conditional jumps included. The special cases:

• ea never falls through, e.g. an unconditional jump, a switch dispatch resolved by analysis, or a call that never returns: its jump or call target is returned, the first one by address when there are several. Use db.xrefs.jumps_from_ea and db.xrefs.calls_from_ea to list them all.
• ea breaks execution flow (e.g. return) or no target is known (an unresolved indirect jump): None.

Flow is many-to-many, so get_previous on the result won't always lead back to ea. Use db.heads.get_next to walk addresses instead of flow.

Parameters:

• ea (ea_t) –

  The effective address of the instruction.

Returns:

• Optional[insn_t] –

  An insn_t instance, or None when ea has no known successor.

Raises:

• InvalidEAError –

  If the effective address is invalid.

get_operand

get_operand(
    insn: insn_t, index: int
) -> Optional[Operand] | None

Get a specific operand from the instruction.

Parameters:

• insn (insn_t) –

  The instruction to analyze.

• index (int) –

  The operand index (0, 1, 2, etc.).

Returns:

• Optional[Operand] | None –

  An Operand instance of the appropriate type, or None

• Optional[Operand] | None –

  if the index is invalid or operand is void.

get_operands

get_operands(insn: insn_t) -> List[Operand]

Get all operands from the instruction.

Parameters:

• insn (insn_t) –

  The instruction to analyze.

Returns:

• List[Operand] –

  A list of Operand instances of appropriate types (excludes void operands).

get_operands_count

get_operands_count(insn: insn_t) -> int

Retrieve the operands number of the given instruction.

Parameters:

• insn (insn_t) –

  The instruction to analyze.

Returns:

• int –

  An integer representing the number, if error, the number is negative.

get_previous

get_previous(ea: ea_t) -> Optional[insn_t]

Decodes the instruction that precedes the one at ea in execution flow.

Usually just the previous instruction by address, falling through into ea. The special cases:

• a jump or call from a lower address targets ea: that instruction is returned instead, the first one by address when several do. A jump or call from a higher address, like a loop jumping back, doesn't count. Use db.xrefs.jumps_to_ea and db.xrefs.calls_to_ea to list them all.
• nothing falls through into ea and no jump or call from a lower address targets it, e.g. the program entry point or code only reached from higher addresses: None.

Flow is many-to-many, so get_next on the result won't always lead back to ea. Use db.heads.get_previous to walk addresses instead of flow.

Parameters:

• ea (ea_t) –

  The effective address of the instruction.

Returns:

• Optional[insn_t] –

  An insn_t instance, or None when ea has no known predecessor.

Raises:

• InvalidEAError –

  If the effective address is invalid.

has_fall_through

has_fall_through(insn: insn_t) -> bool

Checks whether the instruction passes execution to the next one.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• bool –

  True if the instruction can fall through, False otherwise.

has_operand

has_operand(insn: insn_t, index: int) -> bool

Checks whether operand index exists on the given instruction.

Parameters:

• insn (insn_t) –

  The instruction.

• index (int) –

  The operand index.

Returns:

• bool –

  True if the index refers to a present (non-void) operand.

is_call_instruction

is_call_instruction(insn: insn_t) -> bool

Check if the instruction is a call instruction.

Parameters:

• insn (insn_t) –

  The instruction to analyze.

Returns:

• bool –

  True if this is a call instruction.

is_conditional_jump

is_conditional_jump(insn: insn_t) -> bool

Checks whether the instruction is a conditional jump.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• bool –

  True if the instruction is a conditional jump, False otherwise.

is_indirect_jump_or_call

is_indirect_jump_or_call(insn: insn_t) -> bool

Check if the instruction passes execution using indirect jump or call

Parameters:

• insn (insn_t) –

  The instruction to analyze.

Returns: True if this instruction has the CF_JUMP flag set.

is_jump

is_jump(insn: insn_t) -> bool

Checks whether the instruction is a jump.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• bool –

  True if the instruction is a jump, False otherwise.

is_return

is_return(insn: insn_t) -> bool

Checks whether the instruction is a return.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• bool –

  True if the instruction is a return, False otherwise.

is_valid

is_valid(insn: insn_t) -> bool

Checks if the given instruction is valid.

Parameters:

• insn (insn_t) –

  The instruction to validate.

Returns:

• bool –

  True if the instruction is valid, False otherwise.

jump_targets

jump_targets(insn: insn_t) -> Iterator[ea_t]

Retrieves the direct jump targets of the instruction.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• Iterator[ea_t] –

  An iterator over the jump target addresses.

text

text(insn: insn_t) -> Optional[str]

Retrieves the tagged disassembly text of the given instruction.

Convenience wrapper over get_disassembly that keeps IDA color/formatting tags.

Parameters:

• insn (insn_t) –

  The instruction.

Returns:

• Optional[str] –

  The tagged disassembly text, or None if none could be generated.