CNode¶

The CNode API is one of the representation in Bip for the AST nodes of an Hexrays decompiled function. Of the two representations, it is the one which is prefered. The class CNode is an abstract class which is used as parent for the actual classes representing the nodes. For more informations about AST nodes and their different types see Ast Nodes & Visitors.

For recuperating the CNode objects for a particular function several methods of HxCFunc can be used:

the root_node() property for getting the root of the AST for a particular function;
the get_cnode_filter() and get_cnode_filter_type() methods provide list of the nodes in the functions (those are based on the visitors);
the visit_cnode() and visit_cnode_filterlist() methods which allow to visit the AST using a Deep-First Search (DFS) algorithm with preorder-traversal.

For a list of possible node type see AST Node types.

Two internal mechanisms are important to understand the CNode implementation:

all CNode are generated from a citem_t object in IDA, the correct classes is determine depending of the type of the citem_t (HxCType). The from_citem() static method exist for finding the correct child class of CNode corresponding to the citem_t and creating it, as a general rule the constructors should not be called directly.
most of the CNode subclasses are created dynamically from their equivalent HxCItem, this is for avoiding code duplication. For more information see CNode generation and internals.

CNode API¶

class bip.hexrays.CNode(citem, hxcfunc, parent)¶

Abstract class which allow to represent C expression and C statement decompiled from HexRays. This is an equivalent class to HxCItem but is designed for visiting an AST generated by HexRays. The main advantage to use this class and its subclasses and not the HxCItem is the additional features which it provides, such as:

access to the parent node,
access to the parent HxCFunc,
visitor for nodes below the current one,
several node specific methods, listed in Methods specific to CNode implementation.

The parrent class AbstractCItem also provides common functionnality with the HxCItem objects. All subclasses of this class have the same behavior as the one from HxCItem with just some aditional feature.

This is an abstract class and no object of this class should ever be created. The static method from_citem() allow to create object of the correct subclass which inherit from CNode.

__init__(citem, hxcfunc, parent)¶

Constructor for the abstract class CNode . This should never be used directly.

Parameters:	citem – a `citem_t` object, in practice this should always be a `cexpr_t` or a `cinsn_t` object. hxcfunc – A `HxCFunc` object corresponding to the function which contains this node/item. parent – An object which inherit from `CNode` corresponding to the parent expression or statement of this object. This may be `None` if this node is the root of the AST tree for its function.

_hxcfunc = None¶: The function associated with this node. This is a HxCFunc object. This is private and should not be modify. Modifying this attribute will not make any modification to the data stored in IDA.

_parent = None¶: The parent node of this node. This should be an object which inherit from CNode. This may be None if this node is the root node of the AST tree for its function. This is private and should not be modify. Modifying this attribute will not make any modification to the data stored in IDA.

closest_ea¶

Property which return the closest address for this CNode.

By default this should be equivalent to the ea() property except if it return idc.BADADDR, in this case it will try and get the address of the parent. If the most parrent node of this node (which should be the root node of the function) still has no address, None is return.

Returns:	An integer corresponding to the closest address for this node. If no address where found this method will return None.

cstr¶

Property which return the C code corresponding to the decompilation of this CNode as a onliner. This will include the children of this object.

Return str:	The human readable C string corresponding to this `CNode` as a onliner.

has_parent¶: Property which return true if the CNode as a parent. Only CNode which are root of a function should not have a parent.

parent¶

Property which return the parent of this CNode. If this node does not have a parent a RuntimeError exception will be raised.

Returns:	A `CNode` object parent of this node.

hxcfunc¶

Property returning the HxCFunc to which this node is associated.

Returns:	A `HxCFunc` object corresponding to the function associated with this node.

comment¶

Get the comment at the closest address of this node.

Note that two node with the same closest_ea will have the same comment.

Todo

Default ITP will work only for expression, should make another one for statement.

Note

This use the default itp (at the semi-colon level), see HxCFunc.get_cmt().

visit_cnode(callback)¶

Method which allow to visit this CNode elements and all those below it. 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).

Parameters:	callback – A callable which will be called on this and all `CNode` below it. 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 of a type present in a list. Start with the current CNode and look in all its children. 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).

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 below (and including) the current one, 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 children nodes and all nodes 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_filterlist() method which visit all nodes below and including the current one, 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).

ignore_cast¶

Property which return this node if it is not a cast or its child if it is a cast. This is designed for allowing to quickly ignore cast when going through some nodes.

Returns:	The first `CNode` which is not a cast.

ignore_cast_parent¶

Property which return this node if it is not a cast or its parent if it is a cast. This is designed for allowing to quickly ignore cast when going backward through some nodes.

Returns:	The first `CNode` which is not a cast.

_create_child(citem)¶

Internal method which allow to create a CNode object from a citem_t child of the current node. This must be used by CNodeStmt and CNodeExpr for creating their child expression and statement. This method is used for having compatibility with the HxCItem class.

Internally this function is a wrapper on from_citem() which is call with the same function than this object and with this object as parent.

Parameters:	citem – A `citem_t` from ida.
Returns:	The equivalent node object to the `citem_t` for bip. This will be an object which inherit from `CNode` .

static from_citem(citem, hxcfunc, parent)¶

Static method which allow to create an object of the correct child class of CNode which is equivalent to a citem_t from ida. In particular it will be used for converting cexpr_t and cinsn_t from ida to CNodeExpr and CNodeStmt in bip. If no CNode child object exist corresponding to the citem provided a ValueError exception will be raised.

This is the equivalent of HxCItem.from_citem() but for the CNode .

Note

CNodeExpr and CNodeStmt should not used this function for creating child item but CNode._create_child().

Parameters:	citem – A `citem_t` from ida. hxcfunc – A `HxCFunc` object corresponding to the function which contains this node/item. parent – An object which inherit from `CNode` corresponding to the parent expression or statement of this object. This may be `None` if this node is the root of the AST tree for its function.
Returns:	The equivalent object to the `citem_t` for bip. This will be an object which inherit from `HxCItem` .

CNodeExpr API¶

class bip.hexrays.CNodeExpr(cexpr, hxcfunc, parent)¶

Abstract class for representing a C Expression decompiled from HexRays. This is an abstract class which is used as a wrapper on top of the cexpr_t object. This is the equivalent of the HxCExpr class but which inherit from the CNode and is made for visiting an AST.

No object of this class should be instanstiated, for getting an expression the function from_citem() should be used.

Todo

something better could be done here for avoiding code duplication of the HxCExpr class.

__init__(cexpr, hxcfunc, parent)¶

Constructor for the CNodeExpr object. Arguments are used by the CNode constructor.

Parameters:	cexpr – A `cexpr_t` object from ida. hxcfunc – A `HxCFunc` object corresponding to the function which contains this node/item. parent – An object which inherit from `CNode` corresponding to the parent expression or statement of this object. This may be `None` if this node is the root of the AST tree for its function.

_cexpr = None¶: The cexpr_t object from ida.

__str__()¶: Surcharge for printing a CExpr

ops¶

Function which return the C Expressions child of this expression. This is used only when the expression is recursive.

Returns:	A `list` of object inheriting from `CNodeExpr` and child of the current expression.

type¶

Property which return the type (BipType) of this expression.

Returns:	An object which inherit from `BipType` which correspond to the type of this object. Change to this type object will not change the type of this expression.

find_final_left_node()¶: Return the node which is the left most “final” expression (inherit from CNodeExprFinal) below this node. If this node is a final expression it is returned.

find_left_node_notmatching(li)¶

Find the most left node not matching some classes. If the current node does not match any classes in the list provided it will be returned.

This function allow to bypass nodes to ignored. A common utilisation will be to bypass some unary operand for getting a final value or to bypass cast, reference or ptr derefence only. For getting the final node and ingore all other nodes see find_final_left_node(). If a node found is a “final” node (inherit from CNodeExprFinal) it will always be returned.

For example for ignoring cast and ref use: cn.find_left_node_notmatching([CNodeExprCast, CNodeExprRef]) .

Parameters:	li – A `list` or `tuple` of classes which inherit from `CNodeExpr` to ignore.
Returns:	A CNode object which is not of one of the class in `li`.

CNodeStmt API¶

class bip.hexrays.CNodeStmt(cinsn, hxcfunc, parent)¶

Abstract class for representing a C Statement as returned by hexrays. This is an abstract class which is a wrapper on top of the cinsn_t ida object. This is the equivalent of the HxCStmt class but which inherit from the CNode and is made for visiting an AST.

No object of this class should be instanstiated, for getting an expression the function from_citem() should be used.

A statement can contain one or more child statement and one or more child expression (HxCExpr) object. By convention properties which will return child statement of an object will start with the prefix stmt_ or st_.

__init__(cinsn, hxcfunc, parent)¶

Constructor for a CNodeStmt object. Arguments are used by the CNode constructor.

Parameters:	cinsn – A `cinsn_t` from ida. hxcfunc – A `HxCFunc` object corresponding to the function which contains this node/item. parent – An object which inherit from `CNode` corresponding to the parent expression or statement of this object. This may be `None` if this node is the root of the AST tree for its function.

_cinsn = None¶: The cinsn_t object from ida.

__str__()¶: Surcharge for printing a CStmt.

stmt_children¶

Property which return a list of the statements which are children of this statement. This is used only when the statement is recursive, if not this will return an empty list.

Returns:	A list of child statement of this object.
Return type:	Objects which inherit from `CNodeStmt` .

expr_children¶

Property which return a list of the expression (CNodeExpr) which are children of this statement. This will not return children expression of the statement child of the current object.

Returns:	A list of child expression of this object.
Return type:	Objects which inherit from `CNodeExpr` .

Final Expression API¶

class bip.hexrays.CNodeExprFinal(cexpr, hxcfunc, parent)¶

Copy of HxCExprFinal but which inherit from CNode. Automatically created by buildCNode()

__str__()¶: Surcharge for printing a HxCExprFinal.

value¶: Property which return the value of a final expression. This is abstract and if not overwritten it will raise a RuntimeError .

class bip.hexrays.CNodeExprEmpty(cexpr, hxcfunc, parent)¶: Copy of HxCExprEmpty but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprNum(cexpr, hxcfunc, parent)¶

Copy of HxCExprNum but which inherit from CNode. Automatically created by buildCNode()

size¶

Original size in bytes of the number.

Return int:	the size in bytes.

value¶

Value of the number.

Return int:	the value of this number.

class bip.hexrays.CNodeExprFNum(cexpr, hxcfunc, parent)¶

Copy of HxCExprFNum but which inherit from CNode. Automatically created by buildCNode()

size¶

Original size in bytes of the number.

Return int:	the size in bytes.

value¶: Todo

not sure if this works at all and probably not what we want anyway.

class bip.hexrays.CNodeExprStr(cexpr, hxcfunc, parent)¶

Copy of HxCExprStr but which inherit from CNode. Automatically created by buildCNode()

value¶

String value.

Return str:	the value of this string.

class bip.hexrays.CNodeExprObj(cexpr, hxcfunc, parent)¶

Copy of HxCExprObj but which inherit from CNode. Automatically created by buildCNode()

value¶

Address of the object.

Return int:	the address of the object.

class bip.hexrays.CNodeExprVar(cexpr, hxcfunc, parent)¶

Copy of HxCExprVar but which inherit from CNode. Automatically created by buildCNode()

index¶

Index in the lvar array.

Todo

this should probably directly return the lvar ?

Return int:	the index in the lvar array.

lvar¶

Property which allow direct access to the HxLvar object referenced by this node.

This method exist only for the CNode implementation.

Returns:	the `HxLvar` object referenced by this node.

lvar_name¶

Property which allow to get the name of the HxLvar referenced by this node.

This method exist only for the CNode implementation.

Returns:	The name of the lvar as a string.

value¶

Index in the lvar array.

Return int:	the index in the lvar array.

class bip.hexrays.CNodeExprHelper(cexpr, hxcfunc, parent)¶

Copy of HxCExprHelper but which inherit from CNode. Automatically created by buildCNode()

value¶

Value of this helper.

Return str:	the string containing the value of the helper.

class bip.hexrays.CNodeExprInsn(cexpr, hxcfunc, parent)¶: Copy of HxCExprInsn but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprType(cexpr, hxcfunc, parent)¶

Copy of HxCExprType but which inherit from CNode. Automatically created by buildCNode()

value¶: Return the BipType which is represented by this node. This is equivalent to the type() property.

MemAccess Expression API¶

class bip.hexrays.CNodeExprMemAccess(cexpr, hxcfunc, parent)¶

Copy of HxCExprMemAccess but which inherit from CNode. Automatically created by buildCNode()

obj¶

Property which return a HxCExpr representing the base memory location.

Returns:	An operand of the expression, an object which inherit from `HxCExpr` .

off¶

Property which return the offset of the memory location.

Returns:	An object which inherit from `HxCExpr` or an integer.

class bip.hexrays.CNodeExprIdx(cexpr, hxcfunc, parent)¶

Copy of HxCExprIdx but which inherit from CNode. Automatically created by buildCNode()

array¶

Property which return a HxCExpr representing the array element access by this expression.

Returns:	An operand of the expression, an object which inherit from `HxCExpr` .

index¶

Property which return a HxCExpr representing the index of the element access by this expression.

Returns:	An operand of the expression, an object which inherit from `HxCExpr` .

class bip.hexrays.CNodeExprMemref(cexpr, hxcfunc, parent)¶

Copy of HxCExprMemref but which inherit from CNode. Automatically created by buildCNode()

mem¶

Property which return a HxCExpr representing the object which is access by this expression.

Returns:	An operand of the expression, an object which inherit from `HxCExpr` .

off¶

Property which return the memory offset which is access by this expression. In practice this should be an offset in a structure or an enum.

Return int:	The memory offset.

class bip.hexrays.CNodeExprMemptr(cexpr, hxcfunc, parent)¶

Copy of HxCExprMemptr but which inherit from CNode. Automatically created by buildCNode()

access_size¶

Property which return the size which is access by the derefencement of this pointer.

Returns:	An int corresponding to the size acceded.

off¶

Property which return the memory offset which is access by this expression. In practice this should be an offset in a structure or an enum.

Return int:	The memory offset.

ptr¶

Property which return a HxCExpr representing the object which is access by this expression.

Returns:	An operand of the expression, an object which inherit from `HxCExpr` .

Unary Operation Expression API¶

class bip.hexrays.CNodeExprUnaryOperation(cexpr, hxcfunc, parent)¶

Copy of HxCExprUnaryOperation but which inherit from CNode. Automatically created by buildCNode()

operand¶

Property which return the operand of this expression.

Returns:	The operand of the expression, an object which inherit from `HxCExpr` .

class bip.hexrays.CNodeExprPtr(cexpr, hxcfunc, parent)¶

Copy of HxCExprPtr but which inherit from CNode. Automatically created by buildCNode()

access_size¶

Property which return the size which is access by the derefencement of this pointer.

Returns:	An int corresponding to the size acceded.

class bip.hexrays.CNodeExprFneg(cexpr, hxcfunc, parent)¶: Copy of HxCExprFneg but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprNeg(cexpr, hxcfunc, parent)¶: Copy of HxCExprNeg but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprCast(cexpr, hxcfunc, parent)¶

Copy of HxCExprCast but which inherit from CNode. Automatically created by buildCNode()

ignore_cast¶

Property which return the first child expression of this node cast which is not a cast. This is implemented for all CNode for allowing to quickly ignore cast (see ignore_cast()). Multiple chained cast are handle.

Returns:	A `CNodeExpr` which is not a cast.

ignore_cast_parent¶

Property which return the first parent of this node which is not cast This is designed for allowing to quickly ignore cast when going backward through some nodes. Multiple chained cast are handle.

Returns:	The first `CNode` which is not a cast.

class bip.hexrays.CNodeExprLnot(cexpr, hxcfunc, parent)¶: Copy of HxCExprLnot but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprBnot(cexpr, hxcfunc, parent)¶: Copy of HxCExprBnot but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprRef(cexpr, hxcfunc, parent)¶: Copy of HxCExprRef but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprPostinc(cexpr, hxcfunc, parent)¶: Copy of HxCExprPostinc but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprPostdec(cexpr, hxcfunc, parent)¶: Copy of HxCExprPostdec but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprPreinc(cexpr, hxcfunc, parent)¶: Copy of HxCExprPreinc but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprPredec(cexpr, hxcfunc, parent)¶: Copy of HxCExprPredec but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSizeof(cexpr, hxcfunc, parent)¶: Copy of HxCExprSizeof but which inherit from CNode. Automatically created by buildCNode()

Double Operation Expression API¶

class bip.hexrays.CNodeExprDoubleOperation(cexpr, hxcfunc, parent)¶

Copy of HxCExprDoubleOperation but which inherit from CNode. Automatically created by buildCNode()

first_op¶

Property which return the first operand.

Returns:	The first operand of the expression, an object which inherit from `HxCExpr` .

second_op¶

Property which return the second operand.

Returns:	The second operand of the expression, an object which inherit from `HxCExpr` .

class bip.hexrays.CNodeExprComma(cexpr, hxcfunc, parent)¶: Copy of HxCExprComma but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprLor(cexpr, hxcfunc, parent)¶: Copy of HxCExprLor but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprLand(cexpr, hxcfunc, parent)¶: Copy of HxCExprLand but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprBor(cexpr, hxcfunc, parent)¶: Copy of HxCExprBor but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprXor(cexpr, hxcfunc, parent)¶: Copy of HxCExprXor but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprBand(cexpr, hxcfunc, parent)¶: Copy of HxCExprBand but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprEq(cexpr, hxcfunc, parent)¶: Copy of HxCExprEq but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprNe(cexpr, hxcfunc, parent)¶: Copy of HxCExprNe but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSge(cexpr, hxcfunc, parent)¶: Copy of HxCExprSge but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUge(cexpr, hxcfunc, parent)¶: Copy of HxCExprUge but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSle(cexpr, hxcfunc, parent)¶: Copy of HxCExprSle but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUle(cexpr, hxcfunc, parent)¶: Copy of HxCExprUle but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSgt(cexpr, hxcfunc, parent)¶: Copy of HxCExprSgt but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUgt(cexpr, hxcfunc, parent)¶: Copy of HxCExprUgt but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSlt(cexpr, hxcfunc, parent)¶: Copy of HxCExprSlt but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUlt(cexpr, hxcfunc, parent)¶: Copy of HxCExprUlt but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSshr(cexpr, hxcfunc, parent)¶: Copy of HxCExprSshr but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUshr(cexpr, hxcfunc, parent)¶: Copy of HxCExprUshr but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprShl(cexpr, hxcfunc, parent)¶: Copy of HxCExprShl but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAdd(cexpr, hxcfunc, parent)¶: Copy of HxCExprAdd but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSub(cexpr, hxcfunc, parent)¶: Copy of HxCExprSub but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprMul(cexpr, hxcfunc, parent)¶: Copy of HxCExprMul but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSdiv(cexpr, hxcfunc, parent)¶: Copy of HxCExprSdiv but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUdiv(cexpr, hxcfunc, parent)¶: Copy of HxCExprUdiv but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprSmod(cexpr, hxcfunc, parent)¶: Copy of HxCExprSmod but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprUmod(cexpr, hxcfunc, parent)¶: Copy of HxCExprUmod but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprFadd(cexpr, hxcfunc, parent)¶: Copy of HxCExprFadd but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprFsub(cexpr, hxcfunc, parent)¶: Copy of HxCExprFsub but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprFmul(cexpr, hxcfunc, parent)¶: Copy of HxCExprFmul but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprFdiv(cexpr, hxcfunc, parent)¶: Copy of HxCExprFdiv but which inherit from CNode. Automatically created by buildCNode()

Assignment¶

class bip.hexrays.CNodeExprAssignment(cexpr, hxcfunc, parent)¶

Copy of HxCExprAssignment but which inherit from CNode. Automatically created by buildCNode()

dst¶

Helper property which return the destination of the assignment.

This is just a wrapper on top of first_op().

Returns:	The first operand of the expression, an object which inherit from `HxCExpr` .

src¶

Helper property which return the source of the assignment.

This is just a wrapper on top of second_op().

Returns:	The second operand of the expression, an object which inherit from `HxCExpr` .

class bip.hexrays.CNodeExprAsg(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsg but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgbor(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgbor but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgxor(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgxor but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgband(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgband but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgadd(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgadd but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgsub(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgsub but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgmul(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgmul but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgsshr(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgsshr but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgushr(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgushr but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgshl(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgshl but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgsdiv(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgsdiv but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgudiv(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgudiv but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgsmod(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgsmod but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeExprAsgumod(cexpr, hxcfunc, parent)¶: Copy of HxCExprAsgumod but which inherit from CNode. Automatically created by buildCNode()

Other leaf Expressions API¶

class bip.hexrays.CNodeExprTernary(cexpr, hxcfunc, parent)¶

Copy of HxCExprTernary but which inherit from CNode. Automatically created by buildCNode()

cond¶

Property which return the condition of the ternary expression.

Returns:	An object which inherit from `HxCExpr` .

expr1¶

Property which return the first expression of the ternary expression: the one executed if the condition cond() is true.

Returns:	An object which inherit from `HxCExpr` .

expr2¶

Property which return the second expression of the ternary expression: the one executed if the condition cond() is false.

Returns:	An object which inherit from `HxCExpr` .

class bip.hexrays.CNodeExprCall(cexpr, hxcfunc, parent)¶

Copy of HxCExprCall but which inherit from CNode. Automatically created by buildCNode()

_carglist¶: Property which return the carglist_t from IDA.

_get_carg(num)¶: Internal function which give access to the argument at position number num. There is no check on the value of num.

args¶

Property which return the args of the call. Those args are also expressions.

Returns:	A list of `HxCExpr` .

args_iter¶: Property which return an iterator on the args of the call. This is similar to args() but with an iterator, and should have more perf.

caller¶

Property which return the caller of this expression. The caller is also an expression.

Returns:	An object which inherit from `HxCExpr` .

caller_addr¶

Property which return the address called by this CNodeExprCall if it exist.

This property ignore the cast.

Returns:	An integer corresponding to the address called or `None` if the caller is not a `CNodeExprObj` node.

caller_func¶

Property which return the BipFunction called by this CNodeExprCall if it exist.

This property ignore the cast and works only for function in the binary. If this function is not able to create the BipFunction None will be returned (in particular this will not work for the imported function).

Returns:	The `BipFunction` called by this node or None if it was not able to get it.

get_arg(num)¶

Function which return one of the argument of the call to a function. Each argument is also an expression.

Parameters:	num (int) – The argument number.
Raises:	ValueError – if `num` is superior to the number of arguments in the call expression.
Returns:	An object which inherit from `HxCExpr` .

get_arg_intval(argnum)¶

Method for getting the integer value used for an argument at a given position. This allows to quickly get the value of an argument which is an address (CNodeExprObj) or an integer (CNodeExprNum), this function will return None for all other case.

This property ignore the cast.

Parameters:	argnum (int) – The argument number for which to get the value.
Raises:	ValueError – If argument at position `argnum` does not exist.
Returns:	The number or address passed in that argument or None if a number could not be found.

is_helper¶

Property which return true if this function is a decompiler helper function.

Returns:	A bool indicating if this is a helper function (true) or a “real” call.

number_args¶

Property which return the number of arguments pass to the call expresion.

Return int:	The number of argument to the call expression.

type_call¶

Return the type for the function call. This will be the type printed by HexRays for the function. It differs from type() which is the type of result of the node.

Todo

setter

Returns:	An object which inherit from `BipType` which correspond to the call type of this node.

Final Statement API¶

class bip.hexrays.CNodeStmtFinal(cinsn, hxcfunc, parent)¶

Copy of HxCStmtFinal but which inherit from CNode. Automatically created by buildCNode()

__str__()¶: Surcharge for printing a HxCExprFinal.

value¶: Property which return the value of a final expression. This is abstract and if not overwritten it will raise a RuntimeError .

class bip.hexrays.CNodeStmtEmpty(cinsn, hxcfunc, parent)¶: Copy of HxCStmtEmpty but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeStmtExpr(cinsn, hxcfunc, parent)¶

Copy of HxCStmtExpr but which inherit from CNode. Automatically created by buildCNode()

expr¶

Property which return the expression contain in this statement.

Returns:	A child object of `HxCExpr` which represent the expression contain in this statement.

value¶

The expression contain in this statement.

Returns:	A child object of `HxCExpr` which represent the expression contain in this statement.

class bip.hexrays.CNodeStmtGoto(cinsn, hxcfunc, parent)¶

Copy of HxCStmtGoto but which inherit from CNode. Automatically created by buildCNode()

cnode_dst¶: Property which return the CNode which is the destination of the goto. This is not a child node, but a link to on other part of the AST.

label¶

Property which return the label number of the goto statement.

Returns:	An integer representing the label number.

value¶: Return the label number see label() .

class bip.hexrays.CNodeStmtAsm(cinsn, hxcfunc, parent)¶

Copy of HxCStmtAsm but which inherit from CNode. Automatically created by buildCNode()

__len__()¶: Return the number of instruction in this ASM statement. Same as length()

addr_instr¶

Property which return a list of address corresponding to the ASM instruction which are inline.

Returns:	A list of address (integer) representing the address of the inline assembly instruction in the binary.

length¶: Property which return the number of instruction in this ASM statement.

value¶

Return a list of BipInstr corresponding to the ASM instructions in this ASM statement.

Returns:	A list of `BipInstr`.

class bip.hexrays.CNodeStmtReturn(cinsn, hxcfunc, parent)¶

Copy of HxCStmtReturn but which inherit from CNode. Automatically created by buildCNode()

ret_val¶

Property which return the expression which is the value return by this return statement.

Returns:	An object which inherits from `HxCExpr` .

value¶: Return the HxCExpr which is return by this statement. See ret_val() .

Loop Statement API¶

class bip.hexrays.CNodeStmtLoop(cinsn, hxcfunc, parent)¶

Copy of HxCStmtLoop but which inherit from CNode. Automatically created by buildCNode()

cond¶

Property which return the expression used as a condition for the loop.

Returns:	An object which inherits from `HxCExpr` .

st_body¶

Property which return the statement used as a body for the loop.

Returns:	An object which inherits from `HxCStmt` .

class bip.hexrays.CNodeStmtFor(cinsn, hxcfunc, parent)¶

Copy of HxCStmtFor but which inherit from CNode. Automatically created by buildCNode()

cond¶

Property which return the expression used as a condition for the for.

Returns:	An object which inherits from `HxCExpr` .

init¶

Property which return the expression for the initialization of the for loop.

Returns:	An object which inherits from `HxCExpr` .

st_body¶

Property which return the statement used as a body for the for.

Returns:	An object which inherits from `HxCStmt` .

step¶

Property which return the expression for the step of the for loop.

Returns:	An object which inherits from `HxCExpr` .

class bip.hexrays.CNodeStmtWhile(cinsn, hxcfunc, parent)¶

Copy of HxCStmtWhile but which inherit from CNode. Automatically created by buildCNode()

cond¶

Property which return the expression used as a condition for the while.

Returns:	An object which inherits from `HxCExpr` .

st_body¶

Property which return the statement used as a body for the while.

Returns:	An object which inherits from `HxCStmt` .

class bip.hexrays.CNodeStmtDoWhile(cinsn, hxcfunc, parent)¶

Copy of HxCStmtDoWhile but which inherit from CNode. Automatically created by buildCNode()

cond¶

Property which return the expression used as a condition for the do-while.

Returns:	An object which inherits from `HxCExpr` .

st_body¶

Property which return the statement used as a body for the do-while.

Returns:	An object which inherits from `HxCStmt` .

Other leaf Statement API¶

class bip.hexrays.CNodeStmtIf(cinsn, hxcfunc, parent)¶

Copy of HxCStmtIf but which inherit from CNode. Automatically created by buildCNode()

cond¶

Property which return the expression used as a condition for the if.

Returns:	An object which inherits from `HxCExpr` .

has_else¶

Property which indicate if this if statement as an else condtion.

Returns:	True if this statement has an else condition, False otherwise.

st_else¶

Property which return the executed if the condition (cond()) is False.

This property will return None if this condition has no else statement. This can be tested by checking has_else() .

Returns:	An object which inherits from `HxCStmt` .

st_then¶

Property which return the statement executed if the condition (cond()) is true.

Returns:	An object which inherits from `HxCStmt` .

class bip.hexrays.CNodeStmtSwitch(cinsn, hxcfunc, parent)¶

Copy of HxCStmtSwitch but which inherit from CNode. Automatically created by buildCNode()

cases_val¶

Property which return the list of values for each statement. This list is in the same order as the list of statement return by st_cases() .

As each case can have several values for triggering it, this property return a list of list of values.

Returns:	A list of lists of values (int), each list correspond to a different case and contain the values which will make the code enter this path. An empty list means it the default case.

expr¶

Property which return the expression used as the switch expression.

Returns:	An object which inherits from `HxCExpr` .

max_val¶

Property which return the case maximum value for the switch.

Returns:	An integer which is the maximum case value for the switch.

st_cases¶

Property which return the statement used in the different cases.

Returns:	A list of statements representing the different possible cases of this switch.
Return type:	Objects which inherit from `HxCStmt` .

class bip.hexrays.CNodeStmtContinue(cinsn, hxcfunc, parent)¶: Copy of HxCStmtContinue but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeStmtBreak(cinsn, hxcfunc, parent)¶: Copy of HxCStmtBreak but which inherit from CNode. Automatically created by buildCNode()

class bip.hexrays.CNodeStmtBlock(cinsn, hxcfunc, parent)¶

Copy of HxCStmtBlock but which inherit from CNode. Automatically created by buildCNode()

elts¶

Property which return the list of child statement included in this block.

Returns:	The list of child statement of this block.
Return type:	Objects which inherit from `HxCStmt` .

Methods specific to CNode implementation¶

This list the methods which exist only in the implementation of the CNode and not in the HxCItem. Those methods are documented correctly in their respective class, they are listed here only as an easy way to see functionnality which are CNode specific. Access to parent HxCFunc and parent node are not listed here.

Classes	Methods
`CNodeExprVar`	`lvar()`
`CNodeExprVar`	`lvar_name()`
`CNodeExprCast`	`ignore_cast()`
`CNodeExprCast`	`ignore_cast_parent()`
`CNodeStmtGoto`	`cnode_dst()`
`CNodeExprCall`	`caller_addr()`
`CNodeExprCall`	`caller_func()`
`CNodeExprCall`	`get_arg_intval()`

Internal Hexrays Visitor API¶

bip.hexrays.cnode_visitor.visit_dfs_cnode(cnode, callback)¶

Basic visitor for a CNode: this will allow to call a callback on every node under the current one (and including the current node) in the AST. This method does not used the visitor from hexrays (ctree_visitor_t). The callback will receive a CNode in argument.

This visitor implements a Deep-First Search (DFS) algorithm which will always visit first the CNodeExpr and then the CNodeStmt. The callback is called before visiting deeper. For an object which inherit from CNodeExpr the child nodes will be called in the same order than returned by ops(); for an object which inherit from CNodeStmt the child nodes will be called in the same order than returned by expr_children() (expression) follow by the nodes in the same order as stmt_children() (statements).

If the callback return False the visitor will stop. Every other result is ignore.

Note

This function will not visit a statement which is under a CNodeExprInsn . Those should not be present in the last stage of a ctree and so this should not be a problem.

An exception raised by the callback will interupt the visitor.

Parameters:	cnode – An object which inherit from `CNode`. This object and all its child will be visited. callback – A callable taking one argument which will be called on all the `CNode` visited with the `CNode` as argument. If it returns False the visitor stops.

bip.hexrays.cnode_visitor.visit_dfs_cnode_filterlist(cnode, callback, filter_list)¶

Visitor for CNode with filtering. This function is the same than visit_dfs_cnode() but allow to use the callback only on CNode which are in a list (white listing of the node to visit).

For information about the visitor implementation see visit_dfs_cnode() . If the filter_list parameter contain only statement (CNodeStmt) the expression will not be visited at all, this should allow a little performance gain.

If the callback return False the visitor will stop. Every other result is ignore.

Parameters:

cnode – An object which inherit from CNode. This object and all its child will be visited.
callback – A callable taking one argument which will be called on all the CNode visited with the CNode as argument.
filter_list – A list or tuple of class or a class which inherit from CNode. The callback will be called only for the node from a class in this list. If it returns False the visitor stops.

CNode generation and internals¶

This description explains how the CNode subclasses are created and is mainly destined to developers and maintainers of Bip.

For avoiding code duplication most classes which inherit from CNode are created dynamically from their equivalent HxCItem (the direct wrapper on the IDA implementation). The classes for both representation will have mainly the same attributes and the same method. When generating the CNode subclasses the names for the classes are generated by replacing the HxC prefix by the CNode prefix, for example HxCExprAdd will become CNodeExprAdd.

Three classes are not generated dynamically. The CNode class (equivalent to HxCItem) which contains the added method and attributes which are specific to this implementation, this is the main based abstract class for all of this implementation. Both CNode and HxCItem inherit from the AbstractCItem abstract class which contains most of the code common to those two classes. The CNodeExpr (equivalent to HxCExpr) and CNodeStmt (equivalent to HxCStmt) classes are not generated dynamically mainly because their constructors must be changed.

Note

It is possible that the CNodeExpr and CNodeStmt will be generated dynamically in the future.

All other subclasses of CNode are created dynamically using the buildCNode() class decorator. This decorator is used on all the HxCItem subclasses and for each class it is used on it will create the equivalent CNode subclasses. For doing that the following steps are taken:

recreating the architecture of inheritance for the new class,
performing a copy of the attributes of the base class and modifying the __doc__ and __module__,
creating the name for the new class (replace HxC by CNode prefix),
adding methods which are specific to the CNode version of the implementation if any,
creating the actual new class,
registering the new class in the corresponding module globals (bip.hexrays.cnode accessible for a user directly from bip.hexrays or from bip) for being able to access it later on,
registering the new class for being able to create the equivalent when rebuilding the inheritance.

For being able to rebuild the inheritance of the class it is necessary to keep an equivalence between the HxCItem subclasses and the CNode ones. This equivalence is stored in the _citem2cnode global dictionary and updated each time a new class is created by the bip.hexrays.cnode.buildCNode() decorator (first and last step of the previous algorithm).

Note

The system of using bip.hexrays.cnode.buildCNode() as a decorator may be changed in the future as a metaclass is probably more appropriate for this.

For being able to add new methods to a CNode subclass, another decorator exists: addCNodeMethod(). This decorator take in argument a string representing the name of the CNode subclasses the method should be added and an optional second argument which allow to specify a different name for the class method than the one the function decorated has. This decorator will simply add the method in the _cnodeMethods global array which will then be used by the buildCNode() decorator for adding the methods and properties at the class creation. Because of the way this work it is necessary for all specific methods to be created before the actual class creation. Presently, because the number of specific methods is quite small, those methods are directly at the end of the cnode.py file.

Internal generation API¶

Those functions are not currently exported by Bip, and are documented for internal use only:

bip.hexrays.cnode.buildCNode(cls)¶

Class decorator for automatically building a class equivalent to the one pass in argument but which inherit from CNode instead of HxCItem .

Internally this will:

find the equivalent of the base classes by looking in _citem2cnode .
create a class identicall to the one in arguments but with name change for being prefix by CNode instead of HxC. Attributes of the class are copied into the new class.
set the new class created as global to this module (the cnode one, not the one it was used in).

bip.hexrays.cnode.addCNodeMethod(cnode_name, func_name=None)¶

Decorator for a function, allow to add a method to a CNode class. This is for supporting to add method specific to a CNode which are not implemented (probably because it is not possible to do so) in their equivalent HxCItem class. This is design to be used in conjonction with the buildCNode() decorator, methods which are added this way should be done before calling it. If the method already exist it will be overwrite by this implementation, this allow to redefine base methods from the HxCExpr. Internally this use the _cnodeMethods global dictionary.

It is possible to add properties using this method, if no func_name parameter is provided the name of the getter will be taken (and so the property must have a getter name). It is possible to use property as a decorator but this will work only for getter:

@addCNodeMethod(myclassname)
@property #order of those decorator is important
def my_new_property(self):
    """
        Documentation will be correctly seen when generating
        the doc.
    """
    pass # THE CODE

Todo

correctly handle all property decorators

Warning

All methods/properties decorated by this functions should be defined before the creation of the corresponding CNode! Currently the simplest way to do this is by adding it at the end of the cnode.py files.

Parameters:	cnode_name (str) – The name of the CNode class to which add the property. func_name (str) – The name to use for adding to the CNode class, if None the name of the function will be used.

bip.hexrays.cnode._cnodeMethods¶

Dictionary which allows to add method to a particular CNode implementation. This is used by addCNodeMethod() for adding a method in a CNode class which does not exist (is not possible to implement) in the HxCItem class equivalent. When the object is created by buildCNode the method will be added.

This dictionary as the name of the class for key, and a parameter a list of tuples. Each tuple consist of the name of the method as first element follow by the function object.

bip.hexrays.cnode._citem2cnode¶: Dictionary which contain an equivalence between the class which inherit from HxCItem and the one which inherit from CNode. This is used for automatically constructing the classes which inherit from CNode dynamically and should not be modified by hand. It is initialized with the 3 base classes which have a constructor.

CNode¶

CNode API¶

CNodeExpr API¶

CNodeStmt API¶

Final Expression API¶

MemAccess Expression API¶

Unary Operation Expression API¶

Double Operation Expression API¶

Assignment¶

Other leaf Expressions API¶

Final Statement API¶

Loop Statement API¶

Other leaf Statement API¶

Methods specific to CNode implementation¶

Internal Hexrays Visitor API¶

CNode generation and internals¶

Internal generation API¶

Table of Contents

Previous topic

Next topic

This Page