Module `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.

Global variables

var CPL_DEL_MACROS: delete macros at the end of compilation
var CPL_ONLY_SAFE: allow calls of only thread-safe functions
var CPL_USE_LABELS: allow program labels in the script
var EXTFUN_BASE: requires open database.
var EXTFUN_NORET: does not return. the interpreter may clean up its state before calling it.
var EXTFUN_SAFE: thread safe function. may be called from any thread.
var HF_COMMENT: HF_COMMENT = 5
var HF_DEFAULT: HF_DEFAULT = 0
var HF_KEYWORD1: HF_KEYWORD1 = 1
var HF_KEYWORD2: HF_KEYWORD2 = 2
var HF_KEYWORD3: HF_KEYWORD3 = 3
var HF_MAX: HF_MAX = 8
var HF_NUMBER: HF_NUMBER = 7
var HF_PREPROC: HF_PREPROC = 6
var HF_STRING: HF_STRING = 4
var IDC_LANG_EXT: IDC script extension.
var VARSLICE_SINGLE: return single index (i2 is ignored)
var VREF_COPY: copy the result to the input var (v)
var VREF_LOOP: dereference until we get a non VT_REF
var VREF_ONCE: dereference only once, do not loop
var VT_FLOAT: Floating point (see idc_value_t::e)
var VT_FUNC: Function (see idc_value_t::funcidx)
var VT_INT64: i64
var VT_LONG: Integer (see idc_value_t::num)
var VT_OBJ: Object (see idc_value_t::obj)
var VT_PVOID: void *
var VT_REF: Reference.
var VT_STR: String (see qstr() and similar functions)
var 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.
var eExecThrow: See return value of idc_func_t.

Functions

def add_idc_class(*args) ‑> idc_class_t *

add_idc_class(name, super=None) -> idc_class_t *

Create a new IDC class.

name: (C++: const char *) name of the new class

super: (C++: const idc_class_t *) the base class for the new class. if the new class is not based on

any other class, pass nullptr

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

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

Extends the IDC language by exposing a new IDC function that is backed up by a Python function

Add an IDC function. This function does not modify the predefined kernel functions. Example: static 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; } static const char myfunc5_args[] = { VT_LONG, VT_STR, 0 }; static const ext_idcfunc_t myfunc_desc = { "MyFunc5", myfunc5, myfunc5_args, nullptr, 0, EXTFUN_BASE }; // after this: add_idc_func(myfunc_desc); // there is a new IDC function which can be called like this: MyFunc5(0x123, "test");

note: If the function already exists, it will be replaced by the new function

return: success

def add_idc_gvar(*args) ‑> idc_value_t *

add_idc_gvar(name) -> idc_value_t

Add global IDC variable.

name: (C++: const char *) name of the global variable

return: pointer to the created variable or existing variable. NB: the returned

pointer is valid until a new global var is added.

def compile_idc_file(*args) ‑> qstring *

compile_idc_file(nonnul_line) -> str

nonnul_line: char const *

def compile_idc_snippet(*args) ‑> qstring *

compile_idc_snippet(func, text, resolver=None, only_safe_funcs=False) -> str

Compile text with IDC statements.

func: (C++: const char *) name of the function to create out of the snippet

text: (C++: const char *) text to compile

resolver: (C++: idc_resolver_t *) 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: (C++: bool) if true, any calls to functions without EXTFUN_SAFE flag

will lead to a compilation error.

retval true: ok

retval false: error, see errbuf

def compile_idc_text(*args) ‑> qstring *

compile_idc_text(nonnul_line) -> str

nonnul_line: char const *

def copy_idcv(*args) ‑> error_t

copy_idcv(dst, src) -> error_t

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

dst: (C++: idc_value_t *)

src: (C++: const idc_value_t &) idc_value_t const &

def create_idcv_ref(*args) ‑> bool

create_idcv_ref(ref, v) -> bool

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

ref: (C++: idc_value_t *) ptr to the result

v: (C++: const idc_value_t *) variable to reference

return: success

def deep_copy_idcv(*args) ‑> error_t

deep_copy_idcv(dst, src) -> 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

dst: (C++: idc_value_t *)

src: (C++: const idc_value_t &) idc_value_t const &

def del_idc_func(name)

Unregisters the specified IDC function

Delete an IDC function

def del_idcv_attr(*args) ‑> error_t

del_idcv_attr(obj, attr) -> error_t

Delete an object attribute.

obj: (C++: idc_value_t *) variable that holds an object reference

attr: (C++: const char *) attribute name

return: error code, eOk on success

def deref_idcv(*args) ‑> idc_value_t *

deref_idcv(v, vref_flags) -> idc_value_t

Dereference a VT_REF variable.

v: (C++: idc_value_t *) variable to dereference

vref_flags: (C++: int) Dereference IDC variable flags

return: pointer to the dereference result or nullptr. If returns nullptr,

qerrno is set to eExecBadRef "Illegal variable reference"

def eval_expr(*args) ‑> qstring *

eval_expr(rv, where, line) -> str

Compile and calculate an expression.

rv: (C++: idc_value_t *) pointer to the result

where: (C++: ea_t) 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: (C++: const char *) the expression to evaluate

retval true: ok

retval false: error, see errbuf

def eval_idc_expr(*args) ‑> qstring *

eval_idc_expr(rv, where, line) -> str

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

rv: (C++: idc_value_t *)

where: (C++: ea_t)

line: char const *

def exec_idc_script(*args) ‑> qstring *

exec_idc_script(result, path, func, args, argsnum) -> str

Compile and execute IDC function(s) from file.

result: (C++: idc_value_t *) 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: (C++: const char *) text file containing text of IDC functions

func: (C++: const char *) function name to execute

args: (C++: const idc_value_t) array of parameters

argsnum: (C++: size_t) 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

def exec_system_script(*args) ‑> bool

exec_system_script(file, complain_if_no_file=True) -> bool

Compile and execute "main" function from system file.

file: (C++: const char *) file name with IDC function(s). The file will be searched using

get_idc_filename().

complain_if_no_file: (C++: bool) * 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

def find_idc_class(*args) ‑> idc_class_t *

find_idc_class(name) -> idc_class_t *

Find an existing IDC class by its name.

name: (C++: const char *) name of the class

return: pointer to the class or nullptr. The returned pointer is valid until a

new call to add_idc_class()

def find_idc_func(*args) ‑> qstring *

find_idc_func(prefix, n=0) -> str

prefix: char const *

n: int

def find_idc_gvar(*args) ‑> idc_value_t *

find_idc_gvar(name) -> idc_value_t

Find an existing global IDC variable by its name.

name: (C++: const char *) name of the global variable

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

def first_idcv_attr(*args) ‑> char const *

first_idcv_attr(obj) -> char const *

obj: idc_value_t const *

def free_idcv(*args) ‑> void

free_idcv(v)

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

v: (C++: idc_value_t *)

def get_idc_filename(*args) ‑> char const *

get_idc_filename(file) -> str

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

file: (C++: const char *) file name without full path

return: nullptr is file not found. otherwise returns pointer to buf

def get_idcv_attr(*args) ‑> error_t

get_idcv_attr(res, obj, attr, may_use_getattr=False) -> error_t

Get an object attribute.

res: (C++: idc_value_t *) buffer for the attribute value

obj: (C++: const idc_value_t *) variable that holds an object reference. if obj is nullptr it

searches global variables, then user functions

attr: (C++: const char *) attribute name

may_use_getattr: (C++: bool) may call getattr functions to calculate the attribute if

it does not exist

return: error code, eOk on success

def get_idcv_class_name(*args) ‑> qstring *

get_idcv_class_name(obj) -> str

Retrieves the IDC object class name.

obj: (C++: const idc_value_t *) class instance variable

return: error code, eOk on success

def get_idcv_slice(*args) ‑> error_t

get_idcv_slice(res, v, i1, i2, flags=0) -> error_t

Get slice.

res: (C++: idc_value_t *) output variable that will contain the slice

v: (C++: const idc_value_t *) input variable (string or object)

i1: (C++: uval_t) slice start index

i2: (C++: uval_t) slice end index (excluded)

flags: (C++: int) IDC variable slice flags or 0

return: eOk if success

def idcv_float(*args) ‑> error_t

idcv_float(v) -> error_t

Convert IDC variable to a floating point.

v: (C++: idc_value_t *)

def idcv_int64(*args) ‑> error_t

idcv_int64(v) -> error_t

Convert IDC variable to a 64bit number.

v: (C++: idc_value_t *)

return: v = 0 if impossible to convert to int64

def idcv_long(*args) ‑> error_t

idcv_long(v) -> error_t

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

v: (C++: idc_value_t *)

return: v = 0 if impossible to convert to long

def idcv_num(*args) ‑> error_t

idcv_num(v) -> error_t

Convert IDC variable to a long number.

v: (C++: idc_value_t *)

return: * 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

def idcv_object(*args) ‑> error_t

idcv_object(v, icls=None) -> error_t

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

v: (C++: idc_value_t *) variable to hold the object. any previous value will be cleaned

icls: (C++: const idc_class_t *) ptr to the desired class. nullptr means "object" class this ptr

must be returned by add_idc_class() or find_idc_class()

return: always eOk

def idcv_string(*args) ‑> error_t

idcv_string(v) -> error_t

Convert IDC variable to a text string.

v: (C++: idc_value_t *)

def last_idcv_attr(*args) ‑> char const *

last_idcv_attr(obj) -> char const *

obj: idc_value_t const *

def move_idcv(*args) ‑> error_t

move_idcv(dst, src) -> error_t

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

dst: (C++: idc_value_t *)

src: (C++: idc_value_t *)

def next_idcv_attr(*args) ‑> char const *

next_idcv_attr(obj, attr) -> char const *

obj: idc_value_t const *

attr: char const *

def prev_idcv_attr(*args) ‑> char const *

prev_idcv_attr(obj, attr) -> char const *

obj: idc_value_t const *

attr: char const *

def print_idcv(*args) ‑> qstring *

print_idcv(v, name=None, indent=0) -> str

Get text representation of idc_value_t.

v: (C++: const idc_value_t &) idc_value_t const &

name: (C++: const char *) char const *

indent: (C++: int)

def py_add_idc_func(*args) ‑> bool

py_add_idc_func(name, fp_ptr, args, defvals, flags) -> bool

name: char const *

fp_ptr: size_t

args: char const *

defvals: idc_values_t const &

flags: int

def py_get_call_idc_func(*args) ‑> size_t

py_get_call_idc_func() -> size_t

def pyw_convert_defvals(*args) ‑> bool

pyw_convert_defvals(out, py_seq) -> bool

out: idc_values_t *

py_seq: PyObject *

def pyw_register_idc_func(*args) ‑> size_t

pyw_register_idc_func(name, args, py_fp) -> size_t

name: char const *

args: char const *

py_fp: PyObject *

def pyw_unregister_idc_func(*args) ‑> bool

pyw_unregister_idc_func(ctxptr) -> bool

ctxptr: size_t

def set_header_path(*args) ‑> bool

set_header_path(path, add) -> bool

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

path: (C++: const char *) list of directories to add (separated by ';') may be nullptr, in

this case nothing is added

add: (C++: bool) true: append. false: remove old paths.

retval true: success

retval false: no memory

def set_idcv_attr(*args) ‑> error_t

set_idcv_attr(obj, attr, value, may_use_setattr=False) -> error_t

Set an object attribute.

obj: (C++: idc_value_t *) variable that holds an object reference. if obj is nullptr then it

tries to modify a global variable with the attribute name

attr: (C++: const char *) attribute name

value: (C++: const idc_value_t &) new attribute value

may_use_setattr: (C++: bool) may call setattr functions for the class

return: error code, eOk on success

def set_idcv_slice(*args) ‑> error_t

set_idcv_slice(v, i1, i2, _in, flags=0) -> error_t

Set slice.

v: (C++: idc_value_t *) variable to modify (string or object)

i1: (C++: uval_t) slice start index

i2: (C++: uval_t) slice end index (excluded)

in: (C++: const idc_value_t &) new value for the slice

flags: (C++: int) IDC variable slice flags or 0

return: eOk on success

def swap_idcvs(*args) ‑> void

swap_idcvs(v1, v2)

Swap 2 variables.

v1: (C++: idc_value_t *)

v2: (C++: idc_value_t *)

def throw_idc_exception(*args) ‑> error_t

throw_idc_exception(r, desc) -> 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");

r: (C++: idc_value_t *) object to hold the exception object

desc: (C++: const char *) exception description

return: eExecThrow

Classes

class highlighter_cbs_t (*args)

Proxy of C++ highlighter_cbs_t class.

__init__(self) -> highlighter_cbs_t

self: PyObject *

Methods

def cur_block_state(self, *args) ‑> int32: cur_block_state(self) -> int32
def prev_block_state(self, *args) ‑> int32: prev_block_state(self) -> int32
def set_block_state(self, *args) ‑> void: set_block_state(self, arg0)
arg0: int32
def set_style(self, *args) ‑> void: set_style(self, arg0, arg1, arg2)
arg0: int32

arg1: int32

arg2: enum syntax_highlight_style

class idc_global_t (*args)

Proxy of C++ idc_global_t class.

__init__(self) -> idc_global_t

__init__(self, n) -> idc_global_t

n: char const *

Instance variables

var name: name
var value: value

class idc_value_t (*args)

Proxy of C++ idc_value_t class.

__init__(self, n=0) -> idc_value_t

n: sval_t

__init__(self, r) -> idc_value_t

r: idc_value_t const &

__init__(self, _str) -> idc_value_t

_str: char const *

Instance variables

var e: VT_FLOAT
var funcidx: VT_FUNC
var i64: VT_INT64
var num: VT_LONG
var obj: obj
var pvoid: VT_PVOID
var reserve: internal housekeeping: 64-bit qstring is bigger than 12 bytes
var str
var vtype: IDC value types

Methods

def c_str(self, *args) ‑> char const *: c_str(self) -> char const *
VT_STR
def clear(self, *args) ‑> void: clear(self)
See free_idcv()
def create_empty_string(self, *args) ‑> void: create_empty_string(self)
def is_convertible(self, *args) ‑> bool: is_convertible(self) -> bool
Convertible types are VT_LONG, VT_FLOAT, VT_INT64, and VT_STR.
def is_integral(self, *args) ‑> bool: is_integral(self) -> bool
Does value represent a whole number?
def is_zero(self, *args) ‑> bool: is_zero(self) -> bool
Does value represent the integer 0?
def qstr(self, *args) ‑> qstring const &: qstr(self) -> qstring
VT_STR

qstr(self) -> qstring const &
def set_float(self, *args) ‑> void: set_float(self, f)
f: fpvalue_t const &
def set_int64(self, *args) ‑> void: set_int64(self, v)
v: int64
def set_long(self, *args) ‑> void: set_long(self, v)
v: sval_t
def set_pvoid(self, *args) ‑> void: set_pvoid(self, p)
p: void *
def set_string(self, *args) ‑> void: set_string(self, _str, len)
_str: char const *

len: size_t

set_string(self, _str)
_str: char const *
def swap(self, *args) ‑> void: swap(self, v)
Set this = r and v = this.

v: (C++: idc_value_t &)
def u_str(self, *args) ‑> uchar const *: u_str(self) -> uchar const *
VT_STR

class idc_values_t (*args)

Proxy of C++ qvector< idc_value_t > class.

__init__(self) -> idc_values_t

__init__(self, x) -> idc_values_t

x: qvector< idc_value_t > const &

Methods

def at(self, *args) ‑> idc_value_t const &: at(self, _idx) -> idc_value_t
_idx: size_t
def back(self)
def begin(self, *args) ‑> qvector< idc_value_t >::const_iterator: begin(self) -> idc_value_t
def capacity(self, *args) ‑> size_t: capacity(self) -> size_t
def clear(self, *args) ‑> void: clear(self)
def empty(self, *args) ‑> bool: empty(self) -> bool
def end(self, *args) ‑> qvector< idc_value_t >::const_iterator: end(self) -> idc_value_t
def erase(self, *args) ‑> qvector< idc_value_t >::iterator: erase(self, it) -> idc_value_t
it: qvector< idc_value_t >::iterator

erase(self, first, last) -> idc_value_t
first: qvector< idc_value_t >::iterator

last: qvector< idc_value_t >::iterator
def extract(self, *args) ‑> idc_value_t *: extract(self) -> idc_value_t
def front(self)
def grow(self, *args) ‑> void: grow(self, x=idc_value_t())

x: idc_value_t const &
def inject(self, *args) ‑> void: inject(self, s, len)
s: idc_value_t *

len: size_t
def insert(self, *args) ‑> qvector< idc_value_t >::iterator: insert(self, it, x) -> idc_value_t
it: qvector< idc_value_t >::iterator

x: idc_value_t const &
def pop_back(self, *args) ‑> void: pop_back(self)
def push_back(self, *args) ‑> idc_value_t &: push_back(self, x)
x: idc_value_t const &

push_back(self) -> idc_value_t
def qclear(self, *args) ‑> void: qclear(self)
def reserve(self, *args) ‑> void: reserve(self, cnt)
cnt: size_t
def resize(self, *args) ‑> void: resize(self, _newsize, x)
_newsize: size_t

x: idc_value_t const &

resize(self, _newsize)
_newsize: size_t
def size(self, *args) ‑> size_t: size(self) -> size_t
def swap(self, *args) ‑> void: swap(self, r)
r: qvector< idc_value_t > &
def truncate(self, *args) ‑> void: truncate(self)