Our IDA SDK exposes API in the form of C++ libraries and header files, allowing you you to create custom processor modules and plugins, automate tasks, or integrate new features directly into IDA. Our IDA API is defined and organized by the contents of the header files, that you can browse in our IDA C++ SDK Reference.

Typical use cases

With IDA SDK, you can develop loaders for unsupported binary formats or custom processors modules to disassemble and analyze non-standard files. What's more, you can write plugins to perform complex, automated tasks and more, allowing you to go far beyong the basic IDC scripting.

IDAPython allows you to use the Python code in IDA to write scripts and customize basic IDA functionality. It offers more advanced and powerful automation than the IDC language and gives you access to Python modules and native Python abilities to interact with our API.

Typical use cases

When you are asking yourself how to automate work in IDA, like renaming variables or performing custom analyses, the IDAPython API comes in handy. You can use simple code snippets directly inside the IDA output window to perform specific tasks or more advanced scripts for complex usage. Moreover, with IDAPython, you can write plugins to expand basic IDA capabilities even further.

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

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"

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.

Below is the full source code of a sample plugin. It performs a quite useful transformation of the pseudocode: replaces zeroes in pointer contexts with NULLs. A NULL immediately conveys the idea that the current expression is pointer-related. This is especially useful for unknown function arguments.

The plugin is fully automatic. It hooks to the decompiler events and waits for the pseudocode to be ready. At that moment it takes control and modifies the ctree.

The conversion is performed by the convert_zeroes() function. It visits all expressions of the ctree and checks for pointer contexts. If a expression has a pointer type, then the make_null_if_zero() function is called for it. This function checks if the expression is a zero constant and converts it if necessary.

The plugin can be turned on or off by its menu item in the Plugins submenu.

The code is short and straightforward. Use it as a template for your plugins.

\

/*
 *      Hex-Rays Decompiler project
 *      Copyright (c) 2007-2019 by Hex-Rays, support@hex-rays.com
 *      ALL RIGHTS RESERVED.
 *
 *      Sample plugin for Hex-Rays Decompiler.
 *      It automatically replaces zeroes in pointer contexts with NULLs.
 *      For example, expression like
 *
 *              funcptr = 0;
 *
 *      will be displayed as
 *
 *              funcptr = NULL;
 *
 *      Due to highly dynamic nature of the decompier output, we must
 *      use the decompiler events to accomplish the task. The plugin will
 *      wait for the ctree structure to be ready in the memory and will
 *      replace zeroes in pointer contexts with NULLs.
 *
 */

#include <hexrays.hpp>

// Hex-Rays API pointer
hexdsp_t *hexdsp = NULL;

static bool inited = false;

static const char nodename[] = “$ hexrays NULLs”;
static const char null_type[] = “MACRO_NULL”;
//————————————————————————–
// Is the plugin enabled?
// The user can disable it. The plugin will save the on/off switch in the
// current database.
static bool is_enabled(void)
{
  netnode n(nodename); // use a netnode to save the state
  return n.altval(0) == 0; // if the long value is positive, then disabled
}

//————————————————————————–
// If the expression is zero, convert it to NULL
static void make_null_if_zero(cexpr_t *e)
{
  if ( e->is_zero_const() && !e->type.is_ptr() )
  { // this is plain zero, convert it
    number_format_t &nf = e->n->nf;
    nf.flags = enum_flag();
    nf.serial = 0;
    nf.type_name = null_type;
    e->type = tinfo_t::get_stock(STI_PVOID);
  }
}

//————————————————————————–
// Convert zeroes of the ctree to NULLs
static void convert_zeroes(cfunc_t *cfunc)
{
  // To represent NULLs, we will use the MACRO_NULL enumeration
  // Normally it is present in the loaded tils but let’s verify it
  if ( !get_named_type(NULL, null_type, NTF_TYPE) )
  {
    msg(“%s type is missing, cannot convert zeroes to NULLs\n”, null_type);
    return;
  }

  // We derive a helper class from ctree_visitor_t
  // The ctree_visitor_t is a base class to derive
  // ctree walker classes.
  // You have to redefine some virtual functions
  // to do the real job. Here we redefine visit_expr() since we want
  // to examine and modify expressions.
  struct ida_local zero_converter_t : public ctree_visitor_t
  {
    zero_converter_t(void) : ctree_visitor_t(CV_FAST) {}
    int idaapi visit_expr(cexpr_t *e)
    {
      // verify if the current expression has pointer expressions
      // we handle the following patterns:
      //  A. ptr = 0;
      //  B. func(0); where argument is a pointer
      //  C. ptr op 0 where op is a comparison
      switch ( e->op )
      {
        case cot_asg:   // A
          if ( e->x->type.is_ptr() )
            make_null_if_zero(e->y);
          break;

        case cot_call:  // B
          {
            carglist_t &args = *e->a;
            for ( int i=0; i < args.size(); i++ ) // check all arguments
            {
              carg_t &a = args[i];
              if ( a.formal_type.is_ptr_or_array() )
                make_null_if_zero(&a);
            }
          }
          break;

        case cot_eq:    // C
        case cot_ne:
        case cot_sge:
        case cot_uge:
        case cot_sle:
        case cot_ule:
        case cot_sgt:
        case cot_ugt:
        case cot_slt:
        case cot_ult:
          // check both sides for zeroes
          if ( e->y->type.is_ptr() )
            make_null_if_zero(e->x);
          if ( e->x->type.is_ptr() )
            make_null_if_zero(e->y);
          break;

        default:
          break;

      }
      return 0; // continue walking the tree
    }
  };
  zero_converter_t zc;
  // walk the whole function body
  zc.apply_to(&cfunc->body, NULL);
}

//————————————————————————–
// This callback will detect when the ctree is ready to be displayed
// and call convert_zeroes() to create NULLs
static ssize_t idaapi callback(void *, hexrays_event_t event, va_list va)
{
  if ( event == hxe_maturity )
  {
    cfunc_t *cfunc = va_arg(va, cfunc_t*);
    ctree_maturity_t mat = va_argi(va, ctree_maturity_t);
    if ( mat == CMAT_FINAL ) // ctree is ready, time to convert zeroes to NULLs
      convert_zeroes(cfunc);
  }
  return 0;
}

//————————————————————————–
// Initialize the plugin.
int idaapi init(void)
{
  if ( !init_hexrays_plugin() )
    return PLUGIN_SKIP; // no decompiler
  if ( is_enabled() ) // null plugin is enabled?
  {
    install_hexrays_callback(callback, NULL);
    const char *hxver = get_hexrays_version();
    msg(“Hex-rays version %s has been detected, %s ready to use\n”, hxver, PLUGIN.wanted_name);
  }
  inited = true;
  return PLUGIN_KEEP;
}

//————————————————————————–
void idaapi term(void)
{
  if ( inited )
  {
    // clean up
    remove_hexrays_callback(callback, NULL);
    term_hexrays_plugin();
  }
}

//————————————————————————–
bool idaapi run(size_t)
{
  // since all real work is done in the callbacks, use the main plugin entry
  // to turn it on and off.
  // display a message explaining the purpose of the plugin:
  int code = askbuttons(
       “~E~nable”,
       “~D~isable”,
       “~C~lose”,
       –1,
       “AUTOHIDE NONE\n”
       “Sample plugin for Hex-Rays decompiler.\n”
       “\n”
       “This plugin is fully automatic.\n”
       “It detects zeroes in pointer contexts and converts them into NULLs.\n”
       “\n”
       “The current state of the plugin is: %s\n”,
       is_enabled() ? “ENABLED” : “DISABLED”);
  switch ( code )
  {
    case –1:    // close
      break;
    case 0:     // disable
    case 1:     // enable
      netnode n;
      n.create(nodename);
      n.altset(0, code == 0);
      if ( code )
        install_hexrays_callback(callback, NULL);
      else
        remove_hexrays_callback(callback, NULL);
      info(“The %s plugin has been %s.”, PLUGIN.wanted_name, code ? “ENABLED” : “DISABLED”);
      break;
  }
  return true;
}

//————————————————————————–
static char comment[] = “Sample2 plugin for Hex-Rays decompiler”;

//————————————————————————–
//
//      PLUGIN DESCRIPTION BLOCK
//
//————————————————————————–
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  0,                    // plugin flags
  init,                 // initialize
  term,                 // terminate. this pointer may be NULL.
  run,                  // invoke plugin
  comment,              // long comment about the plugin
                        // it could appear in the status line
                        // or as a hint
  “”,                   // multiline help about the plugin
  “Hex-Rays NULL converter”, // the preferred short name of the plugin
  “”                    // the preferred hotkey to run the plugin
};

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?

Welcome to the Hex-Rays Developer Guide, where you can learn how to enhance IDA's capabilities and extend its features.

Utilize scripting options with the IDC language (IDA's native language) or IDAPython, or delve deeper into our SDK to build advanced modules and plugins.

Reference documentation

Check our reference documentation for C++ SDK and IDAPython.

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

will throw value '5'.

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.

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:

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.

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

See other IDC .

In IDC there are the following statements: ; (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... } throw <expr>; ; (empty statement) Please note that the 'switch' statement is not supported.

The following symbols are predefined in the IDC preprocessor:

These symbols are also defined when parsing C header files.

The following conventions are used in the function descriptions:

success end_type_updating(long utp);

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 () function

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

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

success toggle_bnot(long ea, int n);