ida_expr Namespace Reference

Detailed Description

Functions that deal with C-like expressions and built-in IDC language.

Functions marked THREAD_SAFE may be called from any thread. No simultaneous calls should be made for the same variable. We protect only global structures, individual variables must be protected manually. 

Classes
class	_IdcFunction
class	highlighter_cbs_t
class	idc_global_t
class	idc_value_t
class	idc_values_t

Functions
str	compile_idc_file (str nonnul_line)
str	compile_idc_text (str nonnul_line)
'size_t'	py_get_call_idc_func ()
'size_t'	pyw_register_idc_func (str name, str args, 'PyObject *' py_fp)
bool	pyw_unregister_idc_func ('size_t' ctxptr)
bool	pyw_convert_defvals ('idc_values_t' out, 'PyObject *' py_seq)
bool	py_add_idc_func (str name, 'size_t' fp_ptr, str args, 'idc_values_t' defvals, int flags)
str	eval_expr ('idc_value_t' rv, ida_idaapi.ea_t where, str line)
str	eval_idc_expr ('idc_value_t' rv, ida_idaapi.ea_t where, str line)
'error_t'	idcv_long ('idc_value_t' v)
'error_t'	idcv_int64 ('idc_value_t' v)
'error_t'	idcv_num ('idc_value_t' v)
'error_t'	idcv_string ('idc_value_t' v)
'error_t'	idcv_float ('idc_value_t' v)
'error_t'	idcv_object ('idc_value_t' v, 'idc_class_t const *' icls=None)
'error_t'	move_idcv ('idc_value_t' dst, 'idc_value_t' src)
'error_t'	copy_idcv ('idc_value_t' dst, 'idc_value_t' src)
'error_t'	deep_copy_idcv ('idc_value_t' dst, 'idc_value_t' src)
None	free_idcv ('idc_value_t' v)
None	swap_idcvs ('idc_value_t' v1, 'idc_value_t' v2)
str	get_idcv_class_name ('idc_value_t' obj)
'error_t'	get_idcv_attr ('idc_value_t' res, 'idc_value_t' obj, str attr, bool may_use_getattr=False)
'error_t'	set_idcv_attr ('idc_value_t' obj, str attr, 'idc_value_t' value, bool may_use_setattr=False)
'error_t'	del_idcv_attr ('idc_value_t' obj, str attr)
str	first_idcv_attr ('idc_value_t' obj)
str	last_idcv_attr ('idc_value_t' obj)
str	next_idcv_attr ('idc_value_t' obj, str attr)
str	prev_idcv_attr ('idc_value_t' obj, str attr)
str	print_idcv ('idc_value_t' v, str name=None, int indent=0)
'error_t'	get_idcv_slice ('idc_value_t' res, 'idc_value_t' v, int i1, int i2, int flags=0)
'error_t'	set_idcv_slice ('idc_value_t' v, int i1, int i2, 'idc_value_t' _in, int flags=0)
'idc_class_t *'	add_idc_class (str name, 'idc_class_t const *' super=None)
'idc_class_t *'	find_idc_class (str name)
'idc_value_t *'	deref_idcv ('idc_value_t' v, int vref_flags)
bool	create_idcv_ref ('idc_value_t' ref, 'idc_value_t' v)
'idc_value_t *'	add_idc_gvar (str name)
'idc_value_t *'	find_idc_gvar (str name)
str	find_idc_func (str prefix, int n=0)
bool	set_header_path (str path, bool add)
str	get_idc_filename (str file)
bool	exec_system_script (str file, bool complain_if_no_file=True)
str	compile_idc_snippet (str func, str text, 'idc_resolver_t *' resolver=None, bool only_safe_funcs=False)
str	exec_idc_script ('idc_value_t' result, str path, str func, 'idc_value_t' args, 'size_t' argsnum)
'error_t'	throw_idc_exception ('idc_value_t' r, str desc)
	del_idc_func (name)
	add_idc_func (name, fp, args, defvals=(), flags=0)

Variables
	IDC_LANG_EXT = _ida_expr.IDC_LANG_EXT
	VARSLICE_SINGLE = _ida_expr.VARSLICE_SINGLE
	VREF_LOOP = _ida_expr.VREF_LOOP
	VREF_ONCE = _ida_expr.VREF_ONCE
	VREF_COPY = _ida_expr.VREF_COPY
	VT_LONG = _ida_expr.VT_LONG
	VT_FLOAT = _ida_expr.VT_FLOAT
	VT_WILD = _ida_expr.VT_WILD
	VT_OBJ = _ida_expr.VT_OBJ
	VT_FUNC = _ida_expr.VT_FUNC
	VT_STR = _ida_expr.VT_STR
	VT_PVOID = _ida_expr.VT_PVOID
	VT_INT64 = _ida_expr.VT_INT64
	VT_REF = _ida_expr.VT_REF
	eExecThrow = _ida_expr.eExecThrow
	HF_DEFAULT = _ida_expr.HF_DEFAULT
	HF_KEYWORD1 = _ida_expr.HF_KEYWORD1
	HF_KEYWORD2 = _ida_expr.HF_KEYWORD2
	HF_KEYWORD3 = _ida_expr.HF_KEYWORD3
	HF_STRING = _ida_expr.HF_STRING
	HF_COMMENT = _ida_expr.HF_COMMENT
	HF_PREPROC = _ida_expr.HF_PREPROC
	HF_NUMBER = _ida_expr.HF_NUMBER
	HF_USER1 = _ida_expr.HF_USER1
	HF_USER2 = _ida_expr.HF_USER2
	HF_USER3 = _ida_expr.HF_USER3
	HF_USER4 = _ida_expr.HF_USER4
	HF_MAX = _ida_expr.HF_MAX
	CPL_DEL_MACROS = _ida_expr.CPL_DEL_MACROS
	CPL_USE_LABELS = _ida_expr.CPL_USE_LABELS
	CPL_ONLY_SAFE = _ida_expr.CPL_ONLY_SAFE
int	EXTFUN_BASE = 1
int	EXTFUN_NORET = 2
int	EXTFUN_SAFE = 4

Function Documentation

add_idc_class()

'idc_class_t *' add_idc_class	(	str	name,
		'idc_class_t const *'	super = None )

Create a new IDC class. 
    
@param name: name of the new class
@param super: the base class for the new class. if the new class is not based on any other class, pass nullptr
@returns pointer to the created class. If such a class already exists, a pointer to it will be returned. Pointers to other existing classes may be invalidated by this call.

add_idc_func()

add_idc_func	(		name,
			fp,
			args,
			defvals = (),
			flags = 0 )

Add an IDC function. This function does not modify the predefined kernel functions. Example: 
 error_t idaapi myfunc5(idc_value_t *argv, idc_value_t *res)

  msg("myfunc is called with arg0=%a and arg1=%s\\n", argv[0].num, argv[1].str);
  res->num = 5;     // let's return 5
  return eOk;

 const char myfunc5_args[] = { VT_LONG, VT_STR, 0 };
 const ext_idcfunc_t myfunc_desc = { "MyFunc5", myfunc5, myfunc5_args, nullptr, 0, EXTFUN_BASE };

 after this:


 there is a new IDC function which can be called like this:
 "test");


    
@returns success

add_idc_gvar()

'idc_value_t *' add_idc_gvar

(

str

name

)

Add global IDC variable. 
    
@param name: name of the global variable
@returns pointer to the created variable or existing variable. NB: the returned pointer is valid until a new global var is added.

compile_idc_file()

str compile_idc_file

(

str

nonnul_line

)

compile_idc_snippet()

str compile_idc_snippet	(	str	func,
		str	text,
		'idc_resolver_t *'	resolver = None,
		bool	only_safe_funcs = False )

Compile text with IDC statements. 
    
@param func: name of the function to create out of the snippet
@param text: text to compile
@param resolver: callback object to get values of undefined variables This object will be called if IDC function contains references to undefined variables. May be nullptr.
@param only_safe_funcs: if true, any calls to functions without EXTFUN_SAFE flag will lead to a compilation error.
@retval true: ok
@retval false: error, see errbuf

compile_idc_text()

str compile_idc_text

(

str

nonnul_line

)

copy_idcv()

'error_t' copy_idcv	(	'idc_value_t'	dst,
		'idc_value_t'	src )

Copy 'src' to 'dst'. For idc objects only a reference is copied. 

create_idcv_ref()

bool create_idcv_ref	(	'idc_value_t'	ref,
		'idc_value_t'	v )

Create a variable reference. Currently only references to global variables can be created. 
    
@param ref: ptr to the result
@param v: variable to reference
@returns success

deep_copy_idcv()

'error_t' deep_copy_idcv	(	'idc_value_t'	dst,
		'idc_value_t'	src )

Deep copy an IDC object. This function performs deep copy of idc objects. If 'src' is not an object, copy_idcv() will be called 

del_idc_func()

del_idc_func

(

name

)

Delete an IDC function 

del_idcv_attr()

'error_t' del_idcv_attr	(	'idc_value_t'	obj,
		str	attr )

Delete an object attribute. 
    
@param obj: variable that holds an object reference
@param attr: attribute name
@returns error code, eOk on success

deref_idcv()

'idc_value_t *' deref_idcv	(	'idc_value_t'	v,
		int	vref_flags )

Dereference a VT_REF variable. 
    
@param v: variable to dereference
@param vref_flags: Dereference IDC variable flags
@returns pointer to the dereference result or nullptr. If returns nullptr, qerrno is set to eExecBadRef "Illegal variable reference\"

eval_expr()

str eval_expr	(	'idc_value_t'	rv,
		ida_idaapi.ea_t	where,
		str	line )

Compile and calculate an expression. 
    
@param rv: pointer to the result
@param where: the current linear address in the addressing space of the program being disassembled. If will be used to resolve names of local variables etc. if not applicable, then should be BADADDR.
@param line: the expression to evaluate
@retval true: ok
@retval false: error, see errbuf

eval_idc_expr()

str eval_idc_expr	(	'idc_value_t'	rv,
		ida_idaapi.ea_t	where,
		str	line )

Same as eval_expr(), but will always use the IDC interpreter regardless of the currently installed extlang. 

exec_idc_script()

str exec_idc_script	(	'idc_value_t'	result,
		str	path,
		str	func,
		'idc_value_t'	args,
		'size_t'	argsnum )

Compile and execute IDC function(s) from file. 
    
@param result: ptr to idc_value_t to hold result of the function. If execution fails, this variable will contain the exception information. You may pass nullptr if you are not interested in the returned value.
@param path: text file containing text of IDC functions
@param func: function name to execute
@param args: array of parameters
@param argsnum: number of parameters to pass to 'fname' This number should be equal to number of parameters the function expects.
@retval true: ok
@retval false: error, see errbuf

exec_system_script()

bool exec_system_script	(	str	file,
		bool	complain_if_no_file = True )

Compile and execute "main" function from system file. 
    
@param file: file name with IDC function(s). The file will be searched using get_idc_filename().
@param complain_if_no_file: * 1: display warning if the file is not found
* 0: don't complain if file doesn't exist
@retval 1: ok, file is compiled and executed
@retval 0: failure, compilation or execution error, warning is displayed

find_idc_class()

'idc_class_t *' find_idc_class

(

str

name

)

Find an existing IDC class by its name. 
    
@param name: name of the class
@returns pointer to the class or nullptr. The returned pointer is valid until a new call to add_idc_class()

find_idc_func()

str find_idc_func	(	str	prefix,
		int	n = 0 )

find_idc_gvar()

'idc_value_t *' find_idc_gvar

(

str

name

)

Find an existing global IDC variable by its name. 
    
@param name: name of the global variable
@returns pointer to the variable or nullptr. NB: the returned pointer is valid until a new global var is added. FIXME: it is difficult to use this function in a thread safe manner

first_idcv_attr()

str first_idcv_attr

(

'idc_value_t'

obj

)

free_idcv()

None free_idcv

(

'idc_value_t'

v

)

Free storage used by VT_STR/VT_OBJ IDC variables. After this call the variable has a numeric value 0 

get_idc_filename()

str get_idc_filename

(

str

file

)

Get full name of IDC file name. Search for file in list of include directories, IDCPATH directory and system directories. 
    
@param file: file name without full path
@returns nullptr is file not found. otherwise returns pointer to buf

get_idcv_attr()

'error_t' get_idcv_attr	(	'idc_value_t'	res,
		'idc_value_t'	obj,
		str	attr,
		bool	may_use_getattr = False )

Get an object attribute. 
    
@param res: buffer for the attribute value
@param obj: variable that holds an object reference. if obj is nullptr it searches global variables, then user functions
@param attr: attribute name
@param may_use_getattr: may call getattr functions to calculate the attribute if it does not exist
@returns error code, eOk on success

get_idcv_class_name()

str get_idcv_class_name

(

'idc_value_t'

obj

)

Retrieves the IDC object class name. 
    
@param obj: class instance variable
@returns error code, eOk on success

get_idcv_slice()

'error_t' get_idcv_slice	(	'idc_value_t'	res,
		'idc_value_t'	v,
		int	i1,
		int	i2,
		int	flags = 0 )

Get slice. 
    
@param res: output variable that will contain the slice
@param v: input variable (string or object)
@param i1: slice start index
@param i2: slice end index (excluded)
@param flags: IDC variable slice flags or 0
@returns eOk if success

idcv_float()

'error_t' idcv_float

(

'idc_value_t'

v

)

Convert IDC variable to a floating point.

idcv_int64()

'error_t' idcv_int64

(

'idc_value_t'

v

)

Convert IDC variable to a 64bit number. 
    
@returns v = 0 if impossible to convert to int64

idcv_long()

'error_t' idcv_long

(

'idc_value_t'

v

)

Convert IDC variable to a long (32/64bit) number. 
    
@returns v = 0 if impossible to convert to long

idcv_num()

'error_t' idcv_num

(

'idc_value_t'

v

)

Convert IDC variable to a long number. 
    
@returns * v = 0 if IDC variable = "false" string
* v = 1 if IDC variable = "true" string
* v = number if IDC variable is number or string containing a number
* eTypeConflict if IDC variable = empty string

idcv_object()

'error_t' idcv_object	(	'idc_value_t'	v,
		'idc_class_t const *'	icls = None )

Create an IDC object. The original value of 'v' is discarded (freed). 
    
@param v: variable to hold the object. any previous value will be cleaned
@param icls: ptr to the desired class. nullptr means "object" class this ptr must be returned by add_idc_class() or find_idc_class()
@returns always eOk

idcv_string()

'error_t' idcv_string

(

'idc_value_t'

v

)

Convert IDC variable to a text string.

last_idcv_attr()

str last_idcv_attr

(

'idc_value_t'

obj

)

move_idcv()

'error_t' move_idcv	(	'idc_value_t'	dst,
		'idc_value_t'	src )

Move 'src' to 'dst'. This function is more effective than copy_idcv since it never copies big amounts of data. 

next_idcv_attr()

str next_idcv_attr	(	'idc_value_t'	obj,
		str	attr )

prev_idcv_attr()

str prev_idcv_attr	(	'idc_value_t'	obj,
		str	attr )

print_idcv()

str print_idcv	(	'idc_value_t'	v,
		str	name = None,
		int	indent = 0 )

Get text representation of idc_value_t.

py_add_idc_func()

bool py_add_idc_func	(	str	name,
		'size_t'	fp_ptr,
		str	args,
		'idc_values_t'	defvals,
		int	flags )

py_get_call_idc_func()

'size_t' py_get_call_idc_func

(

)

pyw_convert_defvals()

bool pyw_convert_defvals	(	'idc_values_t'	out,
		'PyObject *'	py_seq )

pyw_register_idc_func()

'size_t' pyw_register_idc_func	(	str	name,
		str	args,
		'PyObject *'	py_fp )

pyw_unregister_idc_func()

bool pyw_unregister_idc_func

(

'size_t'

ctxptr

)

set_header_path()

bool set_header_path	(	str	path,
		bool	add )

Set or append a header path. IDA looks for the include files in the appended header paths, then in the ida executable directory. 
    
@param path: list of directories to add (separated by ';') may be nullptr, in this case nothing is added
@param add: true: append. false: remove old paths.
@retval true: success
@retval false: no memory

set_idcv_attr()

'error_t' set_idcv_attr	(	'idc_value_t'	obj,
		str	attr,
		'idc_value_t'	value,
		bool	may_use_setattr = False )

Set an object attribute. 
    
@param obj: variable that holds an object reference. if obj is nullptr then it tries to modify a global variable with the attribute name
@param attr: attribute name
@param value: new attribute value
@param may_use_setattr: may call setattr functions for the class
@returns error code, eOk on success

set_idcv_slice()

'error_t' set_idcv_slice	(	'idc_value_t'	v,
		int	i1,
		int	i2,
		'idc_value_t'	_in,
		int	flags = 0 )

Set slice. 
    
@param v: variable to modify (string or object)
@param i1: slice start index
@param i2: slice end index (excluded)
@param flags: IDC variable slice flags or 0
@returns eOk on success

swap_idcvs()

None swap_idcvs	(	'idc_value_t'	v1,
		'idc_value_t'	v2 )

Swap 2 variables.

throw_idc_exception()

'error_t' throw_idc_exception	(	'idc_value_t'	r,
		str	desc )

Create an idc execution exception object. This helper function can be used to return an exception from C++ code to IDC. In other words this function can be called from idc_func_t() callbacks. Sample usage: if ( !ok ) return throw_idc_exception(r, "detailed error msg"); 
    
@param r: object to hold the exception object
@param desc: exception description
@returns eExecThrow

Variable Documentation

CPL_DEL_MACROS

CPL_DEL_MACROS = _ida_expr.CPL_DEL_MACROS

CPL_ONLY_SAFE

CPL_ONLY_SAFE = _ida_expr.CPL_ONLY_SAFE

CPL_USE_LABELS

CPL_USE_LABELS = _ida_expr.CPL_USE_LABELS

eExecThrow

eExecThrow = _ida_expr.eExecThrow

EXTFUN_BASE

int EXTFUN_BASE = 1

EXTFUN_NORET

int EXTFUN_NORET = 2

EXTFUN_SAFE

int EXTFUN_SAFE = 4

HF_COMMENT

HF_COMMENT = _ida_expr.HF_COMMENT

HF_DEFAULT

HF_DEFAULT = _ida_expr.HF_DEFAULT

HF_KEYWORD1

HF_KEYWORD1 = _ida_expr.HF_KEYWORD1

HF_KEYWORD2

HF_KEYWORD2 = _ida_expr.HF_KEYWORD2

HF_KEYWORD3

HF_KEYWORD3 = _ida_expr.HF_KEYWORD3

HF_MAX

HF_MAX = _ida_expr.HF_MAX

HF_NUMBER

HF_NUMBER = _ida_expr.HF_NUMBER

HF_PREPROC

HF_PREPROC = _ida_expr.HF_PREPROC

HF_STRING

HF_STRING = _ida_expr.HF_STRING

HF_USER1

HF_USER1 = _ida_expr.HF_USER1

HF_USER2

HF_USER2 = _ida_expr.HF_USER2

HF_USER3

HF_USER3 = _ida_expr.HF_USER3

HF_USER4

HF_USER4 = _ida_expr.HF_USER4

IDC_LANG_EXT

IDC_LANG_EXT = _ida_expr.IDC_LANG_EXT

VARSLICE_SINGLE

VARSLICE_SINGLE = _ida_expr.VARSLICE_SINGLE

VREF_COPY

VREF_COPY = _ida_expr.VREF_COPY

VREF_LOOP

VREF_LOOP = _ida_expr.VREF_LOOP

VREF_ONCE

VREF_ONCE = _ida_expr.VREF_ONCE

VT_FLOAT

VT_FLOAT = _ida_expr.VT_FLOAT

VT_FUNC

VT_FUNC = _ida_expr.VT_FUNC

VT_INT64

VT_INT64 = _ida_expr.VT_INT64

VT_LONG

VT_LONG = _ida_expr.VT_LONG

VT_OBJ

VT_OBJ = _ida_expr.VT_OBJ

VT_PVOID

VT_PVOID = _ida_expr.VT_PVOID

VT_REF

VT_REF = _ida_expr.VT_REF

VT_STR

VT_STR = _ida_expr.VT_STR

VT_WILD

VT_WILD = _ida_expr.VT_WILD