Hexrays Functions

Hexrays function are implemented in Bip by the class HxCFunc. They represent a C function as decompiled by hexrays and are the main interface for using the features from hexrays in C.

There are two ways to get a HxCFunc object using the Bip API, the first one is by using the hxcfunc() property method from a BipFunction, this property returns the equivalent HxCFunc for the BipFunction. The second way is to use the class method from_addr() which take an address in argument and try to create the corresponding HxCFunc. Both of those methods may fail if Hexrays is not able to decompile the function or if the address given is not part of a function, in that case an exception BipDecompileError is raised by Bip.

The HxCFunc allows to recuperate the C string of the decompiled function (cstr()), to get the “normal” BipFunction (bfunc()) and provide to two main features: local variables (lvar) and AST nodes.

Local variables (lvar) are represented by HxLvar objects and are accessible through several methods. The simplest way is to use the lvars() property which return an array of the variable. As those variables also include the arguments of the functions the args() property allows to get only the HxLvar which are arguments.

The AST nodes of the HxCFunc can be accessed in different ways. Bip provides CNode classes (CNode is the parent class for all nodes) which represents a node of the AST, those are already a second level of abstraction on top of the hexrays AST node. There are three main ways to access the CNode for a particular function:

It is also possible to use the visitor on the first level of abstraction on top of the hexrays node, those methods start with the prefix hx_visit_.

HxCFunc API

class bip.hexrays.HxCFunc(cfunc)

Python object for representing a C function as decompile by hexrays. This is an abstraction on top of the ida_hexrays.cfuncptr_t and cfunc_t object.

Warning

Decompiling again the function in hexrays (meaning hitting F5 again) will create a new cfunc_t object. An HxCFunc python object (or the corresponding cfunc_t object from IDA) and the others associated objects (such as the HxLvar for example) will not be the same anymore. This can create problems when using the scripting and the interactive view at the same time. Basically you will want to regenerate this object for the function each time you make F5 again in the GUI, this can be done using the HxCFunc.from_addr() class method.

__init__(cfunc)

Constructor for a HxCFunc object.

Parameters:cfunc – A cfunc_t pointer from IDA object such as return by ida_hexrays.decompile .
ea

Property which return the start address of this function.

Return int:The start address of this function
cstr

Property which return the C code corresponding to the decompilation of this function.

Return str:The string corresponding to the decompilation of this function.
bfunc

Property which return the BipFunction associated with this cfunc.

Returns:The BipFunction associated with this object.
invalidate_cache(close_window=False)

Allows to invalidate the cache for this hexray function. This will remove information associated with this function, forcing IDA to regenerate the view for the function next time it will be open.

Warning

This function may generate the same problem as decompiling again the function, this has not been tested. See HxCFunc warning for more information about this potential problem.

Parameters:close_window – If true the window(s) showing the disassembled function will be closed. False by default.
add_cmt(ea, value, itp=None)

Allow to add a comment in the hexrays interface view. If a comment at the same position (ea and itp) exist it will be overwritten.

Parameters:
  • ea (int) – The address at which add the comment. All ea address in the function will not be valid, only the one used for items in the ctree seems to be.
  • value (str) – The comment value.
  • itp (int) – The position at which add the comment. See item_tree_position in IDA, by default (None) at the semi-colon
get_cmt(ea, itp=None)

Allow to get a comment in the hexrays interface view.

Parameters:
  • ea (int) – The address at which is the comment.
  • itp (int) – The position at which the comment is. See item_tree_position in IDA, by default (None) at the semi-colon.
Returns:

None if no comment at that position, the comment as a string if there is any
lvar_at(idx)

Return the local variable corresponding to an index.

This equivalent to using lvars() with access in an index but should be faster.

Returns:A HxLvar object.
lvars

Return a list of HxLvar object representing the local variables of this function. This function will return the argument as well as the local variable of the function.

Returns:A list of HxLvar.
lvars_iter()

Return an iterator of HxLvar object representing the local variables of this function. This is similar to lvars() but with an iterator instead of a list.

Returns:An interator of HxLvar.
lvar_by_name(name)

Return a lvar with a particular name in this function.

Parameters:name (str) – The name of the lvar to search for.
Returns:A HxLvar object or None if the lvar was not found.
args

Return a list of HxLvar object representing the argument of this functions.

Todo

test

Returns:A list of HxLvar.
root_node

Property which return the CNode object which is the root element for this function. This CNode will allow to visit the AST of the function. In practice it should always be of class CNodeStmtBlock .

Returns:The root object for this function which inherit from CNode .
visit_cnode(callback)

Method which allow to visit all CNode elements of this function starting from the root object. This is implemented using a DFS algorithm. This does not use the hexrays visitor. For more information about the implementation see visit_dfs_cnode() (this method is just a wrapper on visit_cnode()).

Parameters:callback – A callable which will be called on all CNode in the function decompiled by hexrays. The call should take only one argument which correspond to the CNode currently visited. If this callback return False the visit is stoped, all other result is ignored.
visit_cnode_filterlist(callback, filter_list)

Method which allow to visit CNode elements which are present in a list. This is implemented using a DFS algorithm. This does not use the hexrays visitor. For more information about the implementation see visit_dfs_cnode_filterlist() (this method is just a wrapper on visit_cnode_filterlist()).

Parameters:
  • callback – A callable which will be called on all CNode in the function decompiled by hexrays. The call should take only one argument which correspond to the CNode currently visited. If this callback return False the visit is stoped, all other result is ignored.
  • filter_list – A list of class which inherit from CNode. The callback will be called only for the node from a class in this list.
get_cnode_filter(cb_filter)

Method which return a list of CNode for which a filter return true. Internally this use the visit_cnode() method which visit all nodes of the function, this is just a wrapper.

Parameters:cb_filter – A callable which take a CNode in parameter and return a boolean. This callback will be called on all node of the function and all node for which it returns true will be added in a list which will be returned by this function.
Returns:A list of CNode which have match the filter. This list is order in which the node have been visited (see visit_cnode() for more information).
get_cnode_filter_type(type_filter)

Method which return a list of CNode of a particular type(s). Internally this use the visit_cnode() method which visit all nodes of the function, this is just a wrapper.

Parameters:type_filter – The type(s) of CNode to get. Only CNode matching the isinstance of this type will be returned. This can be a type, a class or a tuple (or list) of class and type.
Returns:A list of CNode which have match the type. This list is order in which the node have been visited (see visit_cnode() for more information).
get_cnode_label(label_num)

Method which return the CNode which represents the start of a specific label in the function.

Parameters:label_num (int) – The label number for which to get the CNode.
Returns:A CNode which represent label location, or None if the label number was not found.
cnodes_with_label

Property which return a list of CNode which represent the start of the labels in the function.

It is necessary to visit all the AST for doing this, so it is costly.

Returns:A list of CNode which have a label.
hx_root_stmt

Property which return the HxCItem object for the root element of this function. In practice this should always be a HxCStmtBlock.

For the CNode equivalent, see root_node().

Returns:The root object for this function which inherit from HxCItem.
hx_visit_expr(func_visit)

Allow to use the hexrays visitor for visiting all expressions (HxCExpr) of this function.

Internally this function use the _hx_visitor_expr visitor.

Parameters:func_visit – A function which take as argument an HxCExpr object. This function will be called on all HxCExpr element which are part of this function.
hx_visit_list_expr(expr_list, func_visit)

Allow to use the hexrays visitor for visiting only expressions (HxCExpr) which are part of a list.

# example which print all the HxCExprCall from the function
# hxf is an object of this class HxCFunc.
def fu(e):
    print(e)

hxf.visit_list_expr([HxCExprCall], fu)

Internally this function use the _hx_visitor_list_expr visitor.

Parameters:
  • expr_list – A list of class which inherit from HxCExpr, only expression in the list will be visited.
  • func_visit – A function which take as argument an HxCExpr object. This function will be called on all element which are in the expr_list .
hx_visit_stmt(func_visit)

Allow to use the hexrays visitor for visiting all statements (HxCStmt) of this function.

Internally this function use the _hx_visitor_stmt visitor.

Parameters:func_visit – A function which take as argument an HxCStmt object. This function will be called on all HxCStmt element which are part of this function.
hx_visit_list_stmt(stmt_list, func_visit)

Allow to use the hexrays visitor for visiting only statements (HxCStmt) which are part of a list.

Internally this function use the _hx_visitor_list_stmt visitor.

Parameters:
  • stmt_list – A list of class which inherit from HxCStmt, only statements in the list will be visited.
  • func_visit – A function which take as argument an HxCStmt object. This function will be called on all element which are in the stmt_list .
hx_visit_all(func_visit)

Allow to use the hexrays visitor for visiting all items (statements HxCStmt and expression HxCExpr) of this function.

Internally this function use the _hx_visitor_all visitor.

Parameters:func_visit – A function which take as argument an object which inherit from HxCItem. This function will be called on all those elements which are part of this function.
hx_visit_list_all(item_list, func_visit)

Allow to use the hexrays visitor for visiting only statements (HxCStmt) which are part of a list. Allow to use the hexrays visitor for visiting only items (statements HxCStmt and expression HxCExpr) which are part of a list.

Internally this function use the _hx_visitor_list_all visitor.

Parameters:
  • item_list – A list of class which inherit from HxCItem, only items in the list will be visited.
  • func_visit – A function which take as argument an HxCItem object. This function will be called on all element which are in the item_list .
hx_get_label(label_num)

Allow to use the the hexrays API for finding the HxCItem which is reference by a label.

Parameters:label_num (int) – The label number.
Returns:A HxCItem object or None if the label was not found.
classmethod from_addr(ea=None)

Class method which return a HxCFunc object corresponding to the function at a particular address.

This may raise a BipDecompileError if the decompilation failed or if the address provided is not in a function.

Parameters:ea (int) – An address inside the function for which we want an HxCFunc. If None the screen address will be used.
Returns:A HxCFunc object.
static invalidate_all_caches()

Static method for invalidating cache of all hexrays decompiled functions. See invalidate_cache() for invalidating the cache of a specific function.

Warning

This function may generate the same problem as decompiling again a function. See HxCFunc warning for more information about this potential problem.