# coding=utf-8

# Copyright (c) 2015-2026 Vector 35 Inc

#

# Permission is hereby granted, free of charge, to any person obtaining a copy

# of this software and associated documentation files (the "Software"), to

# deal in the Software without restriction, including without limitation the

# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

# sell copies of the Software, and to permit persons to whom the Software is

# furnished to do so, subject to the following conditions:

#

# The above copyright notice and this permission notice shall be included in

# all copies or substantial portions of the Software.

#

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS

# IN THE SOFTWARE.

import ctypes

import inspect

from typing import Generator, Optional, List, Tuple, Union, Mapping, Any, Dict, overload

from dataclasses import dataclass

# Binary Ninja components

from . import _binaryninjacore as core

from .enums import (

AnalysisSkipReason, FunctionGraphType, SymbolType, SymbolBinding, InstructionTextTokenType, HighlightStandardColor,

HighlightColorStyle, DisassemblyOption, IntegerDisplayType, FunctionAnalysisSkipOverride, FunctionUpdateType,

BuiltinType, ExprFolding, EarlyReturn, SwitchRecovery, VariableSourceType, MetadataStoreFlag

)

from . import associateddatastore # Required in the main scope due to being an argument for _FunctionAssociatedDataStore

from . import types

from . import architecture

from . import lowlevelil

from . import mediumlevelil

from . import highlevelil

from . import binaryview

from . import basicblock

from . import databuffer

from . import variable

from . import flowgraph

from . import callingconvention

from . import workflow

from . import languagerepresentation

from . import deprecation

from . import metadata

from . import __version__

from .commonil import Localcall

# we define the following as such so the linter doesn't confuse 'highlight' the module with the

# property of the same name. There is probably some other work around but it eludes me.

from . import highlight as _highlight

from . import platform as _platform

# The following imports are for backward compatibility with API version < 3.0

# so old plugins which do 'from binaryninja.function import RegisterInfo' will still work

from .architecture import (

RegisterInfo, RegisterStackInfo, IntrinsicInput, IntrinsicInfo, InstructionBranch, InstructionInfo,

InstructionTextToken

)

from .variable import (

Variable, LookupTableEntry, RegisterValue, ValueRange, PossibleValueSet, StackVariableReference, ConstantReference,

IndirectBranchInfo, ParameterVariables, AddressRange

)

from . import decorators

from .enums import RegisterValueType

from . import component

ExpressionIndex = int

InstructionIndex = int

AnyFunctionType = Union['Function', 'lowlevelil.LowLevelILFunction', 'mediumlevelil.MediumLevelILFunction',

'highlevelil.HighLevelILFunction']

ILFunctionType = Union['lowlevelil.LowLevelILFunction', 'mediumlevelil.MediumLevelILFunction',

'highlevelil.HighLevelILFunction']

ILInstructionType = Union['lowlevelil.LowLevelILInstruction', 'mediumlevelil.MediumLevelILInstruction',

'highlevelil.HighLevelILInstruction']

StringOrType = Union[str, 'types.Type', 'types.TypeBuilder']

FunctionViewTypeOrName = Union['FunctionViewType', FunctionGraphType, str]

def _function_name_():

return inspect.stack()[1][0].f_code.co_name

@dataclass(frozen=True)

class ArchAndAddr:

arch: 'architecture.Architecture'

addr: int

def __repr__(self):

return f"<archandaddr {self.arch} @ {self.addr:#x}>"

class _FunctionAssociatedDataStore(associateddatastore._AssociatedDataStore):

_defaults = {}

class DisassemblySettings:

"""

``class DisassemblySettings`` contains the options used when rendering disassembly or IL text.

.. note::

Not every :py:class:`~binaryninja.enums.DisassemblyOption` applies to every representation. ``IndentHLILBody``

and ``ShowAddress`` are applied by linear view, not by

:py:func:`~binaryninja.highlevelil.HighLevelILInstruction.get_lines`; options acting on nested bodies, such as

``ShowCollapseIndicators``, only apply to HLIL in AST form. See `AST and Non-AST Forms

<https://docs.binary.ninja/dev/bnil-hlil.html#ast-and-non-ast-forms>`_.

"""

def __init__(self, handle: Optional[core.BNDisassemblySettingsHandle] = None):

if handle is None:

self.handle = core.BNCreateDisassemblySettings()

else:

self.handle = handle

def __del__(self):

if core is not None:

core.BNFreeDisassemblySettings(self.handle)

@property

def width(self) -> int:

return core.BNGetDisassemblyWidth(self.handle)

@width.setter

def width(self, value: int) -> None:

core.BNSetDisassemblyWidth(self.handle, value)

@property

def max_symbol_width(self) -> int:

return core.BNGetDisassemblyMaximumSymbolWidth(self.handle)

@max_symbol_width.setter

def max_symbol_width(self, value: int) -> None:

core.BNSetDisassemblyMaximumSymbolWidth(self.handle, value)

def is_option_set(self, option: DisassemblyOption) -> bool:

if isinstance(option, str):

option = DisassemblyOption[option]

return core.BNIsDisassemblySettingsOptionSet(self.handle, option)

def set_option(self, option: DisassemblyOption, state: bool = True) -> None:

if isinstance(option, str):

option = DisassemblyOption[option]

core.BNSetDisassemblySettingsOption(self.handle, option, state)

@staticmethod

def default_settings() -> 'DisassemblySettings':

return DisassemblySettings(core.BNDefaultDisassemblySettings())

@staticmethod

def default_graph_settings() -> 'DisassemblySettings':

return DisassemblySettings(core.BNDefaultGraphDisassemblySettings())

@staticmethod

def default_linear_settings() -> 'DisassemblySettings':

return DisassemblySettings(core.BNDefaultLinearDisassemblySettings())

@dataclass

class ILReferenceSource:

func: Optional['Function']

arch: Optional['architecture.Architecture']

address: int

il_type: FunctionGraphType

expr_id: ExpressionIndex

@staticmethod

def get_il_name(il_type: FunctionGraphType) -> str:

if il_type == FunctionGraphType.NormalFunctionGraph:

return 'disassembly'

if il_type == FunctionGraphType.LowLevelILFunctionGraph:

return 'llil'

if il_type == FunctionGraphType.LiftedILFunctionGraph:

return 'lifted_llil'

if il_type == FunctionGraphType.LowLevelILSSAFormFunctionGraph:

return 'llil_ssa'

if il_type == FunctionGraphType.MediumLevelILFunctionGraph:

return 'mlil'

if il_type == FunctionGraphType.MediumLevelILSSAFormFunctionGraph:

return 'mlil_ssa'

if il_type == FunctionGraphType.MappedMediumLevelILFunctionGraph:

return 'mapped_mlil'

if il_type == FunctionGraphType.MappedMediumLevelILSSAFormFunctionGraph:

return 'mapped_mlil_ssa'

if il_type == FunctionGraphType.HighLevelILFunctionGraph:

return 'hlil'

if il_type == FunctionGraphType.HighLevelILSSAFormFunctionGraph:

return 'hlil_ssa'

return ""

def __repr__(self):

if self.arch:

return f"<ref: {self.arch}@{self.address:#x}, {self.get_il_name(self.il_type)}@{self.expr_id}>"

else:

return f"<ref: {self.address:#x}, {self.get_il_name(self.il_type)}@{self.expr_id}>"

@dataclass

class VariableReferenceSource:

var: 'variable.Variable'

src: ILReferenceSource

def __repr__(self):

return f"<var: {repr(self.var)}, src: {repr(self.src)}>"

@dataclass

class FunctionViewType:

view_type: FunctionGraphType

name: Optional[str]

def __init__(self, view_type: FunctionViewTypeOrName):

if isinstance(view_type, FunctionViewType):

self.view_type = view_type.view_type

self.name = view_type.name

elif isinstance(view_type, FunctionGraphType):

self.view_type = view_type

self.name = None

else:

self.view_type = FunctionGraphType.HighLevelLanguageRepresentationFunctionGraph

self.name = str(view_type)

def __hash__(self):

return hash((self.view_type, self.name))

@staticmethod

def _from_core_struct(view_type: core.BNFunctionViewType) -> 'FunctionViewType':

if view_type.type == FunctionGraphType.HighLevelLanguageRepresentationFunctionGraph:

if view_type.name is None:

return FunctionViewType("Pseudo C")

else:

return FunctionViewType(view_type.name)

else:

return FunctionViewType(view_type.type)

def _to_core_struct(self) -> core.BNFunctionViewType:

result = core.BNFunctionViewType()

result.type = self.view_type

result.name = self.name

return result

class BasicBlockList:

def __init__(

self, function: Union['Function', 'lowlevelil.LowLevelILFunction', 'mediumlevelil.MediumLevelILFunction',

'highlevelil.HighLevelILFunction']

):

self._count, self._blocks = function._basic_block_list()

self._function = function

self._n = 0

def __repr__(self):

return f"<BasicBlockList {len(self)} BasicBlocks: {list(self)}>"

def __del__(self):

if core is not None:

core.BNFreeBasicBlockList(self._blocks, len(self))

def __len__(self):

return self._count.value

def __iter__(self):

return BasicBlockList(self._function)

def __next__(self) -> 'basicblock.BasicBlock':

if self._n >= len(self):

raise StopIteration

block = core.BNNewBasicBlockReference(self._blocks[self._n])

assert block is not None, "core.BNNewBasicBlockReference returned None"

self._n += 1

return self._function._instantiate_block(block)

@overload

def __getitem__(self, i: int) -> 'basicblock.BasicBlock': ...

@overload

def __getitem__(self, i: slice) -> List['basicblock.BasicBlock']: ...

def __getitem__(self, i: Union[int, slice]) -> Union['basicblock.BasicBlock', List['basicblock.BasicBlock']]:

if isinstance(i, int):

if i < 0:

i = len(self) + i

if i >= len(self):

raise IndexError(f"Index {i} out of bounds for BasicBlockList of size {len(self)}")

block = core.BNNewBasicBlockReference(self._blocks[i])

assert block is not None, "core.BNNewBasicBlockReference returned None"

return self._function._instantiate_block(block)

elif isinstance(i, slice):

result = []

start, stop, step = i.indices(len(self))

for j in range(start, stop, step):

block = core.BNNewBasicBlockReference(self._blocks[j])

assert block is not None, "core.BNNewBasicBlockReference returned None"

result.append(self._function._instantiate_block(block))

return result

raise ValueError("BasicBlockList.__getitem__ supports argument of type integer or slice only")

class LowLevelILBasicBlockList(BasicBlockList):

def __repr__(self):

return f"<LowLevelILBasicBlockList {len(self)} BasicBlocks: {list(self)}>"

@overload

def __getitem__(self, i: int) -> 'lowlevelil.LowLevelILBasicBlock': ...

@overload

def __getitem__(self, i: slice) -> List['lowlevelil.LowLevelILBasicBlock']: ...

def __getitem__(

self, i: Union[int, slice]

) -> Union['lowlevelil.LowLevelILBasicBlock', List['lowlevelil.LowLevelILBasicBlock']]:

return BasicBlockList.__getitem__(self, i) # type: ignore

def __next__(self) -> 'lowlevelil.LowLevelILBasicBlock':

return BasicBlockList.__next__(self) # type: ignore

class MediumLevelILBasicBlockList(BasicBlockList):

def __repr__(self):

return f"<MediumLevelILBasicBlockList {len(self)} BasicBlocks: {list(self)}>"

@overload

def __getitem__(self, i: int) -> 'mediumlevelil.MediumLevelILBasicBlock': ...

@overload

def __getitem__(self, i: slice) -> List['mediumlevelil.MediumLevelILBasicBlock']: ...

def __getitem__(

self, i: Union[int, slice]

) -> Union['mediumlevelil.MediumLevelILBasicBlock', List['mediumlevelil.MediumLevelILBasicBlock']]:

return BasicBlockList.__getitem__(self, i) # type: ignore

def __next__(self) -> 'mediumlevelil.MediumLevelILBasicBlock':

return BasicBlockList.__next__(self) # type: ignore

class HighLevelILBasicBlockList(BasicBlockList):

def __repr__(self):

return f"<HighLevelILBasicBlockList {len(self)} BasicBlocks: {list(self)}>"

@overload

def __getitem__(self, i: int) -> 'highlevelil.HighLevelILBasicBlock': ...

@overload

def __getitem__(self, i: slice) -> List['highlevelil.HighLevelILBasicBlock']: ...

def __getitem__(

self, i: Union[int, slice]

) -> Union['highlevelil.HighLevelILBasicBlock', List['highlevelil.HighLevelILBasicBlock']]:

return BasicBlockList.__getitem__(self, i) # type: ignore

def __next__(self) -> 'highlevelil.HighLevelILBasicBlock':

return BasicBlockList.__next__(self) # type: ignore

class TagList:

def __init__(self, function: 'Function'):

self._count = ctypes.c_ulonglong()

tags = core.BNGetAddressTagReferences(function.handle, self._count)

assert tags is not None, "core.BNGetAddressTagReferences returned None"

self._tags = tags

self._function = function

self._n = 0

def __repr__(self):

return f"<TagList {len(self)} Tags: {list(self)}>"

def __del__(self):

if core is not None:

core.BNFreeTagReferences(self._tags, len(self))

def __len__(self):

return self._count.value

def __iter__(self):

return self

def __next__(self) -> Tuple['architecture.Architecture', int, 'binaryview.Tag']:

if self._n >= len(self):

raise StopIteration

core_tag = core.BNNewTagReference(self._tags[self._n].tag)

arch = architecture.CoreArchitecture._from_cache(self._tags[self._n].arch)

address = self._tags[self._n].addr

assert core_tag is not None, "core.BNNewTagReference returned None"

self._n += 1

return arch, address, binaryview.Tag(core_tag)

@overload

def __getitem__(self, i: int) -> Tuple['architecture.Architecture', int, 'binaryview.Tag']: ...

@overload

def __getitem__(self, i: slice) -> List[Tuple['architecture.Architecture', int, 'binaryview.Tag']]: ...

def __getitem__(

self, i: Union[int, slice]

) -> Union[Tuple['architecture.Architecture', int, 'binaryview.Tag'], List[Tuple['architecture.Architecture', int, 'binaryview.Tag']]]:

if isinstance(i, int):

if i < 0:

i = len(self) + i

if i >= len(self):

raise IndexError(f"Index {i} out of bounds for TagList of size {len(self)}")

core_tag = core.BNNewTagReference(self._tags[i].tag)

arch = architecture.CoreArchitecture._from_cache(self._tags[i].arch)

assert core_tag is not None, "core.BNNewTagReference returned None"

return arch, self._tags[i].addr, binaryview.Tag(core_tag)

elif isinstance(i, slice):

result = []

start, stop, step = i.indices(len(self))

for j in range(start, stop, step):

core_tag = core.BNNewTagReference(self._tags[j].tag)

assert core_tag is not None, "core.BNNewTagReference returned None"

arch = architecture.CoreArchitecture._from_cache(self._tags[j].arch)

result.append((arch, self._tags[j].addr, binaryview.Tag(core_tag)))

return result

raise ValueError("TagList.__getitem__ supports argument of type integer or slice only")

class Function:

_associated_data = {}

"""

The examples in the following code will use the following variables

>>> from binaryninja import *

>>> bv = load("/bin/ls")

>>> current_function = bv.functions[0]

>>> here = current_function.start

"""

def __init__(self, view: Optional['binaryview.BinaryView'] = None, handle: Optional[core.BNFunctionHandle] = None):

self._advanced_analysis_requests = 0

assert handle is not None, "creation of standalone 'Function' objects is not implemented"

FunctionHandle = ctypes.POINTER(core.BNFunction)

self.handle = ctypes.cast(handle, FunctionHandle)

if view is None:

self._view = binaryview.BinaryView(handle=core.BNGetFunctionData(self.handle))

else:

self._view = view

self._arch = None

self._platform = None

def __del__(self):

if core is not None and self.handle is not None:

if self._advanced_analysis_requests > 0:

core.BNReleaseAdvancedFunctionAnalysisDataMultiple(self.handle, self._advanced_analysis_requests)

core.BNFreeFunction(self.handle)

def __repr__(self):

arch = self.arch

if arch:

return f"<func: {arch.name}@{self.start:#x}>"

else:

return f"<func: {self.start:#x}>"

def __eq__(self, other: 'Function') -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)

def __ne__(self, other: 'Function') -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return not (self == other)

def __lt__(self, other: 'Function') -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return self.start < other.start

def __gt__(self, other: 'Function') -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return self.start > other.start

def __le__(self, other: 'Function') -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return self.start <= other.start

def __ge__(self, other: 'Function') -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return self.start >= other.start

def __hash__(self):

return hash((self.start, self.arch, self.platform))

@overload

def __getitem__(self, i: int) -> 'basicblock.BasicBlock': ...

@overload

def __getitem__(self, i: slice) -> List['basicblock.BasicBlock']: ...

def __getitem__(self, i: Union[int, slice]) -> Union['basicblock.BasicBlock', List['basicblock.BasicBlock']]:

return self.basic_blocks[i]

def __iter__(self) -> Generator['basicblock.BasicBlock', None, None]:

yield from self.basic_blocks

def __str__(self):

result = ""

for token in self.type_tokens:

result += token.text

return result

def __contains__(self, value: Union[basicblock.BasicBlock, int]):

if isinstance(value, basicblock.BasicBlock):

return value.function == self

return self in [block.function for block in self.view.get_basic_blocks_at(int(value))]

@classmethod

def _unregister(cls, func: 'core.BNFunction') -> None:

handle = ctypes.cast(func, ctypes.c_void_p)

if handle.value in cls._associated_data:

del cls._associated_data[handle.value]

@staticmethod

def set_default_session_data(name: str, value) -> None:

_FunctionAssociatedDataStore.set_default(name, value)

@property

def name(self) -> str:

"""Symbol name for the function"""

return self.symbol.name

@name.setter

def name(self, value: Union[str, 'types.CoreSymbol']) -> None: # type: ignore

if value is None:

if self.symbol is not None:

self.view.undefine_user_symbol(self.symbol)

elif isinstance(value, str):

symbol = types.Symbol(SymbolType.FunctionSymbol, self.start, value)

self.view.define_user_symbol(symbol)

elif isinstance(value, types.Symbol):

self.view.define_user_symbol(value)

@property

def view(self) -> 'binaryview.BinaryView':

"""Function view (read-only)"""

return self._view

@property

def arch(self) -> 'architecture.Architecture':

"""Function architecture (read-only)"""

if self._arch:

return self._arch

else:

arch = core.BNGetFunctionArchitecture(self.handle)

assert arch is not None, "core.BNGetFunctionArchitecture returned None"

self._arch = architecture.CoreArchitecture._from_cache(arch)

return self._arch

@property

def platform(self) -> Optional['_platform.Platform']:

"""Function platform (read-only)"""

if self._platform:

return self._platform

else:

plat = core.BNGetFunctionPlatform(self.handle)

if plat is None:

return None

self._platform = _platform.CorePlatform._from_cache(handle=plat)

return self._platform

@property

def start(self) -> int:

"""Function start address (read-only)"""

return core.BNGetFunctionStart(self.handle)

@property

def total_bytes(self) -> 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.

"""

return sum(map(len, self))

@property

def highest_address(self) -> int:

"""The highest (largest) virtual address contained in a function."""

return core.BNGetFunctionHighestAddress(self.handle)

@property

def lowest_address(self) -> int:

"""The lowest (smallest) virtual address contained in a function."""

return core.BNGetFunctionLowestAddress(self.handle)

@property

def address_ranges(self) -> List['variable.AddressRange']:

"""All of the address ranges covered by a function"""

count = ctypes.c_ulonglong(0)

range_list = core.BNGetFunctionAddressRanges(self.handle, count)

assert range_list is not None, "core.BNGetFunctionAddressRanges returned None"

result = []

for i in range(0, count.value):

result.append(variable.AddressRange(range_list[i].start, range_list[i].end))

core.BNFreeAddressRanges(range_list)

return result

@property

def symbol(self) -> 'types.CoreSymbol':

"""Function symbol(read-only)"""

sym = core.BNGetFunctionSymbol(self.handle)

assert sym is not None, "core.BNGetFunctionSymbol returned None"

return types.CoreSymbol(sym)

@property

def is_exported(self) -> bool:

"""

Whether the function is exported (read-only).

A function is considered exported when its symbol binding is global or weak.

"""

binding = self.symbol.binding

return binding in (SymbolBinding.GlobalBinding, SymbolBinding.WeakBinding)

@property

def auto(self) -> 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.

"""

return core.BNWasFunctionAutomaticallyDiscovered(self.handle)

@property

def has_user_annotations(self) -> bool:

"""

Whether the function has ever been 'user' modified

"""

return core.BNFunctionHasUserAnnotations(self.handle)

@property

def can_return(self) -> 'types.BoolWithConfidence':

"""Whether function can return"""

result = core.BNCanFunctionReturn(self.handle)

return types.BoolWithConfidence(result.value, confidence=result.confidence)

@can_return.setter

def can_return(self, value: 'types.BoolWithConfidence') -> None:

bc = core.BNBoolWithConfidence()

bc.value = bool(value)

if hasattr(value, 'confidence'):

bc.confidence = value.confidence

else:

bc.confidence = core.max_confidence

core.BNSetUserFunctionCanReturn(self.handle, bc)

@property

def is_pure(self) -> 'types.BoolWithConfidence':

"""Whether function is pure"""

result = core.BNIsFunctionPure(self.handle)

return types.BoolWithConfidence(result.value, confidence=result.confidence)

@is_pure.setter

def is_pure(self, value: 'types.BoolWithConfidence') -> None:

bc = core.BNBoolWithConfidence()

bc.value = bool(value)

if hasattr(value, 'confidence'):

bc.confidence = value.confidence

else:

bc.confidence = core.max_confidence

core.BNSetUserFunctionPure(self.handle, bc)

@property

def has_explicitly_defined_type(self) -> bool:

"""Whether function has explicitly defined types (read-only)"""

return core.BNFunctionHasExplicitlyDefinedType(self.handle)

@property

def needs_update(self) -> bool:

"""Whether the function has analysis that needs to be updated (read-only)"""

return core.BNIsFunctionUpdateNeeded(self.handle)

def _basic_block_list(self):

count = ctypes.c_ulonglong()

blocks = core.BNGetFunctionBasicBlockList(self.handle, count)

assert blocks is not None, "core.BNGetFunctionBasicBlockList returned None"

return count, blocks

def _instantiate_block(self, handle):

return basicblock.BasicBlock(handle, self.view)

@property

def basic_blocks(self) -> BasicBlockList:

"""function.BasicBlockList of BasicBlocks in the current function (read-only)"""

return BasicBlockList(self)

@property

def is_thunk(self) -> bool:

"""Returns True if the function starts with a Tailcall (read-only)"""

if self.llil_if_available is not None:

return self.llil_if_available.is_thunk

else:

return False

@property

def comments(self) -> Dict[int, str]:

"""Dict of comments (read-only)"""

count = ctypes.c_ulonglong()

addrs = core.BNGetCommentedAddresses(self.handle, count)

assert addrs is not None, "core.BNGetCommentedAddresses returned None"

try:

result = {}

for i in range(0, count.value):

result[addrs[i]] = self.get_comment_at(addrs[i])

return result

finally:

core.BNFreeAddressList(addrs)

@property

def tags(self) -> 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.

:rtype: TagList((Architecture, int, Tag))

"""

return TagList(self)

def get_tags_at(self, addr: int, arch: Optional['architecture.Architecture'] = None, auto: Optional[bool] = None) -> List['binaryview.Tag']:

"""

``get_tags`` gets a list of Tags (but not function tags).

:param int addr: Address to get tags from.

:param bool auto: If None, gets all tags, if True, gets auto tags, if False, gets user tags

:rtype: list((Architecture, int, Tag))

"""

if arch is None:

assert self.arch is not None, "Can't call get_tags_at for function with no architecture specified"

arch = self.arch

count = ctypes.c_ulonglong()

if auto is None:

tags = core.BNGetAddressTags(self.handle, arch.handle, addr, count)

assert tags is not None, "core.BNGetAddressTags returned None"

elif auto:

tags = core.BNGetAutoAddressTags(self.handle, arch.handle, addr, count)

assert tags is not None, "core.BNGetAutoAddressTags returned None"

else:

tags = core.BNGetUserAddressTags(self.handle, arch.handle, addr, count)

assert tags is not None, "core.BNGetUserAddressTags returned None"

result = []

try:

for i in range(0, count.value):

core_tag = core.BNNewTagReference(tags[i])

assert core_tag is not None, "core.BNNewTagReference returned None"

result.append(binaryview.Tag(core_tag))

return result

finally:

core.BNFreeTagList(tags, count.value)

def get_tags_in_range(

self, address_range: 'variable.AddressRange', arch: Optional['architecture.Architecture'] = None, auto: Optional[bool] = None

) -> List[Tuple['architecture.Architecture', int, 'binaryview.Tag']]:

"""

``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.

:param AddressRange address_range: Address range from which to get tags

:param Architecture arch: Architecture for the block in which the Tag is located (optional)

:param bool auto: If None, gets all tags, if True, gets auto tags, if False, gets user tags

:return: A list of (arch, address, Tag) tuples

:rtype: list((Architecture, int, Tag))

"""

if arch is None:

assert self.arch is not None, "Can't call get_address_tags_in_range for function with no architecture specified"

arch = self.arch

count = ctypes.c_ulonglong()

if auto is None:

refs = core.BNGetAddressTagsInRange(self.handle, arch.handle, address_range.start, address_range.end, count)

assert refs is not None, "core.BNGetAddressTagsInRange returned None"

elif auto:

refs = core.BNGetAutoAddressTagsInRange(self.handle, arch.handle, address_range.start, address_range.end, count)

assert refs is not None, "core.BNGetAutoAddressTagsInRange returned None"

else:

refs = core.BNGetUserAddressTagsInRange(self.handle, arch.handle, address_range.start, address_range.end, count)

assert refs is not None, "core.BNGetUserAddressTagsInRange returned None"

try:

result = []

for i in range(0, count.value):

tag_ref = core.BNNewTagReference(refs[i].tag)

assert tag_ref is not None, "core.BNNewTagReference returned None"

tag = binaryview.Tag(tag_ref)

result.append((arch, refs[i].addr, tag))

return result

finally:

core.BNFreeTagReferences(refs, count.value)

def get_function_tags(self, auto: Optional[bool] = None, tag_type: Optional[str] = None) -> List['binaryview.Tag']:

"""

``get_function_tags`` gets a list of function Tags for the function.

:param bool auto: If None, gets all tags, if True, gets auto tags, if False, gets user tags

:param str tag_type: If None, gets all tags, otherwise only gets tags of the given type

:rtype: list(Tag)

"""

count = ctypes.c_ulonglong()

tags = []

if tag_type is not None:

tag_type = self.view.get_tag_type(tag_type)

if tag_type is None:

return []

if auto is None:

tags = core.BNGetFunctionTagsOfType(self.handle, tag_type.handle, count)

assert tags is not None, "core.BNGetFunctionTagsOfType returned None"

elif auto:

tags = core.BNGetAutoFunctionTagsOfType(self.handle, tag_type.handle, count)

assert tags is not None, "core.BNGetAutoFunctionTagsOfType returned None"

else:

tags = core.BNGetUserFunctionTagsOfType(self.handle, tag_type.handle, count)

assert tags is not None, "core.BNGetUserFunctionTagsOfType returned None"

else:

if auto is None:

tags = core.BNGetFunctionTags(self.handle, count)

assert tags is not None, "core.BNGetFunctionTags returned None"

elif auto:

tags = core.BNGetAutoFunctionTags(self.handle, count)

assert tags is not None, "core.BNGetAutoFunctionTags returned None"

else:

tags = core.BNGetUserFunctionTags(self.handle, count)

assert tags is not None, "core.BNGetUserFunctionTags returned None"

try:

result = []

for i in range(count.value):

core_tag = core.BNNewTagReference(tags[i])

assert core_tag is not None, "core.BNNewTagReference returned None"

result.append(binaryview.Tag(core_tag))

return result

finally:

core.BNFreeTagList(tags, count.value)

def add_tag(

self, tag_type: str, data: str, addr: Optional[int] = None, auto: bool = False,

arch: Optional['architecture.Architecture'] = None

):

"""

``add_tag`` creates and adds a :py:class:`Tag` 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 :py:func:`~binaryninja.binaryview.BinaryView.add_tag`.

:param str tag_type: The name of the tag type for this Tag

:param str data: additional data for the Tag

:param int addr: address at which to add the tag

:param bool auto: Whether or not an auto tag

:param Architecture arch: 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.

"""

tag_type = self.view.get_tag_type(tag_type)

if tag_type is None:

return

if arch is None:

arch = self.arch

# Create tag

tag_handle = core.BNCreateTag(tag_type.handle, data)

assert tag_handle is not None, "core.BNCreateTag returned None"

tag = binaryview.Tag(tag_handle)

core.BNAddTag(self.view.handle, tag.handle, auto)

if auto:

if addr is None:

core.BNAddAutoFunctionTag(self.handle, tag.handle)

else:

core.BNAddAutoAddressTag(self.handle, arch.handle, addr, tag.handle)

else:

if addr is None:

core.BNAddUserFunctionTag(self.handle, tag.handle)

else:

core.BNAddUserAddressTag(self.handle, arch.handle, addr, tag.handle)

def remove_user_address_tag(

self, addr: int, tag: 'binaryview.Tag', arch: Optional['architecture.Architecture'] = None

) -> None:

"""

``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.

:param int addr: Address at which to remove the tag

:param Tag tag: Tag object to be added

:param Architecture arch: Architecture for the block in which the Tag is added (optional)

:rtype: None

"""

if arch is None:

arch = self.arch

core.BNRemoveUserAddressTag(self.handle, arch.handle, addr, tag.handle)

def remove_user_function_tag(self, tag: 'binaryview.Tag') -> None:

"""

``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.

:param Tag tag: Tag object to be added

:rtype: None

"""

core.BNRemoveUserFunctionTag(self.handle, tag.handle)

def remove_user_address_tags_of_type(self, addr: int, tag_type: str, arch=None):

"""

``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.

:param int addr: Address at which to remove the tag

:param Tag tag_type: TagType object to match for removing

:param Architecture arch: Architecture for the block in which the Tags is located (optional)

:rtype: None

"""

if arch is None:

arch = self.arch

tag_type = self.view.get_tag_type(tag_type)

if tag_type is not None:

core.BNRemoveUserAddressTagsOfType(self.handle, arch.handle, addr, tag_type.handle)

def remove_auto_address_tag(

self, addr: int, tag: 'binaryview.Tag', arch: Optional['architecture.Architecture'] = None

) -> None:

"""

``remove_auto_address_tag`` removes a Tag object at a given address.

:param int addr: Address at which to add the tag

:param Tag tag: Tag object to be added

:param Architecture arch: Architecture for the block in which the Tag is added (optional)

:rtype: None

"""

if arch is None:

arch = self.arch

core.BNRemoveAutoAddressTag(self.handle, arch.handle, addr, tag.handle)

def remove_auto_address_tags_of_type(self, addr: int, tag_type: str, arch=None):

"""

``remove_auto_address_tags_of_type`` removes all tags at the given address of the given type.

:param int addr: Address at which to remove the tags

:param Tag tag_type: TagType object to match for removing

:param Architecture arch: Architecture for the block in which the Tags is located (optional)

:rtype: None

"""

if arch is None:

arch = self.arch

tag_type = self.view.get_tag_type(tag_type)

if tag_type is not None:

core.BNRemoveAutoAddressTagsOfType(self.handle, arch.handle, addr, tag_type.handle)

def remove_user_function_tags_of_type(self, tag_type: str):

"""

``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.

:param TagType tag_type: TagType object to match for removing

:rtype: None

"""

tag_type = self.view.get_tag_type(tag_type)

if tag_type is not None:

core.BNRemoveUserFunctionTagsOfType(self.handle, tag_type.handle)

def remove_auto_function_tag(self, tag: 'binaryview.Tag') -> None:

"""

``remove_user_function_tag`` removes a Tag object as a function tag.

:param Tag tag: Tag object to be added

:rtype: None

"""

core.BNRemoveAutoFunctionTag(self.handle, tag.handle)

def remove_auto_function_tags_of_type(self, tag_type: str):

"""

``remove_user_function_tags_of_type`` removes all function Tag objects on a function of a given type

:param TagType tag_type: TagType object to match for removing

:rtype: None

"""

tag_type = self.view.get_tag_type(tag_type)

if tag_type is not None:

core.BNRemoveAutoFunctionTagsOfType(self.handle, tag_type.handle)

@property

def low_level_il(self) -> Optional['lowlevelil.LowLevelILFunction']:

"""

returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL

(read-only)