idc.py

The sources of IDAPython, a plugin for IDA for using python for scripting in IDA, instead of IDC.

def ApplySig(name):
    """
    Load (plan to apply) a FLIRT signature file

    @param name:  signature name without path and extension

    @return: 0 if could not load the signature file, !=0 otherwise
    """
    return idaapi.plan_to_apply_idasgn(name)


#----------------------------------------------------------------------------
#      C H A N G E   P R O G R A M   R E P R E S E N T A T I O N
#----------------------------------------------------------------------------


def DeleteAll():
    """
    Delete all segments, instructions, comments, i.e. everything
    except values of bytes.
    """
    ea = idaapi.cvar.inf.minEA

    # Brute-force nuke all info from all the heads
    while ea != BADADDR and ea <= idaapi.cvar.inf.maxEA:
        idaapi.del_local_name(ea)
        idaapi.del_global_name(ea)
        func = idaapi.get_func(ea)
        if func: 
            idaapi.del_func_cmt(func, False)
            idaapi.del_func_cmt(func, True)
            idaapi.del_func(ea)
        idaapi.del_hidden_area(ea)    
        seg = idaapi.getseg(ea)
        if seg:
            idaapi.del_segment_cmt(seg, False)
            idaapi.del_segment_cmt(seg, True)
            idaapi.del_segm(ea, idaapi.SEGDEL_KEEP | idaapi.SEGDEL_SILENT)

        ea = idaapi.next_head(ea, idaapi.cvar.inf.maxEA)


def MakeCode(ea):
    """
    Create an instruction at the specified address

    @param ea: linear address

    @return: 0 - can not create an instruction (no such opcode, the instruction
    would overlap with existing items, etc) otherwise returns length of the
    instruction in bytes
    """
    return idaapi.ua_code(ea)


def AnalyzeArea(sEA, eEA):
    """
    Perform full analysis of the area

    @param sEA: starting linear address
    @param eEA: ending linear address (excluded)

    @return: 1-ok, 0-Ctrl-Break was pressed.
    """
    return idaapi.analyze_area(sEA, eEA)


def MakeNameEx(ea, name, flags):
    """
    Rename an address

    @param ea: linear address
    @param name: new name of address. If name == "", then delete old name
    @param flags: combination of SN_... constants

    @return: 1-ok, 0-failure
    """
    return idaapi.set_name(ea, name, flags)

SN_CHECK      = idaapi.SN_CHECK    # Fail if the name contains invalid 
                                   # characters
                                   # If this bit is clear, all invalid chars
                                   # (those !is_ident_char()) will be replaced
                                   # by SubstChar (usually '_')
                                   # List of valid characters is defined in 
                                   # ida.cfg
SN_NOCHECK    = idaapi.SN_NOCHECK  # Replace invalid chars with SubstChar
SN_PUBLIC     = idaapi.SN_PUBLIC   # if set, make name public
SN_NON_PUBLIC = idaapi.SN_NON_PUBLIC # if set, make name non-public
SN_WEAK       = idaapi.SN_WEAK     # if set, make name weak
SN_NON_WEAK   = idaapi.SN_NON_WEAK # if set, make name non-weak
SN_AUTO       = idaapi.SN_AUTO     # if set, make name autogenerated
SN_NON_AUTO   = idaapi.SN_NON_AUTO # if set, make name non-autogenerated
SN_NOLIST     = idaapi.SN_NOLIST   # if set, exclude name from the list
                                   # if not set, then include the name into
                                   # the list (however, if other bits are set,
                                   # the name might be immediately excluded
                                   # from the list)
SN_NOWARN     = idaapi.SN_NOWARN   # don't display a warning if failed
SN_LOCAL      = idaapi.SN_LOCAL    # create local name. a function should exist.
                                   # local names can't be public or weak.
                                   # also they are not included into the list 
                                   # of names they can't have dummy prefixes

def MakeComm(ea, comment):
    """
    Set an indented regular comment of an item

    @param ea: linear address
    @param comment: comment string

    @return: None
    """
    return idaapi.set_cmt(ea, comment, 0)


def MakeRptCmt(ea, comment):
    """
    Set an indented repeatable comment of an item

    @param ea: linear address
    @param comment: comment string

    @return: None
    """
    return idaapi.set_cmt(ea, comment, 1)


def MakeArray(ea, nitems):
    """
    Create an array.

    @param ea: linear address
    @param nitems: size of array in items

    @note: This function will create an array of the items with the same type as
    the type of the item at 'ea'. If the byte at 'ea' is undefined, then
    this function will create an array of bytes.
    """
    flags = idaapi.getFlags(ea)

    if idaapi.isUnknown(flags):
        flags = idaapi.FF_BYTE

    if idaapi.isStruct(flags):
        ti = idaapi.typeinfo_t()
        assert idaapi.get_typeinfo(ea, 0, flags, ti), "get_typeinfo() failed"
        itemsize = idaapi.get_data_elsize(ea, flags, ti)
        tid = ti.tid
    else:
        itemsize = idaapi.get_item_size(ea)
        tid = BADADDR

    return idaapi.do_data_ex(ea, flags, itemsize*nitems, tid)


def MakeStr(ea, endea):
    """
    Create a string.

    This function creates a string (the string type is determined by the
    value of GetLongPrm(INF_STRTYPE))
    
    @param ea: linear address
    @param endea: ending address of the string (excluded)
        if endea == BADADDR, then length of string will be calculated
        by the kernel
    
    @return: 1-ok, 0-failure

    @note: The type of an existing string is returned by GetStringType()
    """
    return idaapi.make_ascii_string(ea, endea - ea, GetLongPrm(INF_STRTYPE))    


def MakeData(ea, flags, size, tid):
    """
    Create a data item at the specified address
    
    @param ea: linear address
    @param flags: FF_BYTE..FF_PACKREAL
    @param size: size of item in bytes
    @param tid: for FF_STRU the structure id

    @return: 1-ok, 0-failure
    """
    raise NotImplementedError, "Use the Make* functions to create data items"


def MakeByte(ea):
    """
    Convert the current item to a byte

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doByte(ea, 1)


def MakeWord(ea):
    """
    Convert the current item to a word (2 bytes)

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doWord(ea, 2)


def MakeDword(ea):
    """
    Convert the current item to a double word (4 bytes)

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doDwrd(ea, 4)


def MakeQword(ea):
    """
    Convert the current item to a quadro word (8 bytes)

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doQwrd(ea, 8)


def MakeOword(ea):
    """
    Convert the current item to a octa word (16 bytes)

    @param ea: linear address
    
    @return: 1-ok, 0-failure
    """
    return idaapi.doOwrd(ea, 16)


def MakeFloat(ea):
    """
    Convert the current item to a floating point (4 bytes)

    @param ea: linear address
    
    @return: 1-ok, 0-failure
    """
    return idaapi.doFloat(ea, 4)


def MakeDouble(ea):
    """
    Convert the current item to a double floating point (8 bytes)

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doDouble(ea, 8)


def MakePackReal(ea):
    """
    Convert the current item to a packed real (10 or 12 bytes)

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doPackReal(ea, idaapi.cvar.ph.tbyte_size)


def MakeTbyte(ea):
    """
    Convert the current item to a tbyte (10 or 12 bytes)

    @param ea: linear address

    @return: 1-ok, 0-failure
    """
    return idaapi.doTbyt(ea, idaapi.cvar.ph.tbyte_size)


def MakeStructEx(ea, size, strname):
    """
    Convert the current item to a structure instance

    @param ea: linear address
    @param size: structure size in bytes. -1 means that the size
        will be calculated automatically
    @param strname: name of a structure type

    @return: 1-ok, 0-failure
    """
    strid = idaapi.get_struc_id(strname)

    # FIXME: This should be changed to BADNODE
    if strid == 0xFFFFFFFF:
        return False

    if size == -1:
        size = idaapi.get_struc_size(strid)

    return idaapi.doStruct(ea, size, strid)    


def MakeAlign(ea, count, align):
    """
    Convert the current item to an alignment directive

    @param ea: linear address
    @param count: number of bytes to convert
    @param align: 0 or 1..32
              if it is 0, the correct alignment will be calculated
              by the kernel

    @return: 1-ok, 0-failure
    """
    return idaapi.doAlign(ea, count, align)


def MakeLocal(start, end, location, name):
    """
    Create a local variable

    @param start: start of address range for the local variable
    @param end: end of address range for the local variable
    @param location: the variable location in the "[bp+xx]" form where xx is
                     a number. The location can also be specified as a 
                     register name.
    @param name: name of the local variable

    @return: 1-ok, 0-failure

    @note: For the stack variables the end address is ignored.
           If there is no function at 'start' then this function.
           will fail.
    """
    func = idaapi.get_func(start)

    if not func:
        return 0

    # Find out if location is in the [bp+xx] form
    r = re.compile("\[([a-z]+)([-+][0-9a-fx]+)", re.IGNORECASE)
    m = r.match(location)

    if m:
        # Location in the form of [bp+xx]
        register = idaapi.str2reg(m.group(1))
        offset = int(m.group(2), 0)
        frame = idaapi.get_frame(func)

        if register == -1 or not frame:
            return 0

        offset += func.frsize
        member = idaapi.get_member(frame, offset)

        if member:
            # Member already exists, rename it
            if idaapi.set_member_name(frame, offset, name):
                return 1
            else:
                return 0
        else:
            # No member at the offset, create a new one
            if idaapi.add_struc_member(frame,
                                       name,
                                       offset,
                                       idaapi.byteflag(),
                                       None, 1) == 0:
                return 1
            else:
                return 0
    else:
        # Location as simple register name
        return idaapi.add_regvar(func, start, end, location, name, None)


def MakeUnkn(ea, flags):
    """
    Convert the current item to an explored item

    @param ea: linear address
    @param flags: combination of DOUNK_* constants

    @return: None
    """
    return idaapi.do_unknown(ea, flags)


def MakeUnknown(ea, size, flags):
    """
    Convert the current item to an explored item

    @param ea: linear address
    @param size: size of the range to undefine (for MakeUnknown)
    @param flags: combination of DOUNK_* constants

    @return: None
    """
    return idaapi.do_unknown_range(ea, size, flags)


DOUNK_SIMPLE   = idaapi.DOUNK_SIMPLE   # simply undefine the specified item
DOUNK_EXPAND   = idaapi.DOUNK_EXPAND   # propogate undefined items, for example
                                       # if removing an instruction removes all
                                       # references to the next instruction, then
                                       # plan to convert to unexplored the next
                                       # instruction too.
DOUNK_DELNAMES = idaapi.DOUNK_DELNAMES # delete any names at the specified address(es)


def OpBinary(ea, n):
    """
    Convert an operand of the item (instruction or data) to a binary number

    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand
        - 1 - the second, third and all other operands
        - -1 - all operands

    @return: 1-ok, 0-failure

    @note: the data items use only the type of the first operand
    """
    return idaapi.op_bin(ea, n)


def OpOctal(ea, n):
    """
    Convert an operand of the item (instruction or data) to an octal number

    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand