Functions & Basic blocks

BipFunction are created by passing them an address. They are container for basic block (BipBlock accessible using the blocks() property) and instruction (BipInstr accessible using the instr() property). BipBlock them self contain instructions, a link back to the function (property func()) and a way to navigate them using the property succ() and BipBlock.pred() .

BipFunction can also allow to recuperate the hexrays decompile version of their code when available, this is done using the hxcfunc() property which return a HxCFunc object when available.

For example of how to use functions and blocks see the Overview .

BipFunction API

class bip.base.BipFunction(ea=None)

Class for representing and manipulating function in IDA.

Todo

provide interface for flowgraph and allow to get all basicblocks and not only the one included in the function (external block: without FC_NOEXT flag)

Todo

Interface with stack

Todo

color

Todo

frame ?

Todo

setter for start ea (BipFunction.ea()) and end ea (BipFunction.end())

__init__(ea=None)

Constructor for a BipFunction object.

This function will raise a ValueError if the address ea is not in the function.

Parameters:ea – An address included in the function, it does not need to be the first one. If None the screen address is used.
_funct = None

Internal func_t object from IDA

ea

Property which return the start address of the function.

Return int:The address of the function.
end

Property which return the address at the end of the function. This address is not included in the function.

Return int:The stop address of the function. This address is not included in the function.
size

Property which allow to get the size of the function in bytes.

Return int:The number of bytes in the function.
name

Property which return the name of the function as display in the IDA window.

This function does not handle mangling, see demangle_name().

Return str:The name of the function.
demangle_name

Property which return the demangle name of the function.

Return str:The demangle name of the function.
is_dummy_name

Property for checking if the current name of this function is a “dummy” name (a name set by default by IDA when it does not know how to call an element) with a special prefix. This function will not recognize the aSTRING naming, see is_auto_name(), and is_ida_name().

Returns:True if the function has a dummy name, False otherwise.
is_auto_name

Property for checking if the current name of this function is an “auto-generated” name, those are the default name generated by IDA but without a special prefix (see is_dummy_name()) such as the one for the string. See also is_ida_name().

Returns:True if the function has an auto-generated name, False otherwise.
is_ida_name

Property for checking if the current name is a default name as generated by IDA. This is an OR condition of is_auto_name() and is_dummy_name().

Returns:True if the function has a name provided by IDA, False otherwise.
is_user_name

Property for checking if the current name is a “user name”. In practice this check a flag that the API can avoid setting, so there is no garantee it is an actual user name. See is_ida_name() for checking if a name was generated by IDA.

Returns:True if the name is marked as set by a user, False otherwise.
truename

Property which return the true name of the function.

Return str:The true name of the function.
ordinal

Property which return the ordinal of this function.

Return int:The number corresponding to the ordinal of this function.
__str__() <==> str(x)
__eq__(other)

Equality comparator with another BipFunction. Return NotImplemented if the argument is not a BipFunction.

__ne__(other)

Inequality comparator with another BipFunction. Return NotImplemented if the argument is not a BipFunction.

__lt__(other)

Lesser than comparator with another BipFunction. Return NotImplemented if the argument is not a BipFunction.

__le__(other)

Lesser or equal comparator with another BipFunction. Return NotImplemented if the argument is not a BipFunction.

__gt__(other)

Greater than comparator with another BipFunction. Return NotImplemented if the argument is not a BipFunction.

__ge__(other)

Gretter or equal comparator with another BipFunction. Return NotImplemented if the argument is not a BipFunction.

__hash__()

Compute a unique hash for this ida function. The produce hash is dependant of the type of the object (BipFunction) and of its address. This allow to create container using the hash of the object for matching an object of a defined type and with a particular address.

Calculation made is: hash(type(self)) ^ self.ea, in particular it means than child classes will not have the same hash as a parrent classes even if the compare works.

Returns:An integer corresponding to the hash for this object.
__contains__(value)

Allow to check if an element is included inside this function. It accepts the following in arguments:

In all those case the address of the element is used for testing if it is present in the function.

hxcfunc

Property which return the hexrays C function (HxCFunc) for this function.

If if it not possible to import the hexrays API an NotImplementedError error will be raised.

This may raise a BipDecompileError if the decompilation failed.

Returns:A HxCFunc object equivalent to this function.
can_decompile

Property which test if it is possible to get the hexrays C function (HxCFunc) for this function.

Internally this will just try to call BipFunction.hxcfunc() and catch the error, this means calling this function will actually perform the decompilation.

Returns:True if its possible to get the HxCFunc object for this BipFunction, False otherwise.
flags

Property which return the function flags as returned by idc.GetFunctionFlags (old) or idc.get_func_attr(ea, FUNCATTR_FLAGS) (new).

Return int:The flags for this function.
is_inside(o)

Allow to check if an address or an BipElt object (or inherited) is included in this function. In particular it allow to check if an BipInstr is included in a function.

This function is based on the func_t.contains function of IDA, this function seems to check only the address compare to the start and end address of a function and will return False for function chunk.

Parameters:o (int coresponding to an address or an object inherited from BipElt .) – The address or object to test for inclusion.
Raises:TypeError – if the parameter o is not from a valid type.
does_return

Property which indicate if the function is expected to return.

Return boolean:True if the function is expected to return.
is_far

Check flags of this function for knowing if this is a far function.

is_lib

Check flags of this function for knowing if this is a library function.

is_static

Check flags of this function for knowing if this is a static function.

use_frame

Check flags of this function for knowing if it is using the frame pointer.

is_userfar

Check flags of this function for knowing if the user as define the function as change the marking of the function being far or not.

is_hidden

Check flags of this function for knowing if its a hidden function.

is_thunk

Check flags of this function for knowing if its a thunk function.

comment

Property which allow access to the comment.

rcomment

Property which allow access to the repeatable comment.

_flowchart

Return a FlowChart object as defined by IDA in ida_gdl.py. This is used for getting the basic block and should not be used directly.

Note

Internally this is compute with the flags _BipFlowChartFlag.FC_PREDS and _BipFlowChartFlag.FC_NOEXT .

Returns:An idaapi.FlowChart object.
nb_blocks

Return the number of blocks present in this function.

blocks

Return a list of BipBlock corresponding to the BasicBlocks in this function.

Returns:A list of object BipBlock
blocks_iter

Return a generator of BipBlock corresponding to the BasicBlocks in this function. This implementation will be just a little more performant than the blocks() property.

Returns:A generator of object BipBlock
items

Return a list of BipElt corresponding to the items of the functions.

Note

This should mainly be BipInstr but possible in theory to be other kind of data.

Returns:A list of object BipElt.
instr

Return a list of BipInstr corresponding to the instructions of the functions.

Returns:A list of object BipInstr
instr_iter

Return a generator of BipInstr corresponding to the instructions of the functions. This implementation will be just a little more performant than the instr() property.

Returns:A generator of object BipInstr
bytes

Property returning the value of the bytes contain in the function.

Returns:A list of the bytes forming the element.
Return type:list(int)
_ida_tinfo

Internal property which allow to get the tinfo_t swig proxy from IDA associated with this function. Internally this use the idaapi.get_type method with the third argument (type_source_t) as idaapi.GUESSED_FUNC .

This property can raise a BipError in case it was not possible to determine (guess ?) the type, meaning the idaapi.get_type returned false. It should be possible to try with a less agressive type source, but except problem with this way it is probably better to be more restrective than less.

Note

When a function is decompiled using hexrays IDA will have a usually way better guess on the type of the function so it may be a good idea to decompile the function before getting the type.

Returns:The ida_typeinf.tinfo_t object (swig proxy) provided by IDA for this function.
str_type

Property which return the type (prototype) of the function.

Return str:String representing the type of the function.
guess_strtype

Property which allow to return the prototype of the function guessed by IDA.

Return str:The guess prototype of the function.
xTo

Property which allow to get all xrefs pointing to (to) this function. This is the equivalent to XrefsTo from idapython on the first instruction.

Returns:A list of BipXref with the dst being this element.
xEaTo

Property which allow to get all addresses which referenced this function (xref to).

Returns:A list of address.
xEltTo

Property which allow to get all elements which referenced this element (xref to).

Returns:A list of BipBaseElt (or subclasses of BipBaseElt).
__weakref__

list of weak references to the object (if defined)

xCodeTo

Property which return all instructions which referenced this element. This will take into account jmp, call, ordinary flow and “data” references.

Returns:A list of BipInstr referenced by this element.
callers

Property which return a list of all the functions which call this function.

This function will not take into account jmp or ordinary flow to this function, see jcallers() property for also getting the jmp and ordinary flow.

Returns:A list of BipFunction which call this function.
jcallers

Property which return a list of all the functions which call, jump or have an ordinary flow to this function.

Returns:A list of BipFunction which call this function.
callees

Property which return a list of the functions which are called by this one.

Internally this function will iterate on all instruction for getting the call xref. This can be quite time consuming.

Returns:A list of BipFunction which are called by this function.
classmethod by_ordinal(ordinal)

Get an BipFunction from its ordinal, there is between 0 and BipFunction.count() function in an IDB.

classmethod iter_all()

Class method allowing to iter on all the functions define in the IDB.

Returns:A generator of BipFunction allowing to iter on all the functions define in the idb.
classmethod entries()

Get the functions which are entry points of the binary.

Returns:A list of BipFunction which are entry points of the binary currently analyzed.
classmethod entries_iter()

Get an generator on the functions which are entry points of the binary. This should be faster than entries() .

Returns:A generator on BipFunction which are entry points of the binary currently analyzed.
classmethod get_by_name(name)

Class method allowing to get a function from its name.

Returns:A BipFunction with the correct name or None if the function was not found.
classmethod get_by_prefix(prefix)

Class method allowing to get all the functions which are named with a particular prefix.

Internally this iterate on all functions.

Parameters:prefix (str) – The prefix for which to get the function.
Returns:A list of BipFunction where their names start with the prefix.
classmethod get_by_regex(regex)

Class method allowing to get all functions matching a regex.

Internally this iterate on all functions and use the re.match function (it compiles the regex first) and return the function if the match did not return None.

Parameters:regex (str) – The regex used for finding the function.
Returns:A list of BipFunction where their names match the regex.
classmethod create(start, end=None)

Class method allowing to create a new function.

Parameters:
  • start (int) – Start address for the function to create.
  • end (int) – Facultative argument which indicate the end address of the function. If is is not provided (None, default value) it will try to create a function using the auto-analysis of IDA.
Returns:

A new BipFunction object corresponding to the function create. If this function was not able to create the new function a BipError will be raised.
static count()

Return the number of functions which are present in the idb.

BipBlock API

class bip.base.BipBlock(val=None)

Class for representing and manipulating basic blocks in IDA.

Warning

This class is an abstraction on top of IDA BadicBlock. In particular IDA does not create basic block if not in a defined function. Change to the flowgraph can be not directly repercuted on this object.

Todo

equality and inclusion operator

Todo

more functions for testing type (abstraction on .type property), property function starting with is_

__init__(val=None)

Constructor for an BipBlock object.

This function may raise a TypeError if the argument is not of a type supported or a ValueError if the address pass in parameter is not inside a function.

Parameters:val – A value used for creating a basic block. This can be an address (int or long) or a ida_gdl.BasicBlock object. If None the screen address is used.
_bb = None

Internal ida_gdl.BasicBlock object representing this block in IDA

ea

Property which return the start address of the function.

Return int:The address of the basicblock.
end

Property which return the end address of the function. This address is not included in the basicblock.

Return int:The first address at the end of the basicblock.
__str__() <==> str(x)
_id

Property returning the ID of the basic block. This is use in particular for manipulating the block using the graph functions.

Return int:The ID of this basic block.
type

Property which allow access to the type of basic block.

Returns:One of the BipBlockType enum.
is_ret

Property which return True if the block can return.

Internally this test the type for BipBlockType.FCB_RET and BipBlockType.FCB_CNDRET. It is the equivalent of ida_gdl.is_ret_block in the standard idapython.

Returns:True if the block return, False otherwise.
is_noret

Property for testing if the block never return. For example this will be True if the block terminate by a call to a function which will never return (abort, …)

Internally this test the type for BipBlockType.FCB_NORET and BipBlockType.FCB_ENORET. It is the equivalent of ida_gdl.is_noret_block in the standard idapython.

Returns:True if the block never return, False otherwise.
is_external

Property for testing if the block is external to the function from which it came.

Internally this test the type for FCB_ENORET and FCB_EXTERN .

Note

This should never be True if this BipBlock was provided by a BipFunction, it can be True if the block provided at the initialization was recuperated from an other source.

Returns:True if the block is not included in the function from which the flowgraph was created, False otherwise.
succ

Return a list of BipBlock which are successor of this block. This follow the potential execution pass.

Returns:A list of BipBlock successor of this block.
succ_iter

Return a generator of the BipBlock following this one. This is equivalent to succ() and will probably be a little faster.

Returns:A generator of BipBlock successor of this block.
pred

Return a list of BipBlock which are predecessor of this block. This provide the basicblock which can lead to this block followin the execution pass.

Returns:A list of BipBlock predecessor of this block.
pred_iter

Return a generator of the BipBlock predecessor of this one. This is equivalent to pred() and will probably be a little faster.

Returns:A generator of BipBlock predecessor of this block.
func

Return the BipFunction object corresponding to this block.

Note

Internally this will return the BipFunction which is present at the start address of the block. In particular in case of external blocks this will return the function in which the block are included and not the one from which they came from.

Returns:The BipFunction in which this block is included.
items

Return a list of BipElt corresponding to the items included in the basic block (between ea and end).

Returns:A list of object BipElt.
instr

Return a list of BipInstr corresponding to the instructions of the basicblock.

Returns:A list of object BipInstr .
instr_iter

Return a generator of BipInstr corresponding to the instructions of the basicblock. This implementation will be just a little more performant than the instr() property.

Returns:A generator of object BipInstr .
__weakref__

list of weak references to the object (if defined)

bytes

Property returning the value of the bytes contain in the basicblock.

Returns:A list of the bytes forming the element.
Return type:list(int)
color

Property for accessing the color of this basic block.

Raises:RuntimeError – If this function was not able to get the information about the graph node.
Return int:The integer representing the color of this block in the BGR format.
class bip.base.BipBlockType

Enum for the type of basic block. This come from the fc_block_type_t enum (gdl.hpp) not exposed to the python API.

FCB_NORMAL = 0

normal block

FCB_INDJUMP = 1

block ends with indirect jump

FCB_RET = 2

return block

FCB_CNDRET = 3

conditional return block

FCB_NORET = 4

noreturn block

FCB_ENORET = 5

external noreturn block (does not belong to the function)

FCB_EXTERN = 6

external normal block

FCB_ERROR = 7

block passes execution past the function end