Module ida_expr
[frames] | no frames]

Module ida_expr

IDA Plugin SDK API wrapper: expr

Classes
  idc_value_t
Proxy of C++ idc_value_t class
  idc_global_t
Proxy of C++ idc_global_t class
  highlighter_cbs_t
Proxy of C++ highlighter_cbs_t class
  idc_values_t
Proxy of C++ qvector<(idc_value_t)> class
Functions
bool
compile_idc_file(nonnul_line)
bool
compile_idc_text(nonnul_line)
size_t
py_get_call_idc_func()
size_t
pyw_register_idc_func(name, args, py_fp)
bool
pyw_unregister_idc_func(ctxptr)
bool
pyw_convert_defvals(out, py_seq)
bool
py_add_idc_func(name, fp_ptr, args, defvals, flags)
bool
eval_expr(rv, where, line)
Compile and calculate an expression.
bool
eval_idc_expr(rv, where, line)
Same as 'eval_expr()' , but will always use the IDC interpreter regardless of the currently installed extlang.
error_t
idcv_long(v)
Convert IDC variable to a long (32/64bit) number.
error_t
idcv_int64(v)
Convert IDC variable to a 64bit number.
error_t
idcv_num(v)
Convert IDC variable to a long number.
error_t
idcv_string(v)
Convert IDC variable to a text string.
error_t
idcv_float(v)
Convert IDC variable to a floating point.
error_t
idcv_object(v, icls=None)
Create an IDC object.
error_t
move_idcv(dst, src)
Move 'src' to 'dst'.
error_t
copy_idcv(dst, src)
Copy 'src' to 'dst'.
error_t
deep_copy_idcv(dst, src)
Deep copy an IDC object.
 
free_idcv(v)
Free storage used by 'VT_STR' / 'VT_OBJ' IDC variables.
 
swap_idcvs(v1, v2)
Swap 2 variables.
error_t
get_idcv_class_name(obj)
Retrieves the IDC object class name.
error_t
get_idcv_attr(res, obj, attr, may_use_getattr=False)
Get an object attribute.
error_t
set_idcv_attr(obj, attr, value, may_use_setattr=False)
Set an object attribute.
error_t
del_idcv_attr(obj, attr)
Delete an object attribute.
char const *
first_idcv_attr(obj)
char const *
last_idcv_attr(obj)
char const *
next_idcv_attr(obj, attr)
char const *
prev_idcv_attr(obj, attr)
bool
print_idcv(v, name=None, indent=0)
Get text representation of 'idc_value_t' .
error_t
get_idcv_slice(res, v, i1, i2, flags=0)
Get slice.
error_t
set_idcv_slice(v, i1, i2, _in, flags=0)
Set slice.
idc_class_t *
add_idc_class(name, super=None)
Create a new IDC class.
idc_class_t *
find_idc_class(name)
Find an existing IDC class by its name.
idc_value_t
deref_idcv(v, vref_flags)
Dereference a 'VT_REF' variable.
bool
create_idcv_ref(ref, v)
Create a variable reference.
idc_value_t
add_idc_gvar(name)
Add global IDC variable.
idc_value_t
find_idc_gvar(name)
Find an existing global IDC variable by its name.
bool
find_idc_func(prefix, n=0)
bool
set_header_path(path, add)
Set or append a header path.
char *
get_idc_filename(file)
Get full name of IDC file name.
bool
exec_system_script(file, complain_if_no_file=True)
Compile and execute "main" function from system file.
bool
compile_idc_snippet(func, text, resolver=None, only_safe_funcs=False)
Compile text with IDC statements.
bool
exec_idc_script(result, path, func, args, argsnum)
Compile and execute IDC function(s) from file.
 
del_idc_func(name)
Unregisters the specified IDC function
 
add_idc_func(name, fp, args, defvals=None, flags=0)
Extends the IDC language by exposing a new IDC function that is backed up by a Python function
Variables
  IDC_LANG_EXT = 'idc'
IDC script extension.
  VARSLICE_SINGLE = 1
return single index (i2 is ignored)
  VREF_LOOP = 0
dereference until we get a non 'VT_REF'
  VREF_ONCE = 1
dereference only once, do not loop
  VREF_COPY = 2
copy the result to the input var (v)
  VT_LONG = 2
Integer (see 'idc_value_t::num' )
  VT_FLOAT = 3
Floating point (see 'idc_value_t::e' )
  VT_WILD = 4
Function with arbitrary number of arguments.
  VT_OBJ = 5
Object (see idc_value_t::obj)
  VT_FUNC = 6
Function (see 'idc_value_t::funcidx' )
  VT_STR = 7
String (see qstr() and similar functions)
  VT_PVOID = 8
void *
  VT_INT64 = 9
i64
  VT_REF = 10
Reference.
  eExecThrow = 90
See return value of 'idc_func_t' .
  HF_DEFAULT = 0
  HF_KEYWORD1 = 1
  HF_KEYWORD2 = 2
  HF_KEYWORD3 = 3
  HF_STRING = 4
  HF_COMMENT = 5
  HF_PREPROC = 6
  HF_NUMBER = 7
  HF_MAX = 8
  CPL_DEL_MACROS = 1
delete macros at the end of compilation
  CPL_USE_LABELS = 2
allow program labels in the script
  CPL_ONLY_SAFE = 4
allow calls of only thread-safe functions
  call_idc_func__ = <CFunctionType object at 0x7fda7a93aae0>
  EXTFUN_BASE = 1
requires open database
  EXTFUN_NORET = 2
does not return.
  EXTFUN_SAFE = 4
thread safe function.
  __package__ = None
Function Details

eval_expr(rv, where, line)

 

Compile and calculate an expression.

Parameters:
  • rv - pointer to the result (C++: idc_value_t *)
  • 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 . (C++: ea_t)
  • line - the expression to evaluate (C++: const char *)
Returns: bool

eval_idc_expr(rv, where, line)

 

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

Parameters:
  • rv, (C++ - idc_value_t *)
  • where, (C++ - ea_t)
Returns: bool

idcv_long(v)

 

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

Parameters:
  • v, (C++ - idc_value_t *)
Returns: error_t
v = 0 if impossible to convert to long

idcv_int64(v)

 

Convert IDC variable to a 64bit number.

Parameters:
  • v, (C++ - idc_value_t *)
Returns: error_t
v = 0 if impossible to convert to int64

idcv_num(v)

 

Convert IDC variable to a long number.

Parameters:
  • v, (C++ - idc_value_t *)
Returns: error_t
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_string(v)

 

Convert IDC variable to a text string.

Parameters:
  • v, (C++ - idc_value_t *)
Returns: error_t

idcv_float(v)

 

Convert IDC variable to a floating point.

Parameters:
  • v, (C++ - idc_value_t *)
Returns: error_t

idcv_object(v, icls=None)

 

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 (C++: idc_value_t *)
  • icls - ptr to the desired class. NULL means "object" class this ptr must be returned by add_idc_class() or find_idc_class() (C++: const idc_class_t *)
Returns: error_t
always eOk

move_idcv(dst, src)

 

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

Parameters:
  • dst, (C++ - idc_value_t *)
  • src, (C++ - idc_value_t *)
Returns: error_t

copy_idcv(dst, src)

 

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

Parameters:
  • dst, (C++ - idc_value_t *)
  • src, (C++ - const idc_value_t &)
Returns: error_t

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

Parameters:
  • dst, (C++ - idc_value_t *)
  • src, (C++ - const idc_value_t &)
Returns: error_t

free_idcv(v)

 

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

Parameters:
  • v, (C++ - idc_value_t *)

swap_idcvs(v1, v2)

 

Swap 2 variables.

Parameters:
  • v1, (C++ - idc_value_t *)
  • v2, (C++ - idc_value_t *)

get_idcv_class_name(obj)

 

Retrieves the IDC object class name.

Parameters:
  • obj - class instance variable (C++: const idc_value_t *)
Returns: error_t
error code, eOk on success

get_idcv_attr(res, obj, attr, may_use_getattr=False)

 

Get an object attribute.

Parameters:
  • res - buffer for the attribute value (C++: idc_value_t *)
  • obj - variable that holds an object reference. if obj is NULL it searches global variables, then user functions (C++: const idc_value_t *)
  • attr - attribute name (C++: const char *)
  • may_use_getattr - may call getattr functions to calculate the attribute if it does not exist (C++: bool)
Returns: error_t
error code, eOk on success

set_idcv_attr(obj, attr, value, may_use_setattr=False)

 

Set an object attribute.

Parameters:
  • obj - variable that holds an object reference. if obj is NULL then it tries to modify a global variable with the attribute name (C++: idc_value_t *)
  • attr - attribute name (C++: const char *)
  • value - new attribute value (C++: const idc_value_t &)
  • may_use_setattr - may call setattr functions for the class (C++: bool)
Returns: error_t
error code, eOk on success

del_idcv_attr(obj, attr)

 

Delete an object attribute.

Parameters:
  • obj - variable that holds an object reference (C++: idc_value_t *)
  • attr - attribute name (C++: const char *)
Returns: error_t
error code, eOk on success

print_idcv(v, name=None, indent=0)

 

Get text representation of 'idc_value_t' .

Parameters:
  • v, (C++ - const idc_value_t &)
  • name, (C++ - const char *)
  • indent, (C++ - int)
Returns: bool

get_idcv_slice(res, v, i1, i2, flags=0)

 

Get slice.

Parameters:
  • res - output variable that will contain the slice (C++: idc_value_t *)
  • v - input variable (string or object) (C++: const idc_value_t *)
  • i1 - slice start index (C++: uval_t)
  • i2 - slice end index (excluded) (C++: uval_t)
  • flags - IDC variable slice flags or 0 (C++: int)
Returns: error_t
eOk if success

set_idcv_slice(v, i1, i2, _in, flags=0)

 

Set slice.

Parameters:
  • v - variable to modify (string or object) (C++: idc_value_t *)
  • i1 - slice start index (C++: uval_t)
  • i2 - slice end index (excluded) (C++: uval_t)
  • flags - IDC variable slice flags or 0 (C++: int)
Returns: error_t
eOk on success

add_idc_class(name, super=None)

 

Create a new IDC class.

Parameters:
  • name - name of the new class (C++: const char *)
  • super - the base class for the new class. if the new class is not based on any other class, pass NULL (C++: const idc_class_t *)
Returns: idc_class_t *
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.

find_idc_class(name)

 

Find an existing IDC class by its name.

Parameters:
  • name - name of the class (C++: const char *)
Returns: idc_class_t *
pointer to the class or NULL. The returned pointer is valid until a new call to add_idc_class()

deref_idcv(v, vref_flags)

 

Dereference a 'VT_REF' variable.

Parameters:
  • v - variable to dereference (C++: idc_value_t *)
  • vref_flags - Dereference IDC variable flags (C++: int)
Returns: idc_value_t
pointer to the dereference result or NULL. If returns NULL, qerrno is set to eExecBadRef "Illegal variable reference"

create_idcv_ref(ref, v)

 

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

Parameters:
  • ref - ptr to the result (C++: idc_value_t *)
  • v - variable to reference (C++: const idc_value_t *)
Returns: bool
success

add_idc_gvar(name)

 

Add global IDC variable.

Parameters:
  • name - name of the global variable (C++: const char *)
Returns: idc_value_t
pointer to the created variable or existing variable. NB: the returned pointer is valid until a new global var is added.

find_idc_gvar(name)

 

Find an existing global IDC variable by its name.

Parameters:
  • name - name of the global variable (C++: const char *)
Returns: idc_value_t
pointer to the variable or NULL. 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

set_header_path(path, add)

 

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 NULL, in this case nothing is added (C++: const char *)
  • add - true: append. false: remove old paths. (C++: bool)
Returns: bool

get_idc_filename(file)

 

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

Parameters:
  • file - file name without full path (C++: const char *)
Returns: char *
NULL is file not found. otherwise returns pointer to buf

exec_system_script(file, complain_if_no_file=True)

 

Compile and execute "main" function from system file.

Parameters:
  • file - file name with IDC function(s). The file will be searched in the idc subdir of ida (C++: const char *)
  • complain_if_no_file - 1: display warning if the file is not found 0: don't complain if file doesn't exist (C++: bool)
Returns: bool

compile_idc_snippet(func, text, resolver=None, only_safe_funcs=False)

 

Compile text with IDC statements.

Parameters:
  • func - name of the function to create out of the snippet (C++: const char *)
  • text - text to compile (C++: const char *)
  • resolver - callback object to get values of undefined variables This object will be called if IDC function contains references to undefined variables. May be NULL. (C++: idc_resolver_t *)
  • only_safe_funcs - if true, any calls to functions without EXTFUN_SAFE flag will lead to a compilation error. (C++: bool)
Returns: bool

exec_idc_script(result, path, func, args, argsnum)

 

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 NULL if you are not interested in the returned value. (C++: idc_value_t *)
  • path - text file containing text of IDC functions (C++: const char *)
  • func - function name to execute (C++: const char *)
  • args - array of parameters (C++: const idc_value_t)
  • argsnum - number of parameters to pass to 'fname' This number should be equal to number of parameters the function expects. (C++: size_t)
Returns: bool

del_idc_func(name)

 

Unregisters the specified IDC function

Parameters:
  • name - IDC function name to unregister
Returns:
Boolean

Delete an IDC function

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

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

    @param name: IDC function name to expose
    @param fp: Python callable that will receive the arguments and return a tuple.
    @param args: Arguments. A tuple of idaapi.VT_XXX constants
    @param flags: IDC function flags. A combination of EXTFUN_XXX constants

    @return: Boolean


    Add an IDC function. This function does not modify the predefined
    kernel functions. Example:staticerror_tidaapimyfunc5(idc_value_t*argv,
    idc_value_t*res){msg("myfunciscalledwitharg0=%aandarg1=%s
",argv[0].n
    um,argv[1].str);res->num=5;//let'sreturn5returneOk;}staticconstcharmyf
    unc5_args[]={VT_LONG,VT_STR,0};staticconstext_idcfunc_tmyfunc_desc={"M
    yFunc5",myfunc5,myfunc5_args,NULL,0,EXTFUN_BASE};//afterthis:add_idc_f
    unc(myfunc_desc);//thereisanewIDCfunctionwhichcanbecalledlikethis:MyFu
    nc5(0x123,"test");If the function already exists, it will be replaced
    by the new function
    
    @return: success
    


Variables Details

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' .

Value:
4

EXTFUN_NORET

does not return. the interpreter may clean up its state before calling it.

Value:
2

EXTFUN_SAFE

thread safe function. may be called

Value:
4