1 of 100

IDC

IDC is an IDA native, embedded scripting language semantically similar to C/C++.

Typical use cases

With IDC, you can write simple scripts for automating repetitive tasks and extending out-of-the-box IDA functionality (for example, for getting the list of all functions or marked positions) without creating more complex plugins with C++ SDK or IDAPython.

What to check next?

Core concepts

IDC language is a C-like language. It has the same lexical tokens as C does: character set, constants, identifiers, keywords, etc. However, since it is a scripting language, there are no pointers, and all variable types can be handled by the interpreter. Any variable may hold any value; variables are declared without specifying their type;

auto myvar;

An IDC program consists of function declarations. By default, execution starts from a function named 'main'.

Select a topic to read:

Expressions

In the IDC expressions you can use almost all C operations except:

are defined more or less like in C, with some minor differences.

There are four type conversion operations:

However, explicit type conversions are rarely required because all type conversions are made automatically:

If any of the long operands is 64bit, the other operand is converted to 64bit too.

There is one notable exception concerning type conversions: if one operand is a string and the other is zero (0), then a string operation is performed. Zero is converted to an empty string in this case.

The & operator is used to take a reference to a variable. References themselves cannot be modified once created. Any assignment to them will modify the target variable. For example:

References to references are immediately resolved:

Since all non-object arguments are passed to functions by value, references are a good way to pass arguments by reference.

Statements

In IDC there are the following statements: expression; (expression-statement) if (expression) statement if (expression) statement else statement for ( expr1; expr2; expr3 ) statement while (expression) statement do statement while (expression); break; continue; return <expr>; return; the same as 'return 0;' { statements... } try statement catch ( var ) statement throw <expr>; ; (empty statement) Please note that the 'switch' statement is not supported.

Functions

An IDC function always returns a value. There are 2 kinds of functions:

functions
user-defined functions A user-defined function is declared this way: static func(arg1,arg2,arg3) { ... } It is not necessary to specify the parameter types because all necessary type conversions are performed automatically.

By default all function arguments are passed by value, except:

If the function to call does not exist, IDA tries to resolve the name using the debugged program labels. If it succeeds, an is performed.

Variables

There are two kinds of variables in IDC:

  - local variables: they are created at the function entry
    and destroyed at the exit

  - global variables: they are created at the compilation time
    and destroyed when the database is closed

A variable can contain:

LONG: a 32-bit signed long integer (64-bit in 64-bit version of IDA)
INT64: a 64-bit signed long integer
STR: a character string
FLOAT: a floating point number (extra precision, up to 25 decimal digits)
OBJECT: an object with attributes and methods (a concept very close to C++ class) more
REF: a reference to another variable
FUNC: a function reference

A local variable is declared this way:

  auto var1;
  auto var2 = <expr>;

Global variables are declared like this:

  extern var;

Global variables can be redefined many times. IDA will silently ignore subsequent declarations. Please note that global variables cannot be initialized at the declaration time.

All C and C++ keywords are reserved and cannot be used as a variable name.

While it is possible to declare a variable anywhere in the function body, all variables are initialized at the function entry and all of them are destroyed only at the exit. So, a variable declared in a loop body will not be reinitialized at each loop iteration, unless explicitly specified with an assignment operator.

If a variable or function name cannot be recognized, IDA tries to resolve them using the names from the disassembled application. In it succeeds, the name is replaced by its value in the disassembly listing. For example:

  .data:00413060 errtable        dd 1   ; oscode
  .data:00413060                 dd 16h ; errnocode

        msg("address is: %x\n", _errtable);

will print 413060. If the label denotes a structure, it is possible to refer to its fields:

        msg("address is: %x\n", _errtable.errnocode);

will print 413064. Please note that IDA does not try to read the data but just returns the address of the structure field. The field address can also be calculated using the get_field_ea function.

NOTE: The processor register names can be used in the IDC scripts when the debugger is active. Reading from such a variable return the corresponding register value. Writing to such a variable modifies the register value in the debugged process. Such variables are accessible only when the application is in the suspended mode.

NOTE: another way to emulate global scope variables is to use array functions and create global persistent arrays.

Constants

The following constants can be used in IDC:

 - long numbers (32-bit for 32-bit version of IDA
            and 64-bit for 64-bit version of IDA)

    12345 - decimal constants
    0x444 - hex constants
    01236 - octal constants
    0b110 - binary constants
    'c'   - character constants

  Any numeric constant may have 'u' and 'l' suffixes, they are ignored.

 - 64-bit numbers. To declare a 64-bit constant, use 'i64' suffix:

   123i64

   Also, if a constant does not fit 32-bits, it will automatically be
   stored as a 64-bit constant.

 - strings. Strings are declared using the double quotes. The backslash
   character can be used to as an escape:

   "string"
   "string\nwith four embedded \x0\x00\000\0 zeroes"

   Multiple string constants in a row will be automatically concatenated:

   "this" " is" " one " "string"

Exceptions

Any runtime error generates an exception. Exceptions terminate the execution. It is possible to catch an exception instead of terminating the execution: auto e; try { ... some statements that cause a runtime error... } catch ( e ) { // e holds the exception information // it is an instance of the exception class } The try/catch blocks can be nested. If the current function has no try/catch blocks, the calling function will be examined, and so on, until we find a try/catch block or exit the main function. If no try/catch block is found, an unhandled exception is reported.

It is also possible to throw an exception explicitly. Any object can be thrown. For example:

        throw 5;

will throw value '5'.

Classes

Classes can be declared the following way:

Inside the class, method functions are declared without the 'static' keyword. The method with the name of the class is the class constructor. For example:

Inside the class methods, the 'this' variable can be used to refer to the current object.

Only one constructor per class is allowed.

Class instances are created like this:

And object attributes (or fields) are accessed like this:

A new attribute is created upon assigning to it:

The following special method names exist:

Simple class inheritance is support. Derived classed are declared like this:

Here we declare the 'derived' class that is derived from the 'base' class. For derived classes, the base class constructor can be called explicitly:

If the base class constructor is not called explicitly, IDA will call it implicitly, without any arguments.

It is possible to call base class methods using full names:

The 'this' argument must be passed explicitly in this case.

When there are no more references to an object, it is automatically destroyed. We use a simple reference count algorithm to track the object use. Circularly dependent objects are not detected: they are never destroyed.

The following built-in object classes exist:

Predefined symbols

The following symbols are predefined in the IDC preprocessor:

These symbols are also defined when parsing C header files.

loader_input_t class

The loader_input_t class can read from input files. It has the following methods:

Instances of this class can be created by calling the open_loader_input function.

See other IDC classes.

Slices

The slice operator can be applied IDC objects are strings.

For strings, the slice operator denotes a substring:

Any indexes that are out of bounds are silently adjusted to correct values. If i1 >= i2, empty string is returned. Negative indexes are used to denote positions counting from the end of the string.

String slices can be used on the right side of an assignment. For example:

will replace 2 characters at the beginning of the string by "abc".

For objects, the slice operator denotes a subset of attributes. It can be used to emulate arrays:

x[i1:i2] denotes all attributes with numeric values between i1 and i2 (i2 is excluded).

Any non-numeric attributes are ignored by the slice operator.

IDC API Reference

Index of debugger related IDC functions

set_selector

enable_tracing

Enable step tracing
     trace_level - what kind of trace to modify
     enable      - 0: turn off, 1: turn on
Returns: success

success enable_tracing(long trace_level, long enable);

#define TRACE_STEP 0x0  // lowest level trace. trace buffers are not maintained
#define TRACE_INSN 0x1  // instruction level trace
#define TRACE_FUNC 0x2  // function level trace (calls & rets)
#define TRACE_BBLK 0x4  // basic block level trace

get_prev_fixup_ea

find previous address with fixup information
     ea - current address
returns: -1 - no more fixups
         otherwise returns the previous address with fixup information

long get_prev_fixup_ea(long ea);

del_segm

Delete a segment
  ea      - any address in the segment
  flags   - combination of SEGMOD_... flags

success del_segm(long ea, long flags);

#define SEGMOD_KILL    0x0001 // disable addresses if segment gets shrinked or deleted
#define SEGMOD_KEEP    0x0002 // keep information (code & data, etc)
#define SEGMOD_SILENT  0x0004 // be silent
#define SEGMOD_KEEP0   0x0008 // flag for internal use, don't set
#define SEGMOD_KEEPSEL 0x0010 // do not try to delete unused selector
#define SEGMOD_NOMOVE  0x0020 // don't move info from the start of segment to the new start address
                              // (for set_segm_start())
#define SEGMOD_SPARSE  0x0040 // use sparse storage if extending the segment
                              // (for set_segm_start(), set_segm_end())

get_bmask_cmt

end_type_updating

success end_type_updating(long utp);

Find

toggle_bnot

Toggle the bitwise not operator for the operand (for the explanations of 'ea' and 'n' please see ())

success toggle_bnot(long ea, int n);

patch_byte

Change value of a program byte
If debugger was active then the debugged process memory will be patched too
     ea    - linear address
     value - new value of the byte
Returns: 1 if the database has been modified,
         0 if either the debugger is running and the process' memory
           has value 'value' at address 'ea',
           or the debugger is not running, and the IDB
           has value 'value' at address 'ea already.

success patch_byte(long ea, long value);

get_module_info

Get a description of the module that contains the given ea
returned objct has attributes:
  "name"      - the full path of the module
  "base"      - module's base address
  "size"      - module size
  "rebase_to" - address the module was rebased to
                BADADDR if module was not rebased at all

object get_module_info(long ea);

set_member_name

change structure member name
     id            - structure type ID
     member_offset - offset of the member
     name          - new name of the member
returns: !=0 - ok.

long set_member_name(long id, long member_offset, string name);

create_float

Convert the current item to a floating point (4 bytes) ea - linear address returns: 1-ok, 0-failure This is a convenience macro, see also create_data() function

#define create_float(ea) create_data(ea, FF_FLOAT, 4, BADADDR)

del_struc_member

read_dbg_memory

Read from debugger memory
     ea - linear address
     size - size of data to read
returns: data as a string. If failed, If failed, throws an exception
Thread-safe function (may be called only from the main thread and debthread)

string read_dbg_memory(long ea, long size);

get_enum_width

getn_thread_name

del_struc

delete a structure type
     id - structure type ID
returns: 0 if bad structure type ID is passed
         1 otherwise the structure type is deleted. All data
           and other structure types referencing to the
           deleted structure type will be displayed as array of bytes.

success del_struc(long id);

filelength

get file length
     handle - file handle
returns: -1 - error
         otherwise file length in bytes
Thread-safe function.

long filelength(long handle);

set_manual_insn

Specify instruction representation manually.
     ea   - linear address
     insn - a string representation of the operand
IDA will not check the specified instruction, it will simply display
it instead of the original representation.

void set_manual_insn(long ea, string insn);

is_value...() functions

Check the variable type
Returns true if the variable type is the expected one
Thread-safe functions.

success value_is_string(var);
success value_is_long(var);
success value_is_float(var);
success value_is_object(var);
success value_is_func(var);
success value_is_pvoid(var);
success value_is_int64(var);

get_ip_val

del_extra_cmt

create_insn

op_offset_high16

Convert operand to a high offset High offset is the upper 16bits of an offset. This type is used by PPC, MIPS, and other RISC processors. (for the explanations of 'ea' and 'n' please see ()) target - the full value (all 32bits) of the offset

success op_offset_high16(long ea, int n, long target);

get_cmt

Get indented comment
     ea - linear address
     repeatable: 0-regular, !=0-repeatable comment

string get_cmt(long ea, long repeatable);

expand_struc

expand or shrink a structure type
     id     - structure type ID
     offset - offset in the structure
     delta  - how many bytes to add or remove
     recalc - recalculate the locations where
              the structure type is used
returns: !=0 - ok

success expand_struc(long id, long offset, long delta, long recalc);

get_idb_path

set_frame_size

get_file_ext

has_value

readshort

read 2 bytes from file
     handle    - file handle
     mostfirst - 0 least significant byte is first (intel)
                 1 most  significant byte is first
returns: -1 - error
         otherwise: a 16-bit value
Thread-safe function.

long readshort(long handle, long mostfirst);

sanitize_file_name

Sanitize the file name.
Remove the directory path, and replace wildcards ? * and chars<' ' with underscore.

string sanitize_file_name(string filename);

get_member_flag

get type of a member id - structure type ID member_offset - member offset. The offset can be any offset in the member. For example, is a member is 4 bytes long and starts at offset 2, then 2, 3, 4, 5 denote the same structure member. returns: -1 if bad structure type ID is passed or no such member in the structure otherwise returns type of the member, see bit definitions above. If the member type is a structure then function get_member_strid() should be used to get the structure type id.

long get_member_flag(long id, long member_offset);

create_struct

Create a structure data item at the specified address
     ea      - linear address
     size    - structure size in bytes. -1 means that the size
               will be calculated automatically
     strname - name of a structure type
returns: 1-ok, 0-failure

success create_struct(long ea, long size, string strname);

ARM specific

Some ARM compilers in Thumb mode use BL (branch-and-link)
instead of B (branch) for long jumps, since BL has more range.
By default, IDA tries to determine if BL is a jump or a call.
You can override IDA's decision using commands in Edit/Other menu
(Force BL call/Force BL jump) or the following two functions.

//  Force BL instruction to be a jump
//       ea - address of the BL instruction
//  returns: 1-ok, 0-failed

success force_bl_jump(long ea);

//  Force BL instruction to be a call
//       ea - address of the BL instruction
//  returns: 1-ok, 0-failed

success force_bl_call(long ea);

Disk Write Error

set_enum_member_cmt

set a comment of a symbolic constant
     const_id - id of const
     cmt     - new comment for the constant
     repeatable - 0:set regular comment
                  1:set repeatable comment
returns: 1-ok, 0-failed

success set_enum_member_cmt(long const_id, string cmt, long repeatable);

rename

rename a file
     oldname - existing file name
     newname - new file name
returns: error code from the system
Thread-safe function.

long rename(string oldname, string newname);

set_ida_state

get_member_size

msg

qbasename

get_enum_member_enum

get id of enum by id of constant
     const_id - id of symbolic constant
returns: id of enum the constant belongs to.
                        -1 if const_id is bad.

long get_enum_member_enum(long const_id);

auto_mark_range

Plan to perform an action in the future.
This function will put your request to a special autoanalysis queue.
Later IDA will retrieve the request from the queue and process
it. There are several autoanalysis queue types. IDA will process all
queries from the first queue and then switch to the second queue, etc.

// plan/unplan range of addresses
void auto_mark_range(long start, long end, long queuetype);
void auto_unmark(long start, long end, long queuetype);

// plan to analyze an address
#define auto_mark(ea, qtype)      auto_mark_range(ea, (ea)+1, qtype)

#define AU_UNK  10      // make unknown
#define AU_CODE 20      // convert to instruction
#define AU_PROC 30      // make function
#define AU_USED 40      // reanalyze
#define AU_LIBF 60      // apply a flirt signature (the current signature!)
#define AU_FINAL 200    // coagulate unexplored items

plan_to_apply_idasgn

set_named_type

Store a type in the til.
To replace the existing type use #NTF_REPLACE
     name    -  type name
     type    -  serialized type string
     fields  -  serialized type fields
     cmt     -  main type comment
     fldcmts -  serialized type field comments
     sclass  -  type storage class

tinfo_code_t set_named_type(
        string name,
        long ntf_flags,
        string type,
        string fields="",
        string cmt="",
        string fldcmts="",
        long sclass=0);

op_offset

Convert operand to a complex offset expression This is a more powerful version of op_plain_offset() function. It allows to explicitly specify the reference type (off8, off16, etc) and the expression target with a possible target delta. The complex expressions are represented by IDA in the following form:

        target + tdelta - base

If the target is not present, then it will be calculated using target = operand_value - tdelta + base The target must be present for LOW.. and HIGH.. reference types ea - linear address of the instruction/data n - number of operand to convert (the same as in op_plain_offset) reftype - one of REF_... constants target - an explicitly specified expression target. if you don't want to specify it, use -1. Please note that LOW... and HIGH... reference type require the target. base - the offset base (a linear address) tdelta - a displacement from the target which will be displayed in the expression.

success op_offset(long ea, int n, long reftype, long target, long base, long tdelta);

#define REF_OFF8 0 // 8bit full offset #define REF_OFF16 1 // 16bit full offset #define REF_OFF32 2 // 32bit full offset #define REF_LOW8 3 // low 8bits of 16bit offset #define REF_LOW16 4 // low 16bits of 32bit offset #define REF_HIGH8 5 // high 8bits of 16bit offset #define REF_HIGH16 6 // high 16bits of 32bit offset #define V695_REF_VHIGH 7 // obsolete #define V695_REF_VLOW 8 // obsolete #define REF_OFF64 9 // 64bit full offset // note: processor modules or plugins may register additional // custom reference types (for example, REF_HIGHA16 is // used by MIPS, SPARC, PPC, ALPHA, TRICORE, etc.) #define REFINFO_RVA 0x10 // based reference (rva) #define REFINFO_PASTEND 0x20 // reference past an item // it may point to an nonexistitng address // do not destroy alignment dirs #define REFINFO_NOBASE 0x80 // offset base is a number // implies that base have be any value // nb: base xrefs are created only if base // points to the middle of a segment #define REFINFO_SUBTRACT 0x0100 // the reference value is subtracted from // the base value instead of (as usual) // being added to it #define REFINFO_SIGNEDOP 0x0200 // the operand value is sign-extended (only // supported for REF_OFF8/16/32/64) #define REFINFO_NO_ZEROS 0x0400 ///< an opval of 0 will be considered invalid #define REFINFO_NO_ONES 0x0800 ///< an opval of ~0 will be considered invalid

rename_entry

rename entry point
     ordinal - entry point number
     name    - new name
returns: !=0 - ok

success rename_entry(long ordinal, string name);

strlen

Return length of a string in bytes
     str - input string
Returns: length (0..n)
Thread-safe function.

long strlen(string str);

get_extra_cmt

Get extra comment line
     ea - linear address
     n  - number of line (0..MAX_ITEM_LINES)
          MAX_ITEM_LINES is defined in IDA.CFG
To get anterior  line #n use (E_PREV + n)
To get posterior line #n use (E_NEXT + n)
Returns number 0 if the comment line does not exit

string get_extra_cmt(long ea, long n);

get_enum_flag

get flag of enum
     enum_id - ID of enum
returns: flags of enum. These flags determine representation
         of numeric constants (binary, octal, decimal, hex)
         in the enum definition. See start of this file for
         more information about flags.
         Returns 0 if enum_id is bad.

long get_enum_flag(long enum_id);

fgetc

read one byte from file
     handle  - file handle
returns: -1 - error
         otherwise a byte read.
Thread-safe function.

long fgetc(long handle);

Internal Error

op_stkvar

Convert operand to a stack variable (for the explanations of 'ea' and 'n' please see op_bin())

success op_stkvar(long ea, int n);

get_last_index

get index of the last existing array element
     tag     - tag of array (AR_LONG or AR_STR)
     id      - array id
returns: -1 - array is empty
         otherwise returns index of the last array element

long get_last_index(long tag, long id);

get_field_ea

Get address of the specified field using the type information
     ea         - address of the structure
     field_name - name of the structure field
If the database contains a structure at the specified ea and the
type information is present, this function will return the address of the
structure field.

long get_field_ea(long ea, string field_name);

For example:

  .data:00413060 errtable        dd 1   ; oscode
  .data:00413060                 dd 16h ; errnocode

        msg("address is: %x\n", _errtable.errnocode);

prints 413064. The "_errtable.errnocode" expression is essentially a shortcut for:

get_field_ea(get_name_ea_simple("_errtable"), "errnocode")

get_last_struc_idx

get index of last structure type none returns: -1 if no structure type is defined index of last structure type. See get_first_struc_idx() for the explanation of structure indices and IDs.

long get_last_struc_idx();

How to use the help subsystem

get_struc_id

get structure ID by structure name
     structure type name
returns: -1 if bad structure type name is passed
         otherwise returns structure ID.

long get_struc_id(string name);

select_thread

Select the given thread as the current debugged thread.
     tid - ID of the thread to select
The process must be suspended to select a new thread.
returns: success

success select_thread(long tid);

create_array

get_struc_cmt

get structure type comment
     id         - structure type ID
     repeatable - 1: get repeatable comment
                  0: get regular comment
returns: 0 if bad structure type ID is passed
         otherwise returns comment.

string get_struc_cmt(long id, long repeatable);

set_array_string

set_func_attr

set_storage_type

get_struc_size

get size of a structure
     id         - structure type ID
returns: 0 if bad structure type ID is passed
         otherwise returns size of structure in bytes.

long get_struc_size(long id);

demangle_name

get_next_fixup_ea

find next address with fixup information
     ea - current address
returns: -1 - no more fixups
         otherwise returns the next address with fixup information

long get_next_fixup_ea(long ea);

get_next_bmask

get next bitmask in the enum (bitfield)
     enum_id - id of enum
     bmask   - value of the current bitmask
returns: value of a bitmask with value higher than the specified
         value. -1 if no such bitmasks exist.
         All bitmasks are sorted by their values as unsigned longs.

long get_next_bmask(long enum_id, long value);

delattr

Del object attribute
     self  - object
     attr  - attribute name
Thread-safe function.

success delattr(object self, string attr);

gen_simple_call_chart

Generate a function call graph GDL file
     outfile - output file name. GDL extension will be used
     title   - graph title
     ea1     - beginning of the range to flow chart
     ea2     - end of the range to flow chart. if ea2 == BADADDR
               then ea1 is treated as an address within a function.
               That function will be flow charted.
     flags   - combination of CHART_GEN_GDL, CHART_WINGRAPH, CHART_NOLIBFUNCS

success gen_simple_call_chart(string outfile, string title, long flags);

patch_qword

Change value of a quad word
     ea    - linear address
     value - new value of the quad word
Returns: 1 if the database has been modified,
         0 if either the debugger is running and the process' memory
           has value 'value' at address 'ea',
           or the debugger is not running, and the IDB
           has value 'value' at address 'ea' already.

success patch_qword(long ea, long value);

get_enum_name

get name of enum
     enum_id - ID of enum
returns: name of enum or empty string

string get_enum_name(long enum_id);

loader_input_t.getc

Read one byte from the input file
Returns -1 if no more bytes

long loader_input_t.getc();

get_first_struc_idx

get_debugger_event_cond

Return the debugger event condition

returns: event condition

string get_debugger_event_cond();

read_dbg_qword

Get value of program quadro word (8 bytes) using the debugger memory
     ea - linear address
returns: the value of the quadro word. If failed, throws an exception
Thread-safe function (may be called only from the main thread and debthread)

long read_dbg_qword(long ea);

define_local_var

generate_disasm_line

add_idc_hotkey

Add hotkey for IDC function
     hotkey  - hotkey name ('a', "Alt-A", etc)
     idcfunc - IDC function name
returns:
#define IDCHK_OK        0       // ok
#define IDCHK_ARG       -1      // bad argument(s)
#define IDCHK_KEY       -2      // bad hotkey name
#define IDCHK_MAX       -3      // too many IDC hotkeys

long add_idc_hotkey(string hotkey, string idcfunc);

tolower

Convert string to lowercase
     str    - input string
returns: lowercase string
Thread-safe function.

string tolower(string str);

del_selector

delete a selector
        arguments:      sel - the selector number to delete
        returns:        nothing
        note:           if the selector is found, it will
                        be deleted

void del_selector(long sel);

set_debugger_event_cond

Set a new debugger event condition

string set_debugger_event_cond(string condition);

get_imagebase

Get base address of the input file

long get_imagebase();