ida_expr

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.

Attributes

`SWIG_PYTHON_LEGACY_BOOL`
`IDC_LANG_EXT`	IDC script extension.
`VARSLICE_SINGLE`	return single index (i2 is ignored)
`VREF_LOOP`	dereference until we get a non VT_REF
`VREF_ONCE`	dereference only once, do not loop
`VREF_COPY`	copy the result to the input var (v)
`VT_LONG`	Integer (see idc_value_t::num)
`VT_FLOAT`	Floating point (see idc_value_t::e)
`VT_WILD`	Function with arbitrary number of arguments. The actual number of arguments will be passed in idc_value_t::num. This value should not be used for idc_value_t.
`VT_OBJ`	Object (see idc_value_t::obj)
`VT_FUNC`	Function (see idc_value_t::funcidx)
`VT_STR`	String (see qstr() and similar functions)
`VT_PVOID`	void *
`VT_INT64`	i64
`VT_REF`	Reference.
`eExecThrow`	See return value of idc_func_t.
`HF_DEFAULT`
`HF_KEYWORD1`
`HF_KEYWORD2`
`HF_KEYWORD3`
`HF_STRING`
`HF_COMMENT`
`HF_PREPROC`
`HF_NUMBER`
`HF_USER1`
`HF_USER2`
`HF_USER3`
`HF_USER4`
`HF_MAX`
`CPL_DEL_MACROS`	delete macros at the end of compilation
`CPL_USE_LABELS`	allow program labels in the script
`CPL_ONLY_SAFE`	allow calls of only thread-safe functions
`EXTFUN_BASE`	requires open database.
`EXTFUN_NORET`	does not return. the interpreter may clean up its state before calling it.
`EXTFUN_SAFE`	thread safe function. may be called from any thread.

Classes

`idc_value_t`
`idc_global_t`
`highlighter_cbs_t`
`idc_values_t`

Functions

`compile_idc_file`(→ str)
`compile_idc_text`(→ str)
`py_get_call_idc_func`(→ size_t)
`pyw_register_idc_func`(→ size_t)
`pyw_unregister_idc_func`(→ bool)
`pyw_convert_defvals`(→ bool)
`py_add_idc_func`(→ bool)
`eval_expr`(→ str)	Compile and calculate an expression.
`eval_idc_expr`(→ str)	Same as eval_expr(), but will always use the IDC interpreter regardless of the currently installed extlang.
`idcv_long`(→ error_t)	Convert IDC variable to a long (32/64bit) number.
`idcv_int64`(→ error_t)	Convert IDC variable to a 64bit number.
`idcv_num`(→ error_t)	Convert IDC variable to a long number.
`idcv_string`(→ error_t)	Convert IDC variable to a text string.
`idcv_float`(→ error_t)	Convert IDC variable to a floating point.
`idcv_object`(→ error_t)	Create an IDC object. The original value of 'v' is discarded (freed).
`move_idcv`(→ error_t)	Move 'src' to 'dst'. This function is more effective than copy_idcv since it never copies big amounts of data.
`copy_idcv`(→ error_t)	Copy 'src' to 'dst'. For idc objects only a reference is copied.
`deep_copy_idcv`(→ error_t)	Deep copy an IDC object. This function performs deep copy of idc objects. If 'src' is not an object, copy_idcv() will be called
`free_idcv`(→ None)	Free storage used by VT_STR/VT_OBJ IDC variables. After this call the variable has a numeric value 0
`swap_idcvs`(→ None)	Swap 2 variables.
`get_idcv_class_name`(→ str)	Retrieves the IDC object class name.
`get_idcv_attr`(→ error_t)	Get an object attribute.
`set_idcv_attr`(→ error_t)	Set an object attribute.
`del_idcv_attr`(→ error_t)	Delete an object attribute.
`first_idcv_attr`(→ str)
`last_idcv_attr`(→ str)
`next_idcv_attr`(→ str)
`prev_idcv_attr`(→ str)
`print_idcv`(→ str)	Get text representation of idc_value_t.
`get_idcv_slice`(→ error_t)	Get slice.
`set_idcv_slice`(→ error_t)	Set slice.
`add_idc_class`(→ idc_class_t *)	Create a new IDC class.
`find_idc_class`(→ idc_class_t *)	Find an existing IDC class by its name.
`deref_idcv`(→ idc_value_t *)	Dereference a VT_REF variable.
`create_idcv_ref`(→ bool)	Create a variable reference. Currently only references to global variables can be created.
`add_idc_gvar`(→ idc_value_t *)	Add global IDC variable.
`find_idc_gvar`(→ idc_value_t *)	Find an existing global IDC variable by its name.
`find_idc_func`(→ str)
`set_header_path`(→ bool)	Set or append a header path. IDA looks for the include files in the appended header paths, then in the ida executable directory.
`get_idc_filename`(→ str)	Get full name of IDC file name. Search for file in list of include directories, IDCPATH directory and system directories.
`exec_system_script`(→ bool)	Compile and execute "main" function from system file.
`compile_idc_snippet`(→ str)	Compile text with IDC statements.
`exec_idc_script`(→ str)	Compile and execute IDC function(s) from file.
`throw_idc_exception`(→ error_t)	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");
`del_idc_func`(name)	Delete an IDC function
`add_idc_func`(name, fp, args[, defvals, flags])	Add an IDC function. This function does not modify the predefined kernel functions. Example:

Module Contents

ida_expr.SWIG_PYTHON_LEGACY_BOOL

ida_expr.compile_idc_file(nonnul_line: str) → str

ida_expr.compile_idc_text(nonnul_line: str) → str

ida_expr.py_get_call_idc_func() → size_t

ida_expr.pyw_register_idc_func(name: str, args: str, py_fp: PyObject *) → size_t

ida_expr.pyw_unregister_idc_func(ctxptr: size_t) → bool

ida_expr.pyw_convert_defvals(out: idc_values_t, py_seq: PyObject *) → bool

ida_expr.py_add_idc_func(name: str, fp_ptr: size_t, args: str, defvals: idc_values_t, flags: int) → bool

ida_expr.eval_expr(rv: idc_value_t, where: ida_idaapi.ea_t, line: str) → str

Compile and calculate an expression.

Parameters:

rv – pointer to the result
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.
line – the expression to evaluate

Returns:

true: ok

Returns:

false: error, see errbuf

ida_expr.eval_idc_expr(rv: idc_value_t, where: ida_idaapi.ea_t, line: str) → str: Same as eval_expr(), but will always use the IDC interpreter regardless of the currently installed extlang.

ida_expr.IDC_LANG_EXT: IDC script extension.

ida_expr.idcv_long(v: idc_value_t) → error_t

Convert IDC variable to a long (32/64bit) number.

Returns:: v = 0 if impossible to convert to long

ida_expr.idcv_int64(v: idc_value_t) → error_t

Convert IDC variable to a 64bit number.

Returns:: v = 0 if impossible to convert to int64

ida_expr.idcv_num(v: idc_value_t) → error_t

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

ida_expr.idcv_string(v: idc_value_t) → error_t: Convert IDC variable to a text string.

ida_expr.idcv_float(v: idc_value_t) → error_t: Convert IDC variable to a floating point.

ida_expr.idcv_object(v: idc_value_t, icls: idc_class_t const * = None) → error_t

Create an IDC object. The original value of ‘v’ is discarded (freed).

Parameters:

v – variable to hold the object. any previous value will be cleaned
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

ida_expr.move_idcv(dst: idc_value_t, src: idc_value_t) → error_t: Move ‘src’ to ‘dst’. This function is more effective than copy_idcv since it never copies big amounts of data.

ida_expr.copy_idcv(dst: idc_value_t, src: idc_value_t) → error_t: Copy ‘src’ to ‘dst’. For idc objects only a reference is copied.

ida_expr.deep_copy_idcv(dst: idc_value_t, src: idc_value_t) → error_t: Deep copy an IDC object. This function performs deep copy of idc objects. If ‘src’ is not an object, copy_idcv() will be called

ida_expr.free_idcv(v: idc_value_t) → None: Free storage used by VT_STR/VT_OBJ IDC variables. After this call the variable has a numeric value 0

ida_expr.swap_idcvs(v1: idc_value_t, v2: idc_value_t) → None: Swap 2 variables.

ida_expr.get_idcv_class_name(obj: idc_value_t) → str

Retrieves the IDC object class name.

Parameters:: obj – class instance variable
Returns:: error code, eOk on success

ida_expr.get_idcv_attr(res: idc_value_t, obj: idc_value_t, attr: str, may_use_getattr: bool = False) → error_t

Get an object attribute.

Parameters:

res – buffer for the attribute value
obj – variable that holds an object reference. if obj is nullptr it searches global variables, then user functions
attr – attribute name
may_use_getattr – may call getattr functions to calculate the attribute if it does not exist

Returns:

error code, eOk on success

ida_expr.set_idcv_attr(obj: idc_value_t, attr: str, value: idc_value_t, may_use_setattr: bool = False) → error_t

Set an object attribute.

Parameters:

obj – variable that holds an object reference. if obj is nullptr then it tries to modify a global variable with the attribute name
attr – attribute name
value – new attribute value
may_use_setattr – may call setattr functions for the class

Returns:

error code, eOk on success

ida_expr.del_idcv_attr(obj: idc_value_t, attr: str) → error_t

Delete an object attribute.

Parameters:

obj – variable that holds an object reference
attr – attribute name

Returns:

error code, eOk on success

ida_expr.first_idcv_attr(obj: idc_value_t) → str

ida_expr.last_idcv_attr(obj: idc_value_t) → str

ida_expr.next_idcv_attr(obj: idc_value_t, attr: str) → str

ida_expr.prev_idcv_attr(obj: idc_value_t, attr: str) → str

ida_expr.print_idcv(v: idc_value_t, name: str = None, indent: int = 0) → str: Get text representation of idc_value_t.

ida_expr.get_idcv_slice(res: idc_value_t, v: idc_value_t, i1: int, i2: int, flags: int = 0) → error_t

Get slice.

Parameters:

res – output variable that will contain the slice
v – input variable (string or object)
i1 – slice start index
i2 – slice end index (excluded)
flags – IDC variable slice flags or 0

Returns:

eOk if success

ida_expr.VARSLICE_SINGLE: return single index (i2 is ignored)

ida_expr.set_idcv_slice(v: idc_value_t, i1: int, i2: int, _in: idc_value_t, flags: int = 0) → error_t

Set slice.

Parameters:

v – variable to modify (string or object)
i1 – slice start index
i2 – slice end index (excluded)
flags – IDC variable slice flags or 0

Returns:

eOk on success

ida_expr.add_idc_class(name: str, super: idc_class_t const * = None) → idc_class_t *

Create a new IDC class.

Parameters:

name – name of the new class
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.

ida_expr.find_idc_class(name: str) → idc_class_t *

Find an existing IDC class by its name.

Parameters:: 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()

ida_expr.deref_idcv(v: idc_value_t, vref_flags: int) → idc_value_t *

Dereference a VT_REF variable.

Parameters:

v – variable to dereference
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”

ida_expr.VREF_LOOP: dereference until we get a non VT_REF

ida_expr.VREF_ONCE: dereference only once, do not loop

ida_expr.VREF_COPY: copy the result to the input var (v)

ida_expr.create_idcv_ref(ref: idc_value_t, v: idc_value_t) → bool

Create a variable reference. Currently only references to global variables can be created.

Parameters:

ref – ptr to the result
v – variable to reference

Returns:

success

ida_expr.add_idc_gvar(name: str) → idc_value_t *

Add global IDC variable.

Parameters:: 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.

ida_expr.find_idc_gvar(name: str) → idc_value_t *

Find an existing global IDC variable by its name.

Parameters:: 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

class ida_expr.idc_value_t(*args)

Bases: object

thisown

vtype: char: IDC value types

num: int: VT_LONG

e: fpvalue_t: VT_FLOAT

obj: idc_object_t *

funcidx: int: VT_FUNC

pvoid: void *: VT_PVOID

i64: int64: VT_INT64

reserve: uchar[sizeof(qstring)]: VT_STR.

clear() → None: See free_idcv()

qstr() → str: VT_STR

c_str() → str: VT_STR

u_str() → uchar const *: VT_STR

swap(v: idc_value_t) → None: Set this = r and v = this.

is_zero() → bool: Does value represent the integer 0?

is_integral() → bool: Does value represent a whole number?

is_convertible() → bool: Convertible types are VT_LONG, VT_FLOAT, VT_INT64, and VT_STR.

create_empty_string() → None

set_string(*args) → None

set_long(v: int) → None

set_pvoid(p: void *) → None

set_int64(v: int64) → None

set_float(f: fpvalue_t const &) → None

str

ida_expr.VT_LONG: Integer (see idc_value_t::num)

ida_expr.VT_FLOAT: Floating point (see idc_value_t::e)

ida_expr.VT_WILD: Function with arbitrary number of arguments. The actual number of arguments will be passed in idc_value_t::num. This value should not be used for idc_value_t.

ida_expr.VT_OBJ: Object (see idc_value_t::obj)

ida_expr.VT_FUNC: Function (see idc_value_t::funcidx)

ida_expr.VT_STR: String (see qstr() and similar functions)

ida_expr.VT_PVOID: void *

ida_expr.VT_INT64: i64

ida_expr.VT_REF: Reference.

class ida_expr.idc_global_t(*args)

Bases: object

thisown

name: str

value: idc_value_t

ida_expr.eExecThrow: See return value of idc_func_t.

ida_expr.find_idc_func(prefix: str, n: int = 0) → str

ida_expr.HF_DEFAULT

ida_expr.HF_KEYWORD1

ida_expr.HF_KEYWORD2

ida_expr.HF_KEYWORD3

ida_expr.HF_STRING

ida_expr.HF_COMMENT

ida_expr.HF_PREPROC

ida_expr.HF_NUMBER

ida_expr.HF_USER1

ida_expr.HF_USER2

ida_expr.HF_USER3

ida_expr.HF_USER4

ida_expr.HF_MAX

class ida_expr.highlighter_cbs_t

Bases: object

thisown

set_style(arg0: int, arg1: int, arg2: syntax_highlight_style) → None

prev_block_state() → int

cur_block_state() → int

set_block_state(arg0: int) → None

ida_expr.set_header_path(path: str, add: bool) → bool

Set or append a header path. IDA looks for the include files in the appended header paths, then in the ida executable directory.

Parameters:

path – list of directories to add (separated by ‘;’) may be nullptr, in this case nothing is added
add – true: append. false: remove old paths.

Returns:

true: success

Returns:

false: no memory

ida_expr.get_idc_filename(file: str) → str

Get full name of IDC file name. Search for file in list of include directories, IDCPATH directory and system directories.

Parameters:: file – file name without full path
Returns:: nullptr is file not found. otherwise returns pointer to buf

ida_expr.exec_system_script(file: str, complain_if_no_file: bool = True) → bool

Compile and execute “main” function from system file.

Parameters:

file – file name with IDC function(s). The file will be searched using get_idc_filename().
complain_if_no_file –
- 1: display warning if the file is not found

0: don’t complain if file doesn’t exist

Returns:: 1: ok, file is compiled and executed
Returns:: 0: failure, compilation or execution error, warning is displayed

ida_expr.CPL_DEL_MACROS: delete macros at the end of compilation

ida_expr.CPL_USE_LABELS: allow program labels in the script

ida_expr.CPL_ONLY_SAFE: allow calls of only thread-safe functions

ida_expr.compile_idc_snippet(func: str, text: str, resolver: idc_resolver_t * = None, only_safe_funcs: bool = False) → str

Compile text with IDC statements.

Parameters:

func – name of the function to create out of the snippet
text – text to compile
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.
only_safe_funcs – if true, any calls to functions without EXTFUN_SAFE flag will lead to a compilation error.

Returns:

true: ok

Returns:

false: error, see errbuf

ida_expr.exec_idc_script(result: idc_value_t, path: str, func: str, args: idc_value_t, argsnum: size_t) → str

Compile and execute IDC function(s) from file.

Parameters:

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.
path – text file containing text of IDC functions
func – function name to execute
args – array of parameters
argsnum – number of parameters to pass to ‘fname’ This number should be equal to number of parameters the function expects.

Returns:

true: ok

Returns:

false: error, see errbuf

ida_expr.throw_idc_exception(r: idc_value_t, desc: str) → error_t

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”);

Parameters:

r – object to hold the exception object
desc – exception description

Returns:

eExecThrow

class ida_expr.idc_values_t(*args)

Bases: object

thisown

push_back(*args) → idc_value_t &

pop_back() → None

size() → size_t

empty() → bool

at(_idx: size_t) → idc_value_t const &

qclear() → None

clear() → None

resize(*args) → None

grow(*args) → None

capacity() → size_t

reserve(cnt: size_t) → None

truncate() → None

swap(r: idc_values_t) → None

extract() → idc_value_t *

inject(s: idc_value_t, len: size_t) → None

begin(*args) → qvector< idc_value_t >::const_iterator

end(*args) → qvector< idc_value_t >::const_iterator

insert(it: idc_value_t, x: idc_value_t) → qvector< idc_value_t >::iterator

erase(*args) → qvector< idc_value_t >::iterator

append(x: idc_value_t) → None

extend(x: idc_values_t) → None

front

back

ida_expr.EXTFUN_BASE = 1: requires open database.

ida_expr.EXTFUN_NORET = 2: does not return. the interpreter may clean up its state before calling it.

ida_expr.EXTFUN_SAFE = 4: thread safe function. may be called from any thread.

ida_expr.del_idc_func(name): Delete an IDC function

ida_expr.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=%sn”, 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