function module¶
Class |
Description |
---|---|
- class ArchAndAddr[source]
Bases:
object
ArchAndAddr(arch: ‘architecture.Architecture’, addr: int)
- __init__(arch: Architecture, addr: int) None
- Parameters:
arch (Architecture) –
addr (int) –
- Return type:
None
- addr: int
- arch: Architecture
- class BasicBlockList[source]
Bases:
object
- __init__(function: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction)[source]
- Parameters:
function (Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction) –
- class DisassemblySettings[source]
Bases:
object
- __init__(handle: LP_BNDisassemblySettings | None = None)[source]
- Parameters:
handle (LP_BNDisassemblySettings | None) –
- static default_graph_settings() DisassemblySettings [source]
- Return type:
- static default_linear_settings() DisassemblySettings [source]
- Return type:
- static default_settings() DisassemblySettings [source]
- Return type:
- is_option_set(option: DisassemblyOption) bool [source]
- Parameters:
option (DisassemblyOption) –
- Return type:
- set_option(option: DisassemblyOption, state: bool = True) None [source]
- Parameters:
option (DisassemblyOption) –
state (bool) –
- Return type:
None
- property max_symbol_width: int
- property width: int
- class DisassemblyTextLine[source]
Bases:
object
DisassemblyTextLine(tokens: List[ForwardRef(‘InstructionTextToken’)], address: Optional[int] = None, il_instr: Union[ForwardRef(‘lowlevelil.LowLevelILInstruction’), ForwardRef(‘mediumlevelil.MediumLevelILInstruction’), ForwardRef(‘highlevelil.HighLevelILInstruction’), NoneType] = None, color: Union[ForwardRef(‘_highlight.HighlightColor’), binaryninja.enums.HighlightStandardColor, NoneType] = None, tags: Optional[List[ForwardRef(‘binaryview.Tag’)]] = None, type_info: Optional[binaryninja.function.DisassemblyTextLineTypeInfo] = None)
- __init__(tokens: List[InstructionTextToken], address: int | None = None, il_instr: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None = None, color: HighlightColor | HighlightStandardColor | None = None, tags: List[Tag] | None = None, type_info: DisassemblyTextLineTypeInfo | None = None)[source]
- Parameters:
tokens (List[InstructionTextToken]) –
address (int | None) –
il_instr (LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None) –
color (HighlightColor | HighlightStandardColor | None) –
type_info (DisassemblyTextLineTypeInfo | None) –
- property address_and_indentation_tokens
- property address_and_indentation_width
- highlight: HighlightColor
- il_instruction: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None
- tokens: List[InstructionTextToken]
- property total_width
- type_info: DisassemblyTextLineTypeInfo | None
- class DisassemblyTextLineTypeInfo[source]
Bases:
object
DisassemblyTextLineTypeInfo(parent_type: Optional[ForwardRef(‘types.Type’)], field_index: int, offset: int)
- field_index: int
- offset: int
- class DisassemblyTextRenderer[source]
Bases:
object
- __init__(func: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None = None, settings: DisassemblySettings | None = None, handle: BNDisassemblySettings | None = None)[source]
- Parameters:
func (Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None) –
settings (DisassemblySettings | None) –
handle (BNDisassemblySettings | None) –
- add_integer_token(tokens: List[InstructionTextToken], int_token: InstructionTextToken, addr: int, arch: Architecture | None = None) None [source]
- Parameters:
tokens (List[InstructionTextToken]) –
int_token (InstructionTextToken) –
addr (int) –
arch (Architecture | None) –
- Return type:
None
- add_stack_var_reference_tokens(tokens: List[InstructionTextToken], ref: StackVariableReference) None [source]
- Parameters:
tokens (List[InstructionTextToken]) –
ref (StackVariableReference) –
- Return type:
None
- add_symbol_token(tokens: List[InstructionTextToken], addr: int, size: int, operand: int | None = None) bool [source]
- get_disassembly_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None] [source]
- Parameters:
addr (int) –
- Return type:
Generator[Tuple[DisassemblyTextLine | None, int], None, None]
- get_instruction_annotations(addr: int) List[InstructionTextToken] [source]
- Parameters:
addr (int) –
- Return type:
- get_instruction_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None] [source]
- Parameters:
addr (int) –
- Return type:
Generator[Tuple[DisassemblyTextLine | None, int], None, None]
- static is_integer_token(token: InstructionTextToken) bool [source]
- Parameters:
token (InstructionTextToken) –
- Return type:
- post_process_lines(addr: int, length: int, in_lines: str | List[str] | List[DisassemblyTextLine], indent_spaces: str = '')[source]
- wrap_comment(lines: List[DisassemblyTextLine], cur_line: DisassemblyTextLine, comment: str, has_auto_annotations: bool, leading_spaces: str = ' ', indent_spaces: str = '') None [source]
- Parameters:
lines (List[DisassemblyTextLine]) –
cur_line (DisassemblyTextLine) –
comment (str) –
has_auto_annotations (bool) –
leading_spaces (str) –
indent_spaces (str) –
- Return type:
None
- property arch: Architecture
- property basic_block: BasicBlock | None
- property function: Function
- property has_data_flow: bool
- property il: bool
- property il_function: LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None
- property settings: DisassemblySettings
- class Function[source]
Bases:
object
- __init__(view: BinaryView | None = None, handle: LP_BNFunction | None = None)[source]
- Parameters:
view (BinaryView | None) –
handle (LP_BNFunction | None) –
- add_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None [source]
add_guided_source_blocks
adds blocks to the guided source block list for this function. The specified blocks will have their direct outgoing branch targets analyzed. This automatically enables theanalysis.guided.enable
setting if it is not already enabled.- Parameters:
addresses (List[Tuple[Architecture, int]]) – List of (architecture, address) tuples to add
addresses –
- Return type:
None
- add_tag(tag_type: str, data: str, addr: int | None = None, auto: bool = False, arch: Architecture | None = None)[source]
add_tag
creates and adds aTag
object on either a function, or on an address inside of a function.“Function tags” appear at the top of a function and are a good way to label an entire function with some information. If you include an address when you call Function.add_tag, you’ll create an “address tag”. These are good for labeling specific instructions.
For tagging arbitrary data, consider
add_tag
.- Parameters:
tag_type (str) – The name of the tag type for this Tag
data (str) – additional data for the Tag
addr (int) – address at which to add the tag
auto (bool) – Whether or not an auto tag
arch (Architecture) – Architecture for the block in which the Tag is added (optional)
- Example:
>>> current_function.add_tag("Important", "I think this is the main function") >>> current_function.add_tag("Crashes", "Nullpointer dereference", here)
Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.
- add_user_code_ref(from_addr: int, to_addr: int, arch: Architecture | None = None) None [source]
add_user_code_ref
places a user-defined cross-reference from the instruction at the given address and architecture to the specified target address. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, useremove_user_code_ref
.- Parameters:
from_addr (int) – virtual address of the source instruction
to_addr (int) – virtual address of the xref’s destination.
arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.add_user_code_ref(here, 0x400000)
- add_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None [source]
add_user_type_field_ref
places a user-defined type field cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, useremove_user_type_field_ref
.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
offset (int) – offset of the field, relative to the type
from_arch (Architecture) – (optional) architecture of the source instruction
size (int) – (optional) the size of the access
- Return type:
None
- Example:
>>> current_function.add_user_type_field_ref(here, 'A', 0x8)
- add_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None [source]
add_user_type_ref
places a user-defined type cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, useremove_user_type_ref
.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
from_arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.add_user_code_ref(here, 'A')
- analyze() None [source]
analyze
causes this function to be analyzed if it’s out of date. This function does not wait for the analysis to finish.- Return type:
None
- apply_auto_discovered_type(func_type: str | Type | TypeBuilder) None [source]
- Parameters:
func_type (str | Type | TypeBuilder) –
- Return type:
None
- apply_imported_types(sym: CoreSymbol, type: str | Type | TypeBuilder | None = None) None [source]
- Parameters:
sym (CoreSymbol) –
type (str | Type | TypeBuilder | None) –
- Return type:
None
- check_for_debug_report(name: str) bool [source]
check_for_debug_report
checks if a function has had a debug report requested with the given name, and then, if one has been requested, clears the request internally so that future calls to this function for that report will return False.If a function has had a debug report requested, it is the caller of this function’s responsibility to actually generate and show the debug report. You can use
binaryninja.interaction.show_report_collection
for showing a debug report from a workflow activity.
- clear_user_var_value(var: Variable, def_addr: int, after: bool = True) None [source]
Clears a previously defined user variable value.
- collapse_region(hash)[source]
Collapse a region during rendering :param hash: Hash value of region
- create_auto_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None [source]
- Parameters:
offset (int) –
var_type (str | Type | TypeBuilder) –
name (str) –
- Return type:
None
- create_auto_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None [source]
- create_graph(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph [source]
Create a flow graph with the disassembly of this function.
Note
This graph waits for function analysis, so Workflow Activities should instead use
create_graph_immediate
to create graphs with the function contents as-is.- Parameters:
graph_type (FunctionViewType | FunctionGraphType | str) – IL form of the disassembly in the graph
settings (DisassemblySettings | None) – Optional settings for the disassembly text renderer
- Returns:
Flow graph object
- Return type:
- create_graph_immediate(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph [source]
Create a flow graph with the disassembly of this function, specifically using the instructions as they are in the function when this is called. You probably want to use this if you are creating a Debug Report in a Workflow Activity.
- Parameters:
graph_type (FunctionViewType | FunctionGraphType | str) – IL form of the disassembly in the graph
settings (DisassemblySettings | None) – Optional settings for the disassembly text renderer
- Returns:
Flow graph object
- Return type:
- create_user_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None [source]
- Parameters:
offset (int) –
var_type (str | Type | TypeBuilder) –
name (str) –
- Return type:
None
- create_user_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None [source]
- expand_all()[source]
Expand all regions in the function
- expand_region(hash)[source]
Un-collapse a region during rendering :param hash: Hash value of region
- get_all_user_var_values() Dict[Variable, Dict[ArchAndAddr, PossibleValueSet]] [source]
Returns a map of current defined user variable values.
- Returns:
Map of user current defined user variable values and their definition sites.
- Type:
dict of (Variable, dict of (ArchAndAddr, PossibleValueSet))
- Return type:
- get_basic_block_at(addr: int, arch: Architecture | None = None) BasicBlock | None [source]
get_basic_block_at
returns the BasicBlock of the optionally specified Architecturearch
at the given addressaddr
.- Parameters:
addr (int) – Address of the BasicBlock to retrieve.
arch (Architecture) – (optional) Architecture of the basic block if different from the Function’s self.arch
- Example:
>>> current_function.get_basic_block_at(current_function.start) <block: x86_64@0x100000f30-0x100000f50>
- Return type:
BasicBlock | None
- get_block_annotations(addr: int, arch: Architecture | None = None) List[List[InstructionTextToken]] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_call_reg_stack_adjustment(addr: int, arch: Architecture | None = None) Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]
- get_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, arch: Architecture | None = None) RegisterStackAdjustmentWithConfidence [source]
- Parameters:
addr (int) –
reg_stack (RegisterStackName | ILRegisterStack | RegisterStackIndex) –
arch (Architecture | None) –
- Return type:
- get_call_stack_adjustment(addr: int, arch: Architecture | None = None) OffsetWithConfidence [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_call_type_adjustment(addr: int, arch: Architecture | None = None) Type | None [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
Type | None
- get_callee_for_analysis(platform: Platform, addr: int, exact: bool = False) Function | None [source]
get_callee_for_analysis
retrieves the callee function for the specified address and platform.Note
This method is intended for use by architecture plugins only.
- get_constant_data(state: RegisterValueType, value: int, size: int = 0) DataBuffer [source]
- Parameters:
state (RegisterValueType) –
value (int) –
size (int) –
- Return type:
- get_constant_data_and_builtin(state: RegisterValueType, value: int, size: int = 0) Tuple[DataBuffer, BuiltinType] [source]
- Parameters:
state (RegisterValueType) –
value (int) –
size (int) –
- Return type:
- get_constants_referenced_by(addr: int, arch: Architecture | None = None) List[ConstantReference] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_constants_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[ConstantReference] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_early_return(addr: int | HighLevelILInstruction) EarlyReturn [source]
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- get_expr_folding(addr: int | HighLevelILInstruction) ExprFolding [source]
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- get_flags_read_by_lifted_il_instruction(i: InstructionIndex) List[FlagName] [source]
- Parameters:
i (InstructionIndex) –
- Return type:
List[FlagName]
- get_flags_written_by_lifted_il_instruction(i: InstructionIndex) List[FlagName] [source]
- Parameters:
i (InstructionIndex) –
- Return type:
List[FlagName]
- get_function_tags(auto: bool | None = None, tag_type: str | None = None) List[Tag] [source]
get_function_tags
gets a list of function Tags for the function.
- get_guided_source_blocks() List[Tuple[Architecture, int]] [source]
get_guided_source_blocks
returns the current list of guided source blocks for this function. These blocks have their direct outgoing branch targets analyzed.- Return type:
List[Tuple[Architecture, int]]
- Returns:
List of (architecture, address) tuples representing current guided source blocks
- get_hlil_var_refs(var: Variable) List[ILReferenceSource] [source]
get_hlil_var_refs
returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag.- Parameters:
var (Variable) – Variable for which to query the xref
- Returns:
List of IL References for the given variable
- Return type:
- Example:
>>> mlil_var = current_hlil[0].operands[0] >>> current_function.get_hlil_var_refs(mlil_var)
- get_hlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource] [source]
get_hlil_var_refs_from
returns a list of variables referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used.- Parameters:
addr (int) – virtual address to query for variable references
length (int) – optional length of query
arch (Architecture) – optional architecture of query
- Returns:
list of variables reference sources
- Return type:
- get_indirect_branches_at(addr: int, arch: Architecture | None = None) List[IndirectBranchInfo] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_instr_highlight(addr: int, arch: Architecture | None = None) HighlightColor [source]
- Example:
>>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0)) >>> current_function.get_instr_highlight(here) <color: #ff00ff>
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_instruction_containing_address(addr: int, arch: Architecture | None = None) int | None [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
int | None
- get_int_display_type(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) IntegerDisplayType [source]
Get the current text display type for an integer token in the disassembly or IL views
See also see
get_int_display_type_and_typeid
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
- Return type:
- get_int_display_type_and_typeid(instr_addr: int, value: int, operand: int, arch: ~binaryninja.architecture.Architecture | None = None) -> (<enum 'IntegerDisplayType'>, <class 'str'>)[source]
Get the current text display type for an integer token in the disassembly or IL views
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
- Return type:
(<enum ‘IntegerDisplayType’>, <class ‘str’>)
- get_int_enum_display_typeid(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) str [source]
Get the current text display enum type for an integer token in the disassembly or IL views.
See also see
get_int_display_type_and_typeid
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
- Returns:
TypeID for the integer token
- Return type:
- get_lifted_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
LowLevelILInstruction | None
- get_lifted_il_flag_definitions_for_use(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[InstructionIndex] [source]
- get_lifted_il_flag_uses_for_definition(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[LowLevelILInstruction] [source]
- Parameters:
i (InstructionIndex) –
flag (FlagName | ILFlag | FlagIndex) –
- Return type:
- get_lifted_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction] [source]
get_lifted_ils_at
gets the Lifted IL Instruction(s) corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the function to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_lifted_ils_at(func.start) [<il: push(rbp)>]
- get_llil_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None [source]
get_llil_at
gets the LowLevelILInstruction corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the instruction to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_llil_at(func.start) <il: push(rbp)>
- get_llils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction] [source]
get_llils_at
gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.- Parameters:
addr (int) – virtual address of the instruction to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_llils_at(func.start) [<il: push(rbp)>]
- get_low_level_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None [source]
get_low_level_il_at
gets the LowLevelILInstruction corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the function to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_low_level_il_at(func.start) <il: push(rbp)>
- get_low_level_il_exits_at(addr: int, arch: Architecture | None = None) List[int] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_low_level_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction] [source]
get_low_level_ils_at
gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.- Parameters:
addr (int) – virtual address of the instruction to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_low_level_ils_at(func.start) [<il: push(rbp)>]
- get_mlil_var_refs(var: Variable) List[ILReferenceSource] [source]
get_mlil_var_refs
returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag. This function is related to get_hlil_var_refs(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.- Parameters:
var (Variable) – Variable for which to query the xref
- Returns:
List of IL References for the given variable
- Return type:
- Example:
>>> mlil_var = current_mlil[0].operands[0] >>> current_function.get_mlil_var_refs(mlil_var)
- get_mlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource] [source]
get_mlil_var_refs_from
returns a list of variables referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used. This function is related to get_hlil_var_refs_from(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.- Parameters:
addr (int) – virtual address to query for variable references
length (int) – optional length of query
arch (Architecture) – optional architecture of query
- Returns:
list of variable reference sources
- Return type:
- get_parameter_at(addr: int, func_type: Type | None, i: int, arch: Architecture | None = None) RegisterValue [source]
- Parameters:
addr (int) –
func_type (Type | None) –
i (int) –
arch (Architecture | None) –
- Return type:
- get_parameter_at_low_level_il_instruction(instr: InstructionIndex, func_type: Type, i: int) RegisterValue [source]
- Parameters:
- Return type:
- get_reg_value_after(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue [source]
get_reg_value_after
gets the value instruction address corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the instruction to query
reg (str) – string value of native register to query
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> current_function.get_reg_value_after(0x400dbe, 'rdi') <undetermined>
- get_reg_value_at(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue [source]
get_reg_value_at
gets the value the provided string register address corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the instruction to query
reg (str) – string value of native register to query
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> current_function.get_reg_value_at(0x400dbe, 'rdi') <const 0x2>
- get_reg_value_at_exit(reg: RegisterName | ILRegister | RegisterIndex) RegisterValue [source]
- Parameters:
reg (RegisterName | ILRegister | RegisterIndex) –
- Return type:
- get_regs_read_by(addr: int, arch: Architecture | None = None) List[RegisterName] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
List[RegisterName]
- get_regs_written_by(addr: int, arch: Architecture | None = None) List[RegisterName] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
List[RegisterName]
- get_stack_contents_after(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue [source]
- Parameters:
addr (int) –
offset (int) –
size (int) –
arch (Architecture | None) –
- Return type:
- get_stack_contents_at(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue [source]
get_stack_contents_at
returns the RegisterValue for the item on the stack in the current function at the given virtual addressaddr
, stack offsetoffset
and size ofsize
. Optionally specifying the architecture.- Parameters:
addr (int) – virtual address of the instruction to query
offset (int) – stack offset base of stack
size (int) – size of memory to query
arch (Architecture) – (optional) Architecture for the given function
- Return type:
Note
Stack base is zero on entry into the function unless the architecture places the return address on the stack as in (x86/x86_64) where the stack base will start at address_size
- Example:
>>> current_function.get_stack_contents_at(0x400fad, -16, 4) <range: 0x8 to 0xffffffff>
- Parameters:
addr (int) –
offset (int) –
size (int) –
arch (Architecture | None) –
- Return type:
- get_stack_var_at_frame_offset(offset: int, addr: int, arch: Architecture | None = None) Variable | None [source]
- Parameters:
offset (int) –
addr (int) –
arch (Architecture | None) –
- Return type:
Variable | None
- get_stack_var_at_frame_offset_after_instruction(offset: int, addr: int, arch: Architecture | None = None) Variable | None [source]
- Parameters:
offset (int) –
addr (int) –
arch (Architecture | None) –
- Return type:
Variable | None
- get_stack_vars_referenced_by(addr: int, arch: Architecture | None = None) List[StackVariableReference] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_stack_vars_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[StackVariableReference] [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_switch_recovery(addr: int | HighLevelILInstruction) SwitchRecovery [source]
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- get_tags_at(addr: int, arch: Architecture | None = None, auto: bool | None = None) List[Tag] [source]
get_tags
gets a list of Tags (but not function tags).- Parameters:
addr (int) – Address to get tags from.
auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags
arch (Architecture | None) –
- Return type:
list((Architecture, int, Tag))
- get_tags_in_range(address_range: AddressRange, arch: Architecture | None = None, auto: bool | None = None) List[Tuple[Architecture, int, Tag]] [source]
get_address_tags_in_range
gets a list of all Tags in the function at a given address. Range is inclusive at the start, exclusive at the end.- Parameters:
address_range (AddressRange) – Address range from which to get tags
arch (Architecture) – Architecture for the block in which the Tag is located (optional)
auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags
- Returns:
A list of (arch, address, Tag) tuples
- Return type:
list((Architecture, int, Tag))
- get_type_tokens(settings: DisassemblySettings | None = None) List[DisassemblyTextLine] [source]
- Parameters:
settings (DisassemblySettings | None) –
- Return type:
- get_variable_by_name(name: str) Variable | None [source]
Get a specific variable or None if it doesn’t exist
- has_guided_source_blocks() bool [source]
has_guided_source_blocks
checks if this function has any guided source blocks configured. This indicates whether guided analysis is active for this function.- Return type:
- Returns:
True if the function has guided source blocks, False otherwise
- is_call_instruction(addr: int, arch: Architecture | None = None) bool [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- is_condition_inverted(addr: int | HighLevelILInstruction) bool [source]
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- is_guided_source_block(arch: Architecture, addr: int) bool [source]
is_guided_source_block
checks if the given address is a guided source block.- Parameters:
arch (Architecture) – Architecture of the address to check
addr (int) – Address to check
- Return type:
- is_instruction_collapsed(instr: HighLevelILInstruction, discriminator: int = 0) bool [source]
Determine if a given HLIL instruction (with discriminator) is collapsed during rendering. :param instr: Instruction which might be collapsed :param discriminator: Unique discriminator id for the region :return: True if the instruction should be rendered as collapsed
- Parameters:
instr (HighLevelILInstruction) –
discriminator (int) –
- Return type:
- is_region_collapsed(hash) bool [source]
Determine if a given region is collapsed during rendering. :param hash: Hash value of region :return: True if the region should be rendered as collapsed
- Return type:
- language_representation(language: str) LanguageRepresentationFunction | None [source]
- Parameters:
language (str) –
- Return type:
- language_representation_if_available(language: str) LanguageRepresentationFunction | None [source]
- Parameters:
language (str) –
- Return type:
- mark_caller_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None [source]
mark_caller_updates_required
indicates that callers of this function need to be reanalyzed during the next update cycle- Parameters:
update_type (FunctionUpdateType) – (optional) Desired update type
- Return type:
None
- mark_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None [source]
mark_updates_required
indicates that this function needs to be reanalyzed during the next update cycle- Parameters:
update_type (FunctionUpdateType) – (optional) Desired update type
- Return type:
None
- merge_vars(target: Variable, sources: List[Variable] | Variable) None [source]
merge_vars
merges one or more variables insources
into thetarget
variable. All variable accesses to the variables insources
will be rewritten to usetarget
.
- query_metadata(key: str) metadata.MetadataValueType [source]
query_metadata retrieves metadata associated with the given key stored in the current function.
- Parameters:
key (str) – key to query
- Return type:
metadata associated with the key
- reanalyze(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None [source]
reanalyze
causes this function to be reanalyzed. This function does not wait for the analysis to finish.- Parameters:
update_type (FunctionUpdateType) – (optional) Desired update type
- Return type:
None
Warning
If analysis_skipped is True, using this API will not trigger re-analysis. Instead, set analysis_skipped to False.
- Return type:
None
- Parameters:
update_type (FunctionUpdateType) –
- remove_auto_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None [source]
remove_auto_address_tag
removes a Tag object at a given address.- Parameters:
addr (int) – Address at which to add the tag
tag (Tag) – Tag object to be added
arch (Architecture) – Architecture for the block in which the Tag is added (optional)
- Return type:
None
- remove_auto_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]
remove_auto_address_tags_of_type
removes all tags at the given address of the given type.- Parameters:
addr (int) – Address at which to remove the tags
tag_type (Tag) – TagType object to match for removing
arch (Architecture) – Architecture for the block in which the Tags is located (optional)
- Return type:
None
- remove_auto_function_tag(tag: Tag) None [source]
remove_user_function_tag
removes a Tag object as a function tag.- Parameters:
tag (Tag) – Tag object to be added
- Return type:
None
- remove_auto_function_tags_of_type(tag_type: str)[source]
remove_user_function_tags_of_type
removes all function Tag objects on a function of a given type- Parameters:
tag_type (TagType) – TagType object to match for removing
- Return type:
None
- remove_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None [source]
remove_guided_source_blocks
removes blocks from the guided source block list for this function. The specified blocks will no longer have their direct outgoing branch targets analyzed. This automatically enables theanalysis.guided.enable
setting if it is not already enabled.- Parameters:
addresses (List[Tuple[Architecture, int]]) – List of (architecture, address) tuples to remove
addresses –
- Return type:
None
- remove_metadata(key: str) None [source]
remove_metadata removes the metadata associated with key from the current function.
- Parameters:
key (str) – key associated with metadata to remove from the function
- Return type:
None
- remove_user_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None [source]
remove_user_address_tag
removes a Tag object at a given address. Since this removes a user tag, it will be added to the current undo buffer.- Parameters:
addr (int) – Address at which to remove the tag
tag (Tag) – Tag object to be added
arch (Architecture) – Architecture for the block in which the Tag is added (optional)
- Return type:
None
- remove_user_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]
remove_user_address_tags_of_type
removes all tags at the given address of the given type. Since this removes user tags, it will be added to the current undo buffer.- Parameters:
addr (int) – Address at which to remove the tag
tag_type (Tag) – TagType object to match for removing
arch (Architecture) – Architecture for the block in which the Tags is located (optional)
- Return type:
None
- remove_user_code_ref(from_addr: int, to_addr: int, from_arch: Architecture | None = None) None [source]
remove_user_code_ref
removes a user-defined cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.- Parameters:
from_addr (int) – virtual address of the source instruction
to_addr (int) – virtual address of the xref’s destination.
from_arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.remove_user_code_ref(here, 0x400000)
- remove_user_function_tag(tag: Tag) None [source]
remove_user_function_tag
removes a Tag object as a function tag. Since this removes a user tag, it will be added to the current undo buffer.- Parameters:
tag (Tag) – Tag object to be added
- Return type:
None
- remove_user_function_tags_of_type(tag_type: str)[source]
remove_user_function_tags_of_type
removes all function Tag objects on a function of a given type Since this removes user tags, it will be added to the current undo buffer.- Parameters:
tag_type (TagType) – TagType object to match for removing
- Return type:
None
- remove_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None [source]
remove_user_type_field_ref
removes a user-defined type field cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
offset (int) – offset of the field, relative to the type
from_arch (Architecture) – (optional) architecture of the source instruction
size (int) – (optional) the size of the access
- Return type:
None
- Example:
>>> current_function.remove_user_type_field_ref(here, 'A', 0x8)
- remove_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None [source]
remove_user_type_ref
removes a user-defined type cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
from_arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.remove_user_type_ref(here, 'A')
- request_debug_report(name: str) None [source]
request_debug_report
can generate internal debug reports for a variety of analysis. Current list of possible values include:mlil_translator
stack_adjust_graph
high_level_il
- Parameters:
name (str) – Name of the debug report
- Return type:
None
- set_auto_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int], arch: Architecture | None = None) None [source]
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
None
- set_auto_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust, arch: Architecture | None = None) None [source]
- Parameters:
addr (int) –
reg_stack (RegisterStackName | ILRegisterStack | RegisterStackIndex) –
arch (Architecture | None) –
- Return type:
None
- set_auto_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None) None [source]
- Parameters:
addr (int) –
adjust (int | OffsetWithConfidence) –
arch (Architecture | None) –
- Return type:
None
- set_auto_calling_convention(value: CallingConvention) None [source]
- Parameters:
value (CallingConvention) –
- Return type:
None
- set_auto_can_return(value: bool | BoolWithConfidence) None [source]
- Parameters:
value (bool | BoolWithConfidence) –
- Return type:
None
- set_auto_clobbered_regs(value: List[RegisterName | ILRegister | RegisterIndex]) None [source]
- Parameters:
value (List[RegisterName | ILRegister | RegisterIndex]) –
- Return type:
None
- set_auto_has_variable_arguments(value: bool | BoolWithConfidence) None [source]
- Parameters:
value (bool | BoolWithConfidence) –
- Return type:
None
- set_auto_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None [source]
- Parameters:
source (int) –
branches (List[Tuple[Architecture, int]]) –
source_arch (Architecture | None) –
- Return type:
None
- set_auto_inline_during_analysis(value: bool | BoolWithConfidence)[source]
- Parameters:
value (bool | BoolWithConfidence) –
- set_auto_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]
set_auto_instr_highlight
highlights the instruction at the specified address with the supplied colorWarning
Use only in analysis plugins. Do not use in regular plugins, as colors won’t be saved to the database.
- Parameters:
addr (int) – virtual address of the instruction to be highlighted
color (HighlightStandardColor|HighlightColor) – Color value to use for highlighting
arch (Architecture) – (optional) Architecture of the instruction if different from self.arch
- set_auto_parameter_vars(value: List[Variable] | Variable | ParameterVariables | None) None [source]
- Parameters:
value (List[Variable] | Variable | ParameterVariables | None) –
- Return type:
None
- set_auto_pure(value: bool | BoolWithConfidence) None [source]
- Parameters:
value (bool | BoolWithConfidence) –
- Return type:
None
- set_auto_reg_stack_adjustments(value: Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence])[source]
- Parameters:
value (Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence]) –
- set_auto_return_regs(value: RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) None [source]
- Parameters:
value (RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) –
- Return type:
None
- set_auto_return_type(value: str | Type | TypeBuilder) None [source]
- Parameters:
value (str | Type | TypeBuilder) –
- Return type:
None
- set_auto_stack_adjustment(value: int | OffsetWithConfidence) None [source]
- Parameters:
value (int | OffsetWithConfidence) –
- Return type:
None
- set_auto_type(value: str | Type | TypeBuilder) None [source]
- Parameters:
value (str | Type | TypeBuilder) –
- Return type:
None
- set_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int | RegisterStackAdjustmentWithConfidence], arch: Architecture | None = None) None [source]
- Parameters:
addr (int) –
adjust (Mapping[RegisterStackName, int | RegisterStackAdjustmentWithConfidence]) –
arch (Architecture | None) –
- Return type:
None
- set_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust: int | RegisterStackAdjustmentWithConfidence, arch: Architecture | None = None) None [source]
- Parameters:
addr (int) –
reg_stack (RegisterStackName | ILRegisterStack | RegisterStackIndex) –
adjust (int | RegisterStackAdjustmentWithConfidence) –
arch (Architecture | None) –
- Return type:
None
- set_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None)[source]
- Parameters:
addr (int) –
adjust (int | OffsetWithConfidence) –
arch (Architecture | None) –
- set_call_type_adjustment(addr: int, adjust_type: str | Type | TypeBuilder | None = None, arch: Architecture | None = None) None [source]
set_call_type_adjustment
sets or removes the call type override at a call site to the given type.- Parameters:
addr (int) – virtual address of the call instruction to adjust
adjust_type (str|Type|TypeBuilder) – (optional) overridden call type, or None to remove an existing adjustment
arch (Architecture) – (optional) Architecture of the instruction if different from self.arch
- Example:
>>> # Change the current call site to no-return >>> target = bv.get_function_at(list(filter(lambda ref: ref.address == here, current_function.call_sites))[0].mlil.dest.value.value) >>> ft = target.type.mutable_copy() >>> ft.can_return = False >>> current_function.set_call_type_adjustment(here, ft)
- Return type:
None
- set_comment_at(addr: int, comment: str) None [source]
set_comment_at
sets a comment for the current function at the address specified
- set_condition_inverted(addr: int | HighLevelILInstruction, invert: bool)[source]
- Parameters:
addr (int | HighLevelILInstruction) –
invert (bool) –
- static set_default_session_data(name: str, value) None [source]
- Parameters:
name (str) –
- Return type:
None
- set_early_return(addr: int | HighLevelILInstruction, value: EarlyReturn)[source]
- Parameters:
addr (int | HighLevelILInstruction) –
value (EarlyReturn) –
- set_expr_folding(addr: int | HighLevelILInstruction, value: ExprFolding)[source]
- Parameters:
addr (int | HighLevelILInstruction) –
value (ExprFolding) –
- set_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None [source]
set_guided_source_blocks
sets the complete list of guided source blocks for this function. Only blocks in this set will have their direct outgoing branch targets analyzed. This replaces any existing guided source blocks and automatically enables or disables theanalysis.guided.enable
setting based on whether addresses are provided.- Parameters:
addresses (List[Tuple[Architecture, int]]) – List of (architecture, address) tuples
addresses –
- Return type:
None
- set_int_display_type(instr_addr: int, value: int, operand: int, display_type: IntegerDisplayType, arch: Architecture | None = None, enum_display_typeid=None) None [source]
Change the text display type for an integer token in the disassembly or IL views
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
display_type (IntegerDisplayType) – Desired display type
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
enum_display_typeid (str) – (optional) Whenever passing EnumDisplayType to
display_type
, passing a type ID here will specify the Enumeration display type. Must be a valid type ID and resolve to an enumeration type.
- Return type:
None
- set_switch_recovery(addr: int | HighLevelILInstruction, value: SwitchRecovery)[source]
- Parameters:
addr (int | HighLevelILInstruction) –
value (SwitchRecovery) –
- set_user_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None [source]
- Parameters:
source (int) –
branches (List[Tuple[Architecture, int]]) –
source_arch (Architecture | None) –
- Return type:
None
- set_user_inline_during_analysis(value: bool | BoolWithConfidence)[source]
- Parameters:
value (bool | BoolWithConfidence) –
- set_user_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]
set_user_instr_highlight
highlights the instruction at the specified address with the supplied color- Parameters:
addr (int) – virtual address of the instruction to be highlighted
color (HighlightStandardColor|HighlightColor) – Color value to use for highlighting
arch (Architecture) – (optional) Architecture of the instruction if different from self.arch
- Example:
>>> current_function.set_user_instr_highlight(here, HighlightStandardColor.BlueHighlightColor) >>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0))
Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.
- set_user_type(value: str | Type | TypeBuilder) None [source]
- Parameters:
value (str | Type | TypeBuilder) –
- Return type:
None
- set_user_var_value(var: Variable, def_addr: int, value: PossibleValueSet, after: bool = True) None [source]
set_user_var_value allows the user to specify a PossibleValueSet value for an MLIL variable at its definition site.
Warning
Setting the variable value, triggers a reanalysis of the function and allows the dataflow to compute and propagate values which depend on the current variable. This implies that branch conditions whose values can be determined statically will be computed, leading to potential branch elimination at the HLIL layer.
- Parameters:
var (Variable) – Variable for which the value is to be set
def_addr (int) – Address where the variable is set
value (PossibleValueSet) – Informed value of the variable
after (bool) – Whether the value happens before or after the instruction
- Return type:
None
- Example:
>>> mlil_var = current_mlil[0].operands[0] >>> def_address = 0x40108d >>> var_value = PossibleValueSet.constant(5) >>> current_function.set_user_var_value(mlil_var, def_address, var_value)
- split_var(var: Variable) None [source]
split_var
splits a variable at the definition site. The givenvar
must be the variable unique to the definition and should be obtained by usingMediumLevelILInstruction.get_split_var_for_definition
at the definition site.This function is not meant to split variables that have been previously merged. Use
unmerge_vars
to split previously merged variables.Warning
Binary Ninja automatically splits all variables that the analysis determines to be safely splittable. Splitting a variable manually with
split_var
can cause IL and decompilation to be incorrect. There are some patterns where variables can be safely split semantically but analysis cannot determine that it is safe. This function is provided to allow variable splitting to be performed in these cases by plugins or by the user.- Parameters:
var (Variable) – variable to split
- Return type:
None
- store_metadata(key: str, md: Metadata | int | bool | str | bytes | float | List[MetadataValueType] | Tuple[MetadataValueType] | dict, isAuto: bool = False) None [source]
store_metadata stores an object for the given key in the current Function. Objects stored using store_metadata can be retrieved when the database is reopened unless isAuto is set to True.
- toggle_region(hash)[source]
Toggle the collapsed state of a region during rendering, by hash value :param hash: Hash value of region
- unmerge_vars(target: Variable, sources: List[Variable] | Variable) None [source]
unmerge_vars
undoes variable merging performed withmerge_vars
. The variables insources
will no longer be merged into thetarget
variable.
- unsplit_var(var: Variable) None [source]
unsplit_var
undoes variable splitting performed withsplit_var
. The givenvar
must be the variable unique to the definition and should be obtained by usingMediumLevelILInstruction.get_split_var_for_definition
at the definition site.- Parameters:
var (Variable) – variable to unsplit
- Return type:
None
- property address_ranges: List[AddressRange]
All of the address ranges covered by a function
- property analysis_skip_override: FunctionAnalysisSkipOverride
Override for skipping of automatic analysis
- property analysis_skip_reason: AnalysisSkipReason
Function analysis skip reason
- property analysis_skipped: bool
Whether automatic analysis was skipped for this function. Can be set to false to re-enable analysis.
- property arch: Architecture
Function architecture (read-only)
- property auto: bool
Whether function was automatically discovered (read-only) as a result of some creation of a ‘user’ function. ‘user’ functions may or may not have been created by a user through the or API. For instance the entry point into a function is always created a ‘user’ function. ‘user’ functions should be considered the root of auto analysis.
- property auto_metadata: Dict[str, metadata.MetadataValueType]
metadata retrieves the metadata associated with the current function.
- Return type:
metadata associated with the function
- property basic_blocks: BasicBlockList
function.BasicBlockList of BasicBlocks in the current function (read-only)
- property call_sites: List[ReferenceSource]
call_sites
returns a list of possible call sites contained in this function. This includes ordinary calls, tail calls, and indirect jumps. Not all of the returned call sites are necessarily true call sites; some may simply be unresolved indirect jumps, for example.- Returns:
List of References that represent the sources of possible calls in this function
- Return type:
- property callee_addresses: List[int]
callee_addressses
returns a list of start addresses for functions that this function calls. Does not point to the actual address where the call occurs, just the start of the function that contains the reference.
- property callees: List[Function]
callees
returns a list of functions that this function calls This does not include the address of those calls, rather just the function objects themselves. Usecall_sites
to identify the location of these calls.
- property caller_sites: Generator[ReferenceSource, None, None]
caller_sites
returns a list of ReferenceSource objects corresponding to the addresses in functions which reference this function- Returns:
List of ReferenceSource objects of the call sites to this function
- Return type:
- property callers: List[Function]
callers
returns a list of functions that call this function Does not point to the actual address where the call occurs, just the start of the function that contains the call.
- property calling_convention: CallingConvention | None
Calling convention used by the function
- property can_return: BoolWithConfidence
Whether function can return
- property clobbered_regs: RegisterSet
Registers that are modified by this function
- property comment: str
Gets the comment for the current function
- property components
- property core_var_stack_layout: List[CoreVariable]
List of function stack variables (read-only)
- property core_vars: List[CoreVariable]
List of CoreVariable objects
- property global_pointer_value: RegisterValue
Discovered value of the global pointer register, if the function uses one (read-only)
- property has_explicitly_defined_type: bool
Whether function has explicitly defined types (read-only)
- property has_unresolved_indirect_branches: bool
Has unresolved indirect branches (read-only)
- property has_user_annotations: bool
Whether the function has ever been ‘user’ modified
- property has_user_type: bool
True if the function has a user-defined type
- property has_variable_arguments: BoolWithConfidence
Whether the function takes a variable number of arguments
- property high_level_il: HighLevelILFunction | None
returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property highest_address: int
The highest (largest) virtual address contained in a function.
- property hlil: HighLevelILFunction | None
returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property hlil_if_available: HighLevelILFunction | None
returns HighLevelILFunction used to represent high level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if high level IL is available without generating it.
- property indirect_branches: List[IndirectBranchInfo]
List of indirect branches (read-only)
- property inline_during_analysis: BoolWithConfidence
Whether the function’s IL should be inlined into all callers’ IL
- property instructions: Generator[Tuple[List[InstructionTextToken], int], None, None]
A generator of instruction tokens and their start addresses for the current function
- property is_collapsed
If the entire function is collapsed during rendering.
- property is_pure: BoolWithConfidence
Whether function is pure
- property is_thunk: bool
Returns True if the function starts with a Tailcall (read-only)
- property lifted_il: LowLevelILFunction | None
returns LowLevelILFunction used to represent lifted IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes lifted IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property lifted_il_if_available: LowLevelILFunction | None
returns LowLevelILFunction used to represent lifted IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if lifted IL is available without generating it.
- property llil: LowLevelILFunction | None
returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property llil_basic_blocks: Generator[LowLevelILBasicBlock, None, None]
A generator of all LowLevelILBasicBlock objects in the current function
- property llil_if_available: LowLevelILFunction | None
returns LowLevelILFunction used to represent low level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if low level IL is available without generating it.
- property low_level_il: LowLevelILFunction | None
returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property lowest_address: int
The lowest (smallest) virtual address contained in a function.
- property mapped_medium_level_il: MediumLevelILFunction | None
returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property medium_level_il: MediumLevelILFunction | None
returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property merged_vars: Dict[Variable, List[Variable]]
Map of merged variables, organized by target variable (read-only). Use
merge_vars
andunmerge_vars
to update merged variables.
- property metadata: Dict[str, metadata.MetadataValueType]
metadata retrieves the metadata associated with the current function.
- Return type:
metadata associated with the function
- property mlil: MediumLevelILFunction | None
returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property mlil_basic_blocks: Generator[MediumLevelILBasicBlock, None, None]
A generator of all MediumLevelILBasicBlock objects in the current function
- property mlil_if_available: MediumLevelILFunction | None
returns MediumLevelILFunction used to represent medium level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if medium level IL is available without generating it.
- property mmlil: MediumLevelILFunction | None
returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property mmlil_if_available: MediumLevelILFunction | None
returns MediumLevelILFunction used to represent mapped medium level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if mapped medium level IL is available without generating it.
- property name: str
Symbol name for the function
- property needs_update: bool
Whether the function has analysis that needs to be updated (read-only)
- property parameter_vars: ParameterVariables
List of variables for the incoming function parameters
- property provenance
provenance
returns a string representing the provenance. This portion of the API is under development. Currently the provenance information is undocumented, not persistent, and not saved to a database.- Returns:
string representation of the provenance
- Return type:
- property pseudo_c: LanguageRepresentationFunction | None
- property pseudo_c_if_available: LanguageRepresentationFunction | None
- property reg_stack_adjustments: Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]
Number of entries removed from each register stack after return
- property return_regs: RegisterSet
Registers that are used for the return value
- property session_data: Any
Dictionary object where plugins can store arbitrary data associated with the function
- property split_vars: List[Variable]
Set of variables that have been split with
split_var
. These variables correspond to those unique to each definition site and are obtained by usingMediumLevelILInstruction.get_split_var_for_definition
at the definitions.
- property stack_adjustment: OffsetWithConfidence
Number of bytes removed from the stack after return
- property start: int
Function start address (read-only)
- property symbol: CoreSymbol
Function symbol(read-only)
- property tags: TagList
tags
gets a TagList of all Tags in the function (but not “function tags”). Tags are returned as an iterable indexable object TagList of (arch, address, Tag) tuples.- Return type:
TagList((Architecture, int, Tag))
- property too_large: bool
Whether the function is too large to automatically perform analysis (read-only)
- property total_bytes: int
Total bytes of a function calculated by summing each basic_block. Because basic blocks can overlap and have gaps between them this may or may not be equivalent to a .size property.
- property type: FunctionType
Function type object, can be set with either a string representing the function prototype (str(function) shows examples) or a
Type
object
- property type_tokens: List[InstructionTextToken]
Text tokens for this function’s prototype
- property unresolved_indirect_branches: List[Tuple[Architecture, int]]
List of unresolved indirect branches (read-only)
- property unresolved_stack_adjustment_graph: CoreFlowGraph | None
Flow graph of unresolved stack adjustments (read-only)
- property uses_incoming_global_pointer: bool
Whether the function uses the incoming global pointer value
- property view: BinaryView
Function view (read-only)
- property workflow
- class FunctionViewType[source]
Bases:
object
FunctionViewType(view_type: Union[ForwardRef(‘FunctionViewType’), binaryninja.enums.FunctionGraphType, str])
- __init__(view_type: FunctionViewType | FunctionGraphType | str)[source]
- Parameters:
view_type (FunctionViewType | FunctionGraphType | str) –
- view_type: FunctionGraphType
- class HighLevelILBasicBlockList[source]
Bases:
BasicBlockList
- class ILReferenceSource[source]
Bases:
object
ILReferenceSource(func: Optional[ForwardRef(‘Function’)], arch: Optional[ForwardRef(‘architecture.Architecture’)], address: int, il_type: binaryninja.enums.FunctionGraphType, expr_id: int)
- __init__(func: Function | None, arch: Architecture | None, address: int, il_type: FunctionGraphType, expr_id: int) None
- Parameters:
func (Function | None) –
arch (Architecture | None) –
address (int) –
il_type (FunctionGraphType) –
expr_id (int) –
- Return type:
None
- static get_il_name(il_type: FunctionGraphType) str [source]
- Parameters:
il_type (FunctionGraphType) –
- Return type:
- address: int
- arch: Architecture | None
- expr_id: int
- il_type: FunctionGraphType
- class LowLevelILBasicBlockList[source]
Bases:
BasicBlockList
- class MediumLevelILBasicBlockList[source]
Bases:
BasicBlockList
- class VariableReferenceSource[source]
Bases:
object
VariableReferenceSource(var: ‘variable.Variable’, src: binaryninja.function.ILReferenceSource)
- __init__(var: Variable, src: ILReferenceSource) None
- Parameters:
var (Variable) –
src (ILReferenceSource) –
- Return type:
None
- src: ILReferenceSource
- var: Variable
AdvancedFunctionAnalysisDataRequestor¶
ArchAndAddr¶
- class ArchAndAddr[source]¶
Bases:
object
ArchAndAddr(arch: ‘architecture.Architecture’, addr: int)
- __init__(arch: Architecture, addr: int) None ¶
- Parameters:
arch (Architecture) –
addr (int) –
- Return type:
None
- arch: Architecture¶
BasicBlockList¶
- class BasicBlockList[source]¶
Bases:
object
- __init__(function: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction)[source]¶
- Parameters:
function (Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction) –
DisassemblySettings¶
- class DisassemblySettings[source]¶
Bases:
object
- __init__(handle: LP_BNDisassemblySettings | None = None)[source]¶
- Parameters:
handle (LP_BNDisassemblySettings | None) –
- static default_graph_settings() DisassemblySettings [source]¶
- Return type:
- static default_linear_settings() DisassemblySettings [source]¶
- Return type:
- static default_settings() DisassemblySettings [source]¶
- Return type:
- is_option_set(option: DisassemblyOption) bool [source]¶
- Parameters:
option (DisassemblyOption) –
- Return type:
- set_option(option: DisassemblyOption, state: bool = True) None [source]¶
- Parameters:
option (DisassemblyOption) –
state (bool) –
- Return type:
None
DisassemblyTextLine¶
- class DisassemblyTextLine[source]¶
Bases:
object
DisassemblyTextLine(tokens: List[ForwardRef(‘InstructionTextToken’)], address: Optional[int] = None, il_instr: Union[ForwardRef(‘lowlevelil.LowLevelILInstruction’), ForwardRef(‘mediumlevelil.MediumLevelILInstruction’), ForwardRef(‘highlevelil.HighLevelILInstruction’), NoneType] = None, color: Union[ForwardRef(‘_highlight.HighlightColor’), binaryninja.enums.HighlightStandardColor, NoneType] = None, tags: Optional[List[ForwardRef(‘binaryview.Tag’)]] = None, type_info: Optional[binaryninja.function.DisassemblyTextLineTypeInfo] = None)
- __init__(tokens: List[InstructionTextToken], address: int | None = None, il_instr: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None = None, color: HighlightColor | HighlightStandardColor | None = None, tags: List[Tag] | None = None, type_info: DisassemblyTextLineTypeInfo | None = None)[source]¶
- Parameters:
tokens (List[InstructionTextToken]) –
address (int | None) –
il_instr (LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None) –
color (HighlightColor | HighlightStandardColor | None) –
type_info (DisassemblyTextLineTypeInfo | None) –
- property address_and_indentation_tokens¶
- property address_and_indentation_width¶
- highlight: HighlightColor¶
- il_instruction: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None¶
- tokens: List[InstructionTextToken]¶
- property total_width¶
- type_info: DisassemblyTextLineTypeInfo | None¶
DisassemblyTextLineTypeInfo¶
DisassemblyTextRenderer¶
- class DisassemblyTextRenderer[source]¶
Bases:
object
- __init__(func: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None = None, settings: DisassemblySettings | None = None, handle: BNDisassemblySettings | None = None)[source]¶
- Parameters:
func (Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None) –
settings (DisassemblySettings | None) –
handle (BNDisassemblySettings | None) –
- add_integer_token(tokens: List[InstructionTextToken], int_token: InstructionTextToken, addr: int, arch: Architecture | None = None) None [source]¶
- Parameters:
tokens (List[InstructionTextToken]) –
int_token (InstructionTextToken) –
addr (int) –
arch (Architecture | None) –
- Return type:
None
- add_stack_var_reference_tokens(tokens: List[InstructionTextToken], ref: StackVariableReference) None [source]¶
- Parameters:
tokens (List[InstructionTextToken]) –
ref (StackVariableReference) –
- Return type:
None
- add_symbol_token(tokens: List[InstructionTextToken], addr: int, size: int, operand: int | None = None) bool [source]¶
- get_disassembly_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None] [source]¶
- Parameters:
addr (int) –
- Return type:
Generator[Tuple[DisassemblyTextLine | None, int], None, None]
- get_instruction_annotations(addr: int) List[InstructionTextToken] [source]¶
- Parameters:
addr (int) –
- Return type:
- get_instruction_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None] [source]¶
- Parameters:
addr (int) –
- Return type:
Generator[Tuple[DisassemblyTextLine | None, int], None, None]
- static is_integer_token(token: InstructionTextToken) bool [source]¶
- Parameters:
token (InstructionTextToken) –
- Return type:
- post_process_lines(addr: int, length: int, in_lines: str | List[str] | List[DisassemblyTextLine], indent_spaces: str = '')[source]¶
- wrap_comment(lines: List[DisassemblyTextLine], cur_line: DisassemblyTextLine, comment: str, has_auto_annotations: bool, leading_spaces: str = ' ', indent_spaces: str = '') None [source]¶
- Parameters:
lines (List[DisassemblyTextLine]) –
cur_line (DisassemblyTextLine) –
comment (str) –
has_auto_annotations (bool) –
leading_spaces (str) –
indent_spaces (str) –
- Return type:
None
- property arch: Architecture¶
- property basic_block: BasicBlock | None¶
- property il_function: LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None¶
- property settings: DisassemblySettings¶
Function¶
- class Function[source]¶
Bases:
object
- __init__(view: BinaryView | None = None, handle: LP_BNFunction | None = None)[source]¶
- Parameters:
view (BinaryView | None) –
handle (LP_BNFunction | None) –
- add_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None [source]¶
add_guided_source_blocks
adds blocks to the guided source block list for this function. The specified blocks will have their direct outgoing branch targets analyzed. This automatically enables theanalysis.guided.enable
setting if it is not already enabled.- Parameters:
addresses (List[Tuple[Architecture, int]]) – List of (architecture, address) tuples to add
addresses –
- Return type:
None
- add_tag(tag_type: str, data: str, addr: int | None = None, auto: bool = False, arch: Architecture | None = None)[source]¶
add_tag
creates and adds aTag
object on either a function, or on an address inside of a function.“Function tags” appear at the top of a function and are a good way to label an entire function with some information. If you include an address when you call Function.add_tag, you’ll create an “address tag”. These are good for labeling specific instructions.
For tagging arbitrary data, consider
add_tag
.- Parameters:
tag_type (str) – The name of the tag type for this Tag
data (str) – additional data for the Tag
addr (int) – address at which to add the tag
auto (bool) – Whether or not an auto tag
arch (Architecture) – Architecture for the block in which the Tag is added (optional)
- Example:
>>> current_function.add_tag("Important", "I think this is the main function") >>> current_function.add_tag("Crashes", "Nullpointer dereference", here)
Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.
- add_user_code_ref(from_addr: int, to_addr: int, arch: Architecture | None = None) None [source]¶
add_user_code_ref
places a user-defined cross-reference from the instruction at the given address and architecture to the specified target address. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, useremove_user_code_ref
.- Parameters:
from_addr (int) – virtual address of the source instruction
to_addr (int) – virtual address of the xref’s destination.
arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.add_user_code_ref(here, 0x400000)
- add_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None [source]¶
add_user_type_field_ref
places a user-defined type field cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, useremove_user_type_field_ref
.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
offset (int) – offset of the field, relative to the type
from_arch (Architecture) – (optional) architecture of the source instruction
size (int) – (optional) the size of the access
- Return type:
None
- Example:
>>> current_function.add_user_type_field_ref(here, 'A', 0x8)
- add_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None [source]¶
add_user_type_ref
places a user-defined type cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, useremove_user_type_ref
.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
from_arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.add_user_code_ref(here, 'A')
- analyze() None [source]¶
analyze
causes this function to be analyzed if it’s out of date. This function does not wait for the analysis to finish.- Return type:
None
- apply_auto_discovered_type(func_type: str | Type | TypeBuilder) None [source]¶
- Parameters:
func_type (str | Type | TypeBuilder) –
- Return type:
None
- apply_imported_types(sym: CoreSymbol, type: str | Type | TypeBuilder | None = None) None [source]¶
- Parameters:
sym (CoreSymbol) –
type (str | Type | TypeBuilder | None) –
- Return type:
None
- check_for_debug_report(name: str) bool [source]¶
check_for_debug_report
checks if a function has had a debug report requested with the given name, and then, if one has been requested, clears the request internally so that future calls to this function for that report will return False.If a function has had a debug report requested, it is the caller of this function’s responsibility to actually generate and show the debug report. You can use
binaryninja.interaction.show_report_collection
for showing a debug report from a workflow activity.
- clear_all_user_var_values() None [source]¶
Clear all user defined variable values.
- Return type:
None
- clear_user_var_value(var: Variable, def_addr: int, after: bool = True) None [source]¶
Clears a previously defined user variable value.
- create_auto_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None [source]¶
- Parameters:
offset (int) –
var_type (str | Type | TypeBuilder) –
name (str) –
- Return type:
None
- create_auto_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None [source]¶
- create_graph(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph [source]¶
Create a flow graph with the disassembly of this function.
Note
This graph waits for function analysis, so Workflow Activities should instead use
create_graph_immediate
to create graphs with the function contents as-is.- Parameters:
graph_type (FunctionViewType | FunctionGraphType | str) – IL form of the disassembly in the graph
settings (DisassemblySettings | None) – Optional settings for the disassembly text renderer
- Returns:
Flow graph object
- Return type:
- create_graph_immediate(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph [source]¶
Create a flow graph with the disassembly of this function, specifically using the instructions as they are in the function when this is called. You probably want to use this if you are creating a Debug Report in a Workflow Activity.
- Parameters:
graph_type (FunctionViewType | FunctionGraphType | str) – IL form of the disassembly in the graph
settings (DisassemblySettings | None) – Optional settings for the disassembly text renderer
- Returns:
Flow graph object
- Return type:
- create_user_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None [source]¶
- Parameters:
offset (int) –
var_type (str | Type | TypeBuilder) –
name (str) –
- Return type:
None
- create_user_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None [source]¶
- expand_region(hash)[source]¶
Un-collapse a region during rendering :param hash: Hash value of region
- get_all_user_var_values() Dict[Variable, Dict[ArchAndAddr, PossibleValueSet]] [source]¶
Returns a map of current defined user variable values.
- Returns:
Map of user current defined user variable values and their definition sites.
- Type:
dict of (Variable, dict of (ArchAndAddr, PossibleValueSet))
- Return type:
- get_basic_block_at(addr: int, arch: Architecture | None = None) BasicBlock | None [source]¶
get_basic_block_at
returns the BasicBlock of the optionally specified Architecturearch
at the given addressaddr
.- Parameters:
addr (int) – Address of the BasicBlock to retrieve.
arch (Architecture) – (optional) Architecture of the basic block if different from the Function’s self.arch
- Example:
>>> current_function.get_basic_block_at(current_function.start) <block: x86_64@0x100000f30-0x100000f50>
- Return type:
BasicBlock | None
- get_block_annotations(addr: int, arch: Architecture | None = None) List[List[InstructionTextToken]] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_call_reg_stack_adjustment(addr: int, arch: Architecture | None = None) Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]
- get_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, arch: Architecture | None = None) RegisterStackAdjustmentWithConfidence [source]¶
- Parameters:
addr (int) –
reg_stack (RegisterStackName | ILRegisterStack | RegisterStackIndex) –
arch (Architecture | None) –
- Return type:
- get_call_stack_adjustment(addr: int, arch: Architecture | None = None) OffsetWithConfidence [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_call_type_adjustment(addr: int, arch: Architecture | None = None) Type | None [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
Type | None
- get_callee_for_analysis(platform: Platform, addr: int, exact: bool = False) Function | None [source]¶
get_callee_for_analysis
retrieves the callee function for the specified address and platform.Note
This method is intended for use by architecture plugins only.
- get_constant_data(state: RegisterValueType, value: int, size: int = 0) DataBuffer [source]¶
- Parameters:
state (RegisterValueType) –
value (int) –
size (int) –
- Return type:
- get_constant_data_and_builtin(state: RegisterValueType, value: int, size: int = 0) Tuple[DataBuffer, BuiltinType] [source]¶
- Parameters:
state (RegisterValueType) –
value (int) –
size (int) –
- Return type:
- get_constants_referenced_by(addr: int, arch: Architecture | None = None) List[ConstantReference] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_constants_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[ConstantReference] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_early_return(addr: int | HighLevelILInstruction) EarlyReturn [source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- get_expr_folding(addr: int | HighLevelILInstruction) ExprFolding [source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- get_flags_read_by_lifted_il_instruction(i: InstructionIndex) List[FlagName] [source]¶
- Parameters:
i (InstructionIndex) –
- Return type:
List[FlagName]
- get_flags_written_by_lifted_il_instruction(i: InstructionIndex) List[FlagName] [source]¶
- Parameters:
i (InstructionIndex) –
- Return type:
List[FlagName]
- get_function_tags(auto: bool | None = None, tag_type: str | None = None) List[Tag] [source]¶
get_function_tags
gets a list of function Tags for the function.
- get_guided_source_blocks() List[Tuple[Architecture, int]] [source]¶
get_guided_source_blocks
returns the current list of guided source blocks for this function. These blocks have their direct outgoing branch targets analyzed.- Return type:
List[Tuple[Architecture, int]]
- Returns:
List of (architecture, address) tuples representing current guided source blocks
- get_hlil_var_refs(var: Variable) List[ILReferenceSource] [source]¶
get_hlil_var_refs
returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag.- Parameters:
var (Variable) – Variable for which to query the xref
- Returns:
List of IL References for the given variable
- Return type:
- Example:
>>> mlil_var = current_hlil[0].operands[0] >>> current_function.get_hlil_var_refs(mlil_var)
- get_hlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource] [source]¶
get_hlil_var_refs_from
returns a list of variables referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used.- Parameters:
addr (int) – virtual address to query for variable references
length (int) – optional length of query
arch (Architecture) – optional architecture of query
- Returns:
list of variables reference sources
- Return type:
- get_indirect_branches_at(addr: int, arch: Architecture | None = None) List[IndirectBranchInfo] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_instr_highlight(addr: int, arch: Architecture | None = None) HighlightColor [source]¶
- Example:
>>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0)) >>> current_function.get_instr_highlight(here) <color: #ff00ff>
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_instruction_containing_address(addr: int, arch: Architecture | None = None) int | None [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
int | None
- get_int_display_type(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) IntegerDisplayType [source]¶
Get the current text display type for an integer token in the disassembly or IL views
See also see
get_int_display_type_and_typeid
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
- Return type:
- get_int_display_type_and_typeid(instr_addr: int, value: int, operand: int, arch: ~binaryninja.architecture.Architecture | None = None) -> (<enum 'IntegerDisplayType'>, <class 'str'>)[source]¶
Get the current text display type for an integer token in the disassembly or IL views
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
- Return type:
(<enum ‘IntegerDisplayType’>, <class ‘str’>)
- get_int_enum_display_typeid(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) str [source]¶
Get the current text display enum type for an integer token in the disassembly or IL views.
See also see
get_int_display_type_and_typeid
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
- Returns:
TypeID for the integer token
- Return type:
- get_lifted_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
LowLevelILInstruction | None
- get_lifted_il_flag_definitions_for_use(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[InstructionIndex] [source]¶
- get_lifted_il_flag_uses_for_definition(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[LowLevelILInstruction] [source]¶
- Parameters:
i (InstructionIndex) –
flag (FlagName | ILFlag | FlagIndex) –
- Return type:
- get_lifted_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction] [source]¶
get_lifted_ils_at
gets the Lifted IL Instruction(s) corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the function to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_lifted_ils_at(func.start) [<il: push(rbp)>]
- get_llil_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None [source]¶
get_llil_at
gets the LowLevelILInstruction corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the instruction to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_llil_at(func.start) <il: push(rbp)>
- get_llils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction] [source]¶
get_llils_at
gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.- Parameters:
addr (int) – virtual address of the instruction to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_llils_at(func.start) [<il: push(rbp)>]
- get_low_level_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None [source]¶
get_low_level_il_at
gets the LowLevelILInstruction corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the function to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_low_level_il_at(func.start) <il: push(rbp)>
- get_low_level_il_exits_at(addr: int, arch: Architecture | None = None) List[int] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_low_level_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction] [source]¶
get_low_level_ils_at
gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.- Parameters:
addr (int) – virtual address of the instruction to be queried
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> func = next(bv.functions) >>> func.get_low_level_ils_at(func.start) [<il: push(rbp)>]
- get_mlil_var_refs(var: Variable) List[ILReferenceSource] [source]¶
get_mlil_var_refs
returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag. This function is related to get_hlil_var_refs(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.- Parameters:
var (Variable) – Variable for which to query the xref
- Returns:
List of IL References for the given variable
- Return type:
- Example:
>>> mlil_var = current_mlil[0].operands[0] >>> current_function.get_mlil_var_refs(mlil_var)
- get_mlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource] [source]¶
get_mlil_var_refs_from
returns a list of variables referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used. This function is related to get_hlil_var_refs_from(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.- Parameters:
addr (int) – virtual address to query for variable references
length (int) – optional length of query
arch (Architecture) – optional architecture of query
- Returns:
list of variable reference sources
- Return type:
- get_parameter_at(addr: int, func_type: Type | None, i: int, arch: Architecture | None = None) RegisterValue [source]¶
- Parameters:
addr (int) –
func_type (Type | None) –
i (int) –
arch (Architecture | None) –
- Return type:
- get_parameter_at_low_level_il_instruction(instr: InstructionIndex, func_type: Type, i: int) RegisterValue [source]¶
- Parameters:
- Return type:
- get_reg_value_after(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue [source]¶
get_reg_value_after
gets the value instruction address corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the instruction to query
reg (str) – string value of native register to query
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> current_function.get_reg_value_after(0x400dbe, 'rdi') <undetermined>
- get_reg_value_at(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue [source]¶
get_reg_value_at
gets the value the provided string register address corresponding to the given virtual address- Parameters:
addr (int) – virtual address of the instruction to query
reg (str) – string value of native register to query
arch (Architecture) – (optional) Architecture for the given function
- Return type:
- Example:
>>> current_function.get_reg_value_at(0x400dbe, 'rdi') <const 0x2>
- get_reg_value_at_exit(reg: RegisterName | ILRegister | RegisterIndex) RegisterValue [source]¶
- Parameters:
reg (RegisterName | ILRegister | RegisterIndex) –
- Return type:
- get_regs_read_by(addr: int, arch: Architecture | None = None) List[RegisterName] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
List[RegisterName]
- get_regs_written_by(addr: int, arch: Architecture | None = None) List[RegisterName] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
List[RegisterName]
- get_stack_contents_after(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue [source]¶
- Parameters:
addr (int) –
offset (int) –
size (int) –
arch (Architecture | None) –
- Return type:
- get_stack_contents_at(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue [source]¶
get_stack_contents_at
returns the RegisterValue for the item on the stack in the current function at the given virtual addressaddr
, stack offsetoffset
and size ofsize
. Optionally specifying the architecture.- Parameters:
addr (int) – virtual address of the instruction to query
offset (int) – stack offset base of stack
size (int) – size of memory to query
arch (Architecture) – (optional) Architecture for the given function
- Return type:
Note
Stack base is zero on entry into the function unless the architecture places the return address on the stack as in (x86/x86_64) where the stack base will start at address_size
- Example:
>>> current_function.get_stack_contents_at(0x400fad, -16, 4) <range: 0x8 to 0xffffffff>
- Parameters:
addr (int) –
offset (int) –
size (int) –
arch (Architecture | None) –
- Return type:
- get_stack_var_at_frame_offset(offset: int, addr: int, arch: Architecture | None = None) Variable | None [source]¶
- Parameters:
offset (int) –
addr (int) –
arch (Architecture | None) –
- Return type:
Variable | None
- get_stack_var_at_frame_offset_after_instruction(offset: int, addr: int, arch: Architecture | None = None) Variable | None [source]¶
- Parameters:
offset (int) –
addr (int) –
arch (Architecture | None) –
- Return type:
Variable | None
- get_stack_vars_referenced_by(addr: int, arch: Architecture | None = None) List[StackVariableReference] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_stack_vars_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[StackVariableReference] [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- get_switch_recovery(addr: int | HighLevelILInstruction) SwitchRecovery [source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- get_tags_at(addr: int, arch: Architecture | None = None, auto: bool | None = None) List[Tag] [source]¶
get_tags
gets a list of Tags (but not function tags).- Parameters:
addr (int) – Address to get tags from.
auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags
arch (Architecture | None) –
- Return type:
list((Architecture, int, Tag))
- get_tags_in_range(address_range: AddressRange, arch: Architecture | None = None, auto: bool | None = None) List[Tuple[Architecture, int, Tag]] [source]¶
get_address_tags_in_range
gets a list of all Tags in the function at a given address. Range is inclusive at the start, exclusive at the end.- Parameters:
address_range (AddressRange) – Address range from which to get tags
arch (Architecture) – Architecture for the block in which the Tag is located (optional)
auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags
- Returns:
A list of (arch, address, Tag) tuples
- Return type:
list((Architecture, int, Tag))
- get_type_tokens(settings: DisassemblySettings | None = None) List[DisassemblyTextLine] [source]¶
- Parameters:
settings (DisassemblySettings | None) –
- Return type:
- get_variable_by_name(name: str) Variable | None [source]¶
Get a specific variable or None if it doesn’t exist
- has_guided_source_blocks() bool [source]¶
has_guided_source_blocks
checks if this function has any guided source blocks configured. This indicates whether guided analysis is active for this function.- Return type:
- Returns:
True if the function has guided source blocks, False otherwise
- is_call_instruction(addr: int, arch: Architecture | None = None) bool [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
- is_condition_inverted(addr: int | HighLevelILInstruction) bool [source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
- Return type:
- is_guided_source_block(arch: Architecture, addr: int) bool [source]¶
is_guided_source_block
checks if the given address is a guided source block.- Parameters:
arch (Architecture) – Architecture of the address to check
addr (int) – Address to check
- Return type:
- is_instruction_collapsed(instr: HighLevelILInstruction, discriminator: int = 0) bool [source]¶
Determine if a given HLIL instruction (with discriminator) is collapsed during rendering. :param instr: Instruction which might be collapsed :param discriminator: Unique discriminator id for the region :return: True if the instruction should be rendered as collapsed
- Parameters:
instr (HighLevelILInstruction) –
discriminator (int) –
- Return type:
- is_region_collapsed(hash) bool [source]¶
Determine if a given region is collapsed during rendering. :param hash: Hash value of region :return: True if the region should be rendered as collapsed
- Return type:
- language_representation(language: str) LanguageRepresentationFunction | None [source]¶
- Parameters:
language (str) –
- Return type:
- language_representation_if_available(language: str) LanguageRepresentationFunction | None [source]¶
- Parameters:
language (str) –
- Return type:
- mark_caller_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None [source]¶
mark_caller_updates_required
indicates that callers of this function need to be reanalyzed during the next update cycle- Parameters:
update_type (FunctionUpdateType) – (optional) Desired update type
- Return type:
None
- mark_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None [source]¶
mark_updates_required
indicates that this function needs to be reanalyzed during the next update cycle- Parameters:
update_type (FunctionUpdateType) – (optional) Desired update type
- Return type:
None
- merge_vars(target: Variable, sources: List[Variable] | Variable) None [source]¶
merge_vars
merges one or more variables insources
into thetarget
variable. All variable accesses to the variables insources
will be rewritten to usetarget
.
- query_metadata(key: str) metadata.MetadataValueType [source]¶
query_metadata retrieves metadata associated with the given key stored in the current function.
- Parameters:
key (str) – key to query
- Return type:
metadata associated with the key
- reanalyze(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None [source]¶
reanalyze
causes this function to be reanalyzed. This function does not wait for the analysis to finish.- Parameters:
update_type (FunctionUpdateType) – (optional) Desired update type
- Return type:
None
Warning
If analysis_skipped is True, using this API will not trigger re-analysis. Instead, set analysis_skipped to False.
- Return type:
None
- Parameters:
update_type (FunctionUpdateType) –
- remove_auto_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None [source]¶
remove_auto_address_tag
removes a Tag object at a given address.- Parameters:
addr (int) – Address at which to add the tag
tag (Tag) – Tag object to be added
arch (Architecture) – Architecture for the block in which the Tag is added (optional)
- Return type:
None
- remove_auto_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]¶
remove_auto_address_tags_of_type
removes all tags at the given address of the given type.- Parameters:
addr (int) – Address at which to remove the tags
tag_type (Tag) – TagType object to match for removing
arch (Architecture) – Architecture for the block in which the Tags is located (optional)
- Return type:
None
- remove_auto_function_tag(tag: Tag) None [source]¶
remove_user_function_tag
removes a Tag object as a function tag.- Parameters:
tag (Tag) – Tag object to be added
- Return type:
None
- remove_auto_function_tags_of_type(tag_type: str)[source]¶
remove_user_function_tags_of_type
removes all function Tag objects on a function of a given type- Parameters:
tag_type (TagType) – TagType object to match for removing
- Return type:
None
- remove_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None [source]¶
remove_guided_source_blocks
removes blocks from the guided source block list for this function. The specified blocks will no longer have their direct outgoing branch targets analyzed. This automatically enables theanalysis.guided.enable
setting if it is not already enabled.- Parameters:
addresses (List[Tuple[Architecture, int]]) – List of (architecture, address) tuples to remove
addresses –
- Return type:
None
- remove_metadata(key: str) None [source]¶
remove_metadata removes the metadata associated with key from the current function.
- Parameters:
key (str) – key associated with metadata to remove from the function
- Return type:
None
- remove_user_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None [source]¶
remove_user_address_tag
removes a Tag object at a given address. Since this removes a user tag, it will be added to the current undo buffer.- Parameters:
addr (int) – Address at which to remove the tag
tag (Tag) – Tag object to be added
arch (Architecture) – Architecture for the block in which the Tag is added (optional)
- Return type:
None
- remove_user_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]¶
remove_user_address_tags_of_type
removes all tags at the given address of the given type. Since this removes user tags, it will be added to the current undo buffer.- Parameters:
addr (int) – Address at which to remove the tag
tag_type (Tag) – TagType object to match for removing
arch (Architecture) – Architecture for the block in which the Tags is located (optional)
- Return type:
None
- remove_user_code_ref(from_addr: int, to_addr: int, from_arch: Architecture | None = None) None [source]¶
remove_user_code_ref
removes a user-defined cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.- Parameters:
from_addr (int) – virtual address of the source instruction
to_addr (int) – virtual address of the xref’s destination.
from_arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.remove_user_code_ref(here, 0x400000)
- remove_user_function_tag(tag: Tag) None [source]¶
remove_user_function_tag
removes a Tag object as a function tag. Since this removes a user tag, it will be added to the current undo buffer.- Parameters:
tag (Tag) – Tag object to be added
- Return type:
None
- remove_user_function_tags_of_type(tag_type: str)[source]¶
remove_user_function_tags_of_type
removes all function Tag objects on a function of a given type Since this removes user tags, it will be added to the current undo buffer.- Parameters:
tag_type (TagType) – TagType object to match for removing
- Return type:
None
- remove_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None [source]¶
remove_user_type_field_ref
removes a user-defined type field cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
offset (int) – offset of the field, relative to the type
from_arch (Architecture) – (optional) architecture of the source instruction
size (int) – (optional) the size of the access
- Return type:
None
- Example:
>>> current_function.remove_user_type_field_ref(here, 'A', 0x8)
- remove_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None [source]¶
remove_user_type_ref
removes a user-defined type cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.- Parameters:
from_addr (int) – virtual address of the source instruction
name (QualifiedName) – name of the referenced type
from_arch (Architecture) – (optional) architecture of the source instruction
- Return type:
None
- Example:
>>> current_function.remove_user_type_ref(here, 'A')
- request_debug_report(name: str) None [source]¶
request_debug_report
can generate internal debug reports for a variety of analysis. Current list of possible values include:mlil_translator
stack_adjust_graph
high_level_il
- Parameters:
name (str) – Name of the debug report
- Return type:
None
- set_auto_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int], arch: Architecture | None = None) None [source]¶
- Parameters:
addr (int) –
arch (Architecture | None) –
- Return type:
None
- set_auto_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust, arch: Architecture | None = None) None [source]¶
- Parameters:
addr (int) –
reg_stack (RegisterStackName | ILRegisterStack | RegisterStackIndex) –
arch (Architecture | None) –
- Return type:
None
- set_auto_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None) None [source]¶
- Parameters:
addr (int) –
adjust (int | OffsetWithConfidence) –
arch (Architecture | None) –
- Return type:
None
- set_auto_calling_convention(value: CallingConvention) None [source]¶
- Parameters:
value (CallingConvention) –
- Return type:
None
- set_auto_can_return(value: bool | BoolWithConfidence) None [source]¶
- Parameters:
value (bool | BoolWithConfidence) –
- Return type:
None
- set_auto_clobbered_regs(value: List[RegisterName | ILRegister | RegisterIndex]) None [source]¶
- Parameters:
value (List[RegisterName | ILRegister | RegisterIndex]) –
- Return type:
None
- set_auto_has_variable_arguments(value: bool | BoolWithConfidence) None [source]¶
- Parameters:
value (bool | BoolWithConfidence) –
- Return type:
None
- set_auto_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None [source]¶
- Parameters:
source (int) –
branches (List[Tuple[Architecture, int]]) –
source_arch (Architecture | None) –
- Return type:
None
- set_auto_inline_during_analysis(value: bool | BoolWithConfidence)[source]¶
- Parameters:
value (bool | BoolWithConfidence) –
- set_auto_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]¶
set_auto_instr_highlight
highlights the instruction at the specified address with the supplied colorWarning
Use only in analysis plugins. Do not use in regular plugins, as colors won’t be saved to the database.
- Parameters:
addr (int) – virtual address of the instruction to be highlighted
color (HighlightStandardColor|HighlightColor) – Color value to use for highlighting
arch (Architecture) – (optional) Architecture of the instruction if different from self.arch
- set_auto_parameter_vars(value: List[Variable] | Variable | ParameterVariables | None) None [source]¶
- Parameters:
value (List[Variable] | Variable | ParameterVariables | None) –
- Return type:
None
- set_auto_pure(value: bool | BoolWithConfidence) None [source]¶
- Parameters:
value (bool | BoolWithConfidence) –
- Return type:
None
- set_auto_reg_stack_adjustments(value: Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence])[source]¶
- Parameters:
value (Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence]) –
- set_auto_return_regs(value: RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) None [source]¶
- Parameters:
value (RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) –
- Return type:
None
- set_auto_return_type(value: str | Type | TypeBuilder) None [source]¶
- Parameters:
value (str | Type | TypeBuilder) –
- Return type:
None
- set_auto_stack_adjustment(value: int | OffsetWithConfidence) None [source]¶
- Parameters:
value (int | OffsetWithConfidence) –
- Return type:
None
- set_auto_type(value: str | Type | TypeBuilder) None [source]¶
- Parameters:
value (str | Type | TypeBuilder) –
- Return type:
None
- set_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int | RegisterStackAdjustmentWithConfidence], arch: Architecture | None = None) None [source]¶
- Parameters:
addr (int) –
adjust (Mapping[RegisterStackName, int | RegisterStackAdjustmentWithConfidence]) –
arch (Architecture | None) –
- Return type:
None
- set_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust: int | RegisterStackAdjustmentWithConfidence, arch: Architecture | None = None) None [source]¶
- Parameters:
addr (int) –
reg_stack (RegisterStackName | ILRegisterStack | RegisterStackIndex) –
adjust (int | RegisterStackAdjustmentWithConfidence) –
arch (Architecture | None) –
- Return type:
None
- set_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None)[source]¶
- Parameters:
addr (int) –
adjust (int | OffsetWithConfidence) –
arch (Architecture | None) –
- set_call_type_adjustment(addr: int, adjust_type: str | Type | TypeBuilder | None = None, arch: Architecture | None = None) None [source]¶
set_call_type_adjustment
sets or removes the call type override at a call site to the given type.- Parameters:
addr (int) – virtual address of the call instruction to adjust
adjust_type (str|Type|TypeBuilder) – (optional) overridden call type, or None to remove an existing adjustment
arch (Architecture) – (optional) Architecture of the instruction if different from self.arch
- Example:
>>> # Change the current call site to no-return >>> target = bv.get_function_at(list(filter(lambda ref: ref.address == here, current_function.call_sites))[0].mlil.dest.value.value) >>> ft = target.type.mutable_copy() >>> ft.can_return = False >>> current_function.set_call_type_adjustment(here, ft)
- Return type:
None
- set_comment_at(addr: int, comment: str) None [source]¶
set_comment_at
sets a comment for the current function at the address specified
- set_condition_inverted(addr: int | HighLevelILInstruction, invert: bool)[source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
invert (bool) –
- static set_default_session_data(name: str, value) None [source]¶
- Parameters:
name (str) –
- Return type:
None
- set_early_return(addr: int | HighLevelILInstruction, value: EarlyReturn)[source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
value (EarlyReturn) –
- set_expr_folding(addr: int | HighLevelILInstruction, value: ExprFolding)[source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
value (ExprFolding) –
- set_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None [source]¶
set_guided_source_blocks
sets the complete list of guided source blocks for this function. Only blocks in this set will have their direct outgoing branch targets analyzed. This replaces any existing guided source blocks and automatically enables or disables theanalysis.guided.enable
setting based on whether addresses are provided.- Parameters:
addresses (List[Tuple[Architecture, int]]) – List of (architecture, address) tuples
addresses –
- Return type:
None
- set_int_display_type(instr_addr: int, value: int, operand: int, display_type: IntegerDisplayType, arch: Architecture | None = None, enum_display_typeid=None) None [source]¶
Change the text display type for an integer token in the disassembly or IL views
- Parameters:
instr_addr (int) – Address of the instruction or IL line containing the token
value (int) –
value
field of the InstructionTextToken object for the token, usually the constant displayedoperand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token
display_type (IntegerDisplayType) – Desired display type
arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token
enum_display_typeid (str) – (optional) Whenever passing EnumDisplayType to
display_type
, passing a type ID here will specify the Enumeration display type. Must be a valid type ID and resolve to an enumeration type.
- Return type:
None
- set_switch_recovery(addr: int | HighLevelILInstruction, value: SwitchRecovery)[source]¶
- Parameters:
addr (int | HighLevelILInstruction) –
value (SwitchRecovery) –
- set_user_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None [source]¶
- Parameters:
source (int) –
branches (List[Tuple[Architecture, int]]) –
source_arch (Architecture | None) –
- Return type:
None
- set_user_inline_during_analysis(value: bool | BoolWithConfidence)[source]¶
- Parameters:
value (bool | BoolWithConfidence) –
- set_user_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]¶
set_user_instr_highlight
highlights the instruction at the specified address with the supplied color- Parameters:
addr (int) – virtual address of the instruction to be highlighted
color (HighlightStandardColor|HighlightColor) – Color value to use for highlighting
arch (Architecture) – (optional) Architecture of the instruction if different from self.arch
- Example:
>>> current_function.set_user_instr_highlight(here, HighlightStandardColor.BlueHighlightColor) >>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0))
Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.
- set_user_type(value: str | Type | TypeBuilder) None [source]¶
- Parameters:
value (str | Type | TypeBuilder) –
- Return type:
None
- set_user_var_value(var: Variable, def_addr: int, value: PossibleValueSet, after: bool = True) None [source]¶
set_user_var_value allows the user to specify a PossibleValueSet value for an MLIL variable at its definition site.
Warning
Setting the variable value, triggers a reanalysis of the function and allows the dataflow to compute and propagate values which depend on the current variable. This implies that branch conditions whose values can be determined statically will be computed, leading to potential branch elimination at the HLIL layer.
- Parameters:
var (Variable) – Variable for which the value is to be set
def_addr (int) – Address where the variable is set
value (PossibleValueSet) – Informed value of the variable
after (bool) – Whether the value happens before or after the instruction
- Return type:
None
- Example:
>>> mlil_var = current_mlil[0].operands[0] >>> def_address = 0x40108d >>> var_value = PossibleValueSet.constant(5) >>> current_function.set_user_var_value(mlil_var, def_address, var_value)
- split_var(var: Variable) None [source]¶
split_var
splits a variable at the definition site. The givenvar
must be the variable unique to the definition and should be obtained by usingMediumLevelILInstruction.get_split_var_for_definition
at the definition site.This function is not meant to split variables that have been previously merged. Use
unmerge_vars
to split previously merged variables.Warning
Binary Ninja automatically splits all variables that the analysis determines to be safely splittable. Splitting a variable manually with
split_var
can cause IL and decompilation to be incorrect. There are some patterns where variables can be safely split semantically but analysis cannot determine that it is safe. This function is provided to allow variable splitting to be performed in these cases by plugins or by the user.- Parameters:
var (Variable) – variable to split
- Return type:
None
- store_metadata(key: str, md: Metadata | int | bool | str | bytes | float | List[MetadataValueType] | Tuple[MetadataValueType] | dict, isAuto: bool = False) None [source]¶
store_metadata stores an object for the given key in the current Function. Objects stored using store_metadata can be retrieved when the database is reopened unless isAuto is set to True.
- toggle_region(hash)[source]¶
Toggle the collapsed state of a region during rendering, by hash value :param hash: Hash value of region
- unmerge_vars(target: Variable, sources: List[Variable] | Variable) None [source]¶
unmerge_vars
undoes variable merging performed withmerge_vars
. The variables insources
will no longer be merged into thetarget
variable.
- unsplit_var(var: Variable) None [source]¶
unsplit_var
undoes variable splitting performed withsplit_var
. The givenvar
must be the variable unique to the definition and should be obtained by usingMediumLevelILInstruction.get_split_var_for_definition
at the definition site.- Parameters:
var (Variable) – variable to unsplit
- Return type:
None
- property address_ranges: List[AddressRange]¶
All of the address ranges covered by a function
- property analysis_skip_override: FunctionAnalysisSkipOverride¶
Override for skipping of automatic analysis
- property analysis_skip_reason: AnalysisSkipReason¶
Function analysis skip reason
- property analysis_skipped: bool¶
Whether automatic analysis was skipped for this function. Can be set to false to re-enable analysis.
- property arch: Architecture¶
Function architecture (read-only)
- property auto: bool¶
Whether function was automatically discovered (read-only) as a result of some creation of a ‘user’ function. ‘user’ functions may or may not have been created by a user through the or API. For instance the entry point into a function is always created a ‘user’ function. ‘user’ functions should be considered the root of auto analysis.
- property auto_metadata: Dict[str, metadata.MetadataValueType]¶
metadata retrieves the metadata associated with the current function.
- Return type:
metadata associated with the function
- property basic_blocks: BasicBlockList¶
function.BasicBlockList of BasicBlocks in the current function (read-only)
- property call_sites: List[ReferenceSource]¶
call_sites
returns a list of possible call sites contained in this function. This includes ordinary calls, tail calls, and indirect jumps. Not all of the returned call sites are necessarily true call sites; some may simply be unresolved indirect jumps, for example.- Returns:
List of References that represent the sources of possible calls in this function
- Return type:
- property callee_addresses: List[int]¶
callee_addressses
returns a list of start addresses for functions that this function calls. Does not point to the actual address where the call occurs, just the start of the function that contains the reference.
- property callees: List[Function]¶
callees
returns a list of functions that this function calls This does not include the address of those calls, rather just the function objects themselves. Usecall_sites
to identify the location of these calls.
- property caller_sites: Generator[ReferenceSource, None, None]¶
caller_sites
returns a list of ReferenceSource objects corresponding to the addresses in functions which reference this function- Returns:
List of ReferenceSource objects of the call sites to this function
- Return type:
- property callers: List[Function]¶
callers
returns a list of functions that call this function Does not point to the actual address where the call occurs, just the start of the function that contains the call.
- property calling_convention: CallingConvention | None¶
Calling convention used by the function
- property can_return: BoolWithConfidence¶
Whether function can return
- property clobbered_regs: RegisterSet¶
Registers that are modified by this function
- property components¶
- property core_var_stack_layout: List[CoreVariable]¶
List of function stack variables (read-only)
- property core_vars: List[CoreVariable]¶
List of CoreVariable objects
- property global_pointer_value: RegisterValue¶
Discovered value of the global pointer register, if the function uses one (read-only)
- property has_explicitly_defined_type: bool¶
Whether function has explicitly defined types (read-only)
- property has_variable_arguments: BoolWithConfidence¶
Whether the function takes a variable number of arguments
- property high_level_il: HighLevelILFunction | None¶
returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property hlil: HighLevelILFunction | None¶
returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property hlil_if_available: HighLevelILFunction | None¶
returns HighLevelILFunction used to represent high level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if high level IL is available without generating it.
- property indirect_branches: List[IndirectBranchInfo]¶
List of indirect branches (read-only)
- property inline_during_analysis: BoolWithConfidence¶
Whether the function’s IL should be inlined into all callers’ IL
- property instructions: Generator[Tuple[List[InstructionTextToken], int], None, None]¶
A generator of instruction tokens and their start addresses for the current function
- property is_collapsed¶
If the entire function is collapsed during rendering.
- property is_pure: BoolWithConfidence¶
Whether function is pure
- property lifted_il: LowLevelILFunction | None¶
returns LowLevelILFunction used to represent lifted IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes lifted IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property lifted_il_if_available: LowLevelILFunction | None¶
returns LowLevelILFunction used to represent lifted IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if lifted IL is available without generating it.
- property llil: LowLevelILFunction | None¶
returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property llil_basic_blocks: Generator[LowLevelILBasicBlock, None, None]¶
A generator of all LowLevelILBasicBlock objects in the current function
- property llil_if_available: LowLevelILFunction | None¶
returns LowLevelILFunction used to represent low level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if low level IL is available without generating it.
- property low_level_il: LowLevelILFunction | None¶
returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property mapped_medium_level_il: MediumLevelILFunction | None¶
returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property medium_level_il: MediumLevelILFunction | None¶
returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property merged_vars: Dict[Variable, List[Variable]]¶
Map of merged variables, organized by target variable (read-only). Use
merge_vars
andunmerge_vars
to update merged variables.
- property metadata: Dict[str, metadata.MetadataValueType]¶
metadata retrieves the metadata associated with the current function.
- Return type:
metadata associated with the function
- property mlil: MediumLevelILFunction | None¶
returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property mlil_basic_blocks: Generator[MediumLevelILBasicBlock, None, None]¶
A generator of all MediumLevelILBasicBlock objects in the current function
- property mlil_if_available: MediumLevelILFunction | None¶
returns MediumLevelILFunction used to represent medium level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if medium level IL is available without generating it.
- property mmlil: MediumLevelILFunction | None¶
returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)
Note
This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
- property mmlil_if_available: MediumLevelILFunction | None¶
returns MediumLevelILFunction used to represent mapped medium level IL, or None if not loaded or it cannot be generated (read-only)
Note
This function can be used to check if mapped medium level IL is available without generating it.
- property parameter_vars: ParameterVariables¶
List of variables for the incoming function parameters
- property provenance¶
provenance
returns a string representing the provenance. This portion of the API is under development. Currently the provenance information is undocumented, not persistent, and not saved to a database.- Returns:
string representation of the provenance
- Return type:
- property pseudo_c: LanguageRepresentationFunction | None¶
- property pseudo_c_if_available: LanguageRepresentationFunction | None¶
- property reg_stack_adjustments: Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]¶
Number of entries removed from each register stack after return
- property return_regs: RegisterSet¶
Registers that are used for the return value
- property session_data: Any¶
Dictionary object where plugins can store arbitrary data associated with the function
- property split_vars: List[Variable]¶
Set of variables that have been split with
split_var
. These variables correspond to those unique to each definition site and are obtained by usingMediumLevelILInstruction.get_split_var_for_definition
at the definitions.
- property stack_adjustment: OffsetWithConfidence¶
Number of bytes removed from the stack after return
- property symbol: CoreSymbol¶
Function symbol(read-only)
- property tags: TagList¶
tags
gets a TagList of all Tags in the function (but not “function tags”). Tags are returned as an iterable indexable object TagList of (arch, address, Tag) tuples.- Return type:
TagList((Architecture, int, Tag))
- property too_large: bool¶
Whether the function is too large to automatically perform analysis (read-only)
- property total_bytes: int¶
Total bytes of a function calculated by summing each basic_block. Because basic blocks can overlap and have gaps between them this may or may not be equivalent to a .size property.
- property type: FunctionType¶
Function type object, can be set with either a string representing the function prototype (str(function) shows examples) or a
Type
object
- property type_tokens: List[InstructionTextToken]¶
Text tokens for this function’s prototype
- property unresolved_indirect_branches: List[Tuple[Architecture, int]]¶
List of unresolved indirect branches (read-only)
- property unresolved_stack_adjustment_graph: CoreFlowGraph | None¶
Flow graph of unresolved stack adjustments (read-only)
- property uses_incoming_global_pointer: bool¶
Whether the function uses the incoming global pointer value
- property view: BinaryView¶
Function view (read-only)
- property workflow¶
FunctionViewType¶
- class FunctionViewType[source]¶
Bases:
object
FunctionViewType(view_type: Union[ForwardRef(‘FunctionViewType’), binaryninja.enums.FunctionGraphType, str])
- __init__(view_type: FunctionViewType | FunctionGraphType | str)[source]¶
- Parameters:
view_type (FunctionViewType | FunctionGraphType | str) –
- view_type: FunctionGraphType¶
HighLevelILBasicBlockList¶
- class HighLevelILBasicBlockList[source]¶
Bases:
BasicBlockList
ILReferenceSource¶
- class ILReferenceSource[source]¶
Bases:
object
ILReferenceSource(func: Optional[ForwardRef(‘Function’)], arch: Optional[ForwardRef(‘architecture.Architecture’)], address: int, il_type: binaryninja.enums.FunctionGraphType, expr_id: int)
- __init__(func: Function | None, arch: Architecture | None, address: int, il_type: FunctionGraphType, expr_id: int) None ¶
- Parameters:
func (Function | None) –
arch (Architecture | None) –
address (int) –
il_type (FunctionGraphType) –
expr_id (int) –
- Return type:
None
- static get_il_name(il_type: FunctionGraphType) str [source]¶
- Parameters:
il_type (FunctionGraphType) –
- Return type:
- arch: Architecture | None¶
- il_type: FunctionGraphType¶
LowLevelILBasicBlockList¶
- class LowLevelILBasicBlockList[source]¶
Bases:
BasicBlockList
MediumLevelILBasicBlockList¶
- class MediumLevelILBasicBlockList[source]¶
Bases:
BasicBlockList
TagList¶
VariableReferenceSource¶
- class VariableReferenceSource[source]¶
Bases:
object
VariableReferenceSource(var: ‘variable.Variable’, src: binaryninja.function.ILReferenceSource)
- __init__(var: Variable, src: ILReferenceSource) None ¶
- Parameters:
var (Variable) –
src (ILReferenceSource) –
- Return type:
None
- src: ILReferenceSource¶