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.

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.

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:

• Variables

• Functions

• Statements

• Expressions

• Predefined symbols

• Slices

• Exceptions

• Index of IDC functions

• Index of debugger related IDC functions

Classes can be declared the following way:

  class name
  {
    method1(...) {}
    ...
  };

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:

  class myclass
  {
     myclass(x,y)
     {
       print("myclass constructor has been called with two arguments: ", x, y);
       this.x = x;
       this.y = x;
     }
     ~myclass()
     {
       print("destructor has been called: ", this);
     }
  };

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:

  o = myclass(1, 2);

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

  print(o.x);
  o.y = o.x + 1;

A new attribute is created upon assigning to it:

  o.new_attr = 1;

Accessing an unexisting attribute generates an exception, which can be caught.

The following special method names exist:

  __setattr__(attr, value)
    This method is called when an object attribute is assigned a new value.
    Instead of assigning a value, this method can do something else.
    To modify a class attribute from this method, please use the setattr()
    global function.
    Compare with: Python _setattr_ method

  __getattr__(attr)
    This method is called when an object attribute is accessed for reading.
    Instead of simply returning a value, this method can do something else,
    for example to calculate the attribute on the fly. To retrieve a
    attribute from this function, use the getattr() global function.
    Compare with: Python _getattr_ method

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

  class derived : base
  {
    ...
  };

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

  class derived : base
  {
    derived() : base(args...)
    {
    }
  };

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:

    base::func(this, args...);

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:

  - object: the default base class for all new classes. When the base class
    is not specified, the new class will inherit from 'object'
    This class has no fields and no special constructor. It has the following
    methods:

• void object.store(typeinfo, ea, flags)

• void object.retrieve(typeinfo, ea, flags)

  Copy

  - exception: class used to report exceptions. It has the following attributes:
  
    file - source file name where the exception occurred
    func - current function name
    line - line number
    pc   - program counter value (internal to idc)
  
    Runtime errors are reported as exceptions too. They are two more fields:
  
    qerrno      - runtime error code
    description - printable error description
  
    This class has no special constructor and has no methods.
  
  - typeinfo: class used to represent type info. It has the following attributes:
  
    type        - binary encoded type string
    fields      - field names for the type (e.g. structure member names)
    name        - (optional) variable/function name

Human readable form of the typeinfo can be obtained by calling the print() method. The type size can be calculated using the size() method.

• loader_input_t: class to read files.

The following symbols are predefined in the IDC preprocessor:

  _NT_           IDA is running under MS Windows
  _LINUX_        IDA is running under Linux
  _MAC_          IDA is running under Mac OS X
  _UNIX_         IDA is running under Unix (linux or mac)
  _EA64_         64-bit version IDA
  _QT_           GUI version of IDA (Qt)
  _GUI           GUI version of IDA
  _TXT_          Text version of IDA
  _IDA_VERSION_  The current IDA version. For example: "8.4"
  _IDAVER_       The current, numerical IDA version. For example: "840" means v8.4

These symbols are also defined when parsing C header files.

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

  complex assignment operations as '+='

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

There are four type conversion operations:

  long(expr)  floating point numbers are truncated during conversion
  char(expr)
  float(expr)
  __int64(expr)

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

  - addition:
        if both operands are strings,
          string addition is performed (strings are concatenated);
        if both operands are objects,
          object combination is performed (a new object is created)
        if floating point operand exists,
          both operands are converted to floats;
        otherwise
          both operands are converted to longs;

  - subtraction/multiplication/division:
        if floating point operand exists,
          both operands are converted to floats;
        if both operands are objects and the operation is subtraction,
          object subtraction is performed (a new object is created)
        otherwise
          both operands are converted to longs;

  - comparisons (==,!=, etc):
        if both operands are strings, string comparison is performed;
        if floating point operand exists,
          both operands are converted to floats;
        otherwise
          both operands are converted to numbers;

  - all other operations:
        operand(s) are converted to longs;

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:

        auto x, r;
        r = &x;
        r = 1;   // x is equal to 1 now

References to references are immediately resolved:

        auto x, r1, r2;
        r1 = &x;
        r2 = &r1; // r2 points to x

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

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

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

• built-in functions

• user-defined functions A user-defined function is declared this way: static func(arg1,arg2,arg3) { statements ... } 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:

  - objects are always passed by reference
  - functions are always passed by reference
  - it is possible to pass a variable by reference using the & operator

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

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"

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

• long read(vref buf, long size);

• long size();

• long seek(long pos, long whence);

• long tell();

• string gets(long maxsize);

• string getz(long pos, long maxsize);

• long getc();

• long readbytes(vref result, long size, long mf);

• void close();

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

See other IDC classes.

The slice operator can be applied IDC objects are strings.

For strings, the slice operator denotes a substring:

  str[i1:i2] - substring from i1 to i2. i2 is excluded
  str[idx]   - one character substring at 'idx'.
               this is equivalent to str[idx:idx+1]
  str[:idx]  - substring from the beginning of the string to idx
               this is equivalent to str[0:idx]
  str[idx:]  - substring from idx to the end of the string
               this is equivalent to str[idx:0x7fffffff]

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:

  str[0:2] = "abc";

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:

  auto x = object();
  x[0] = value1;
  x[1] = "value2";

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.