idc.py

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

        - 1 - the second, third and all other operands
        - -1 - all operands
    """
    return idaapi.op_oct(ea, n)


def OpDecimal(ea, n):
    """
    Convert an operand of the item (instruction or data) to a decimal 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 idaapi.op_dec(ea, n)


def OpHex(ea, n):
    """
    Convert an operand of the item (instruction or data) to a hexadecimal 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 idaapi.op_hex(ea, n)


def OpChr(ea, n):
    """
    @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 idaapi.op_chr(ea, n)


def OpOff(ea, n, base):
    """
    Convert operand to an offset
    (for the explanations of 'ea' and 'n' please see OpBinary())
    
    Example:
    ========

        seg000:2000 dw      1234h
    
        and there is a segment at paragraph 0x1000 and there is a data item
        within the segment at 0x1234:
        
        seg000:1234 MyString        db 'Hello, world!',0
        
        Then you need to specify a linear address of the segment base to
        create a proper offset:
        
        OpOffset(["seg000",0x2000],0,0x10000);
        
        and you will have:
        
        seg000:2000 dw      offset MyString
    
    Motorola 680x0 processor have a concept of "outer offsets".
    If you want to create an outer offset, you need to combine number
    of the operand with the following bit:

    Please note that the outer offsets are meaningful only for
    Motorola 680x0.

    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand
        - 1 - the second, third and all other operands
        - -1 - all operands
    @param base: base of the offset as a linear address
        If base == BADADDR then the current operand becomes non-offset
    """
    return idaapi.set_offset(ea, n, base)


OPND_OUTER = idaapi.OPND_OUTER # outer offset base


def OpOffEx(ea, n, reftype, target, base, tdelta):
    """
    Convert operand to a complex offset expression
    This is a more powerful version of OpOff() 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

    @param ea: linear address of the instruction/data
    @param n: number of operand to convert (the same as in OpOff)
    @param reftype: one of REF_... constants
    @param target: an explicitly specified expression target. if you don't
              want to specify it, use -1. Please note that LOW... and
              HIGH... reference type requre the target.
    @param base: the offset base (a linear address)
    @param tdelta: a displacement from the target which will be displayed
              in the expression.

    @return: success (boolean)
    """
    return idaapi.op_offset(ea, n, reftype, target, base, tdelta)


REF_OFF8    = idaapi.REF_OFF8    # 8bit full offset
REF_OFF16   = idaapi.REF_OFF16   # 16bit full offset
REF_OFF32   = idaapi.REF_OFF32   # 32bit full offset
REF_LOW8    = idaapi.REF_LOW8    # low 8bits of 16bit offset
REF_LOW16   = idaapi.REF_LOW16   # low 16bits of 32bit offset
REF_HIGH8   = idaapi.REF_HIGH8   # high 8bits of 16bit offset
REF_HIGH16  = idaapi.REF_HIGH16  # high 16bits of 32bit offset
REF_VHIGH   = idaapi.REF_VHIGH   # high ph.high_fixup_bits of 32bit offset (processor dependent)
REF_VLOW    = idaapi.REF_VLOW    # low  (32-ph.high_fixup_bits) of 32bit offset (processor dependent)
REF_OFF64   = idaapi.REF_OFF64   # 64bit full offset
REFINFO_RVA     = 0x10 # based reference (rva)
REFINFO_PASTEND = 0x20 # reference past an item it may point to an nonexistitng
                       # do not destroy alignment dirs
REFINFO_NOBASE  = 0x80 # offset base is a number
                       # that base have be any value
                       # nb: base xrefs are created only if base
                       # points to the middle of a segment


def OpSeg(ea, n):
    """
    Convert operand to a segment expression

    @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 idaapi.op_seg(ea, n)


def OpNumber(ea, n):
    """
    Convert operand to a number (with default number base, radix)

    @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 idaapi.op_num(ea, n)


def OpAlt(ea, n, opstr):
    """
    Specify operand represenation manually.

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

    @note: IDA will not check the specified operand, it will simply display
    it instead of the orginal representation of the operand.
    """
    return idaapi.set_forced_operand(ea, n, opstr)


def OpSign(ea, n):
    """
    Change sign of the operand

    @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 idaapi.toggle_sign(ea, n)


def OpNot(ea, n):
    """
    Toggle the bitwise not operator for the operand

    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand
        - 1 - the second, third and all other operands
        - -1 - all operands
    """
    idaapi.toggle_bnot(ea, n)
    return True


def OpEnumEx(ea, n, enumid, serial):
    """
    Convert operand to a symbolic constant

    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand
        - 1 - the second, third and all other operands
        - -1 - all operands
    @param enumid: id of enumeration type
    @param serial: serial number of the constant in the enumeration
             The serial numbers are used if there are more than
             one symbolic constant with the same value in the
             enumeration. In this case the first defined constant
             get the serial number 0, then second 1, etc.
             There could be 256 symbolic constants with the same
             value in the enumeration.
    """
    return idaapi.op_enum(ea, n, enumid, serial)


def OpStroffEx(ea, n, strid, delta):
    """
    Convert operand to an offset in a structure
    
    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand
        - 1 - the second, third and all other operands
        - -1 - all operands
    @param strid: id of a structure type
    @param delta: struct offset delta. usually 0. denotes the difference
                    between the structure base and the pointer into the structure.

    """
    path = idaapi.tid_array(1)
    path[0] = strid
    return idaapi.op_stroff(ea, n, path.cast(), 1, delta)


def OpStkvar(ea, n):
    """
    Convert operand to a stack variable
    
    @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 idaapi.op_stkvar(ea, n)


def OpHigh(ea, n, target):
    """
    Convert operand to a high offset
    High offset is the upper 16bits of an offset.
    This type is used by TMS320C6 processors (and probably by other
    RISC processors too)

    @param ea: linear address
    @param n: number of operand
        - 0 - the first operand
        - 1 - the second, third and all other operands
        - -1 - all operands
    @param target: the full value (all 32bits) of the offset
    """
    return idaapi.op_offset(ea, n, idaapi.REF_HIGH16, target)


def MakeVar(ea):
    """
    Mark the location as "variable"

    @param ea: address to mark

    @return: None

    @note: All that IDA does is to mark the location as "variable". 
    Nothing else, no additional analysis is performed.
    This function may disappear in the future.
    """
    idaapi.doVar(ea, 1)


def ExtLinA(ea, n, line):
    """
    Specify an additional line to display before the generated ones.

    @param ea: linear address
    @param n: number of anterior additioal line (0..MAX_ITEM_LINES)
    @param line: the line to display

    @return: None

    @note: IDA displays additional lines from number 0 up to the first unexisting
    additional line. So, if you specify additional line #150 and there is no
    additional line #149, your line will not be displayed.  MAX_ITEM_LINES is
    defined in IDA.CFG
    """
    idaapi.ExtraUpdate(ea, line, idaapi.E_PREV + n)


def ExtLinB(ea, n, line):
    """
    Specify an additional line to display after the generated ones.

    @param ea: linear address
    @param n: number of posterior additioal line (0..MAX_ITEM_LINES)
    @param line: the line to display

    @return: None
    
    @note: IDA displays additional lines from number 0 up to the first
    unexisting additional line. So, if you specify additional line #150 
    and there is no additional line #149, your line will not be displayed. 
    MAX_ITEM_LINES is defined in IDA.CFG
    """
    idaapi.ExtraUpdate(ea, line, idaapi.E_NEXT + n)


def DelExtLnA(ea, n):
    """
    Delete an additional anterior line

    @param ea: linear address
    @param n: number of anterior additioal line (0..500)

    @return: None
    """
    idaapi.ExtraDel(ea, idaapi.E_PREV + n)


def DelExtLnB(ea, n):
    """
    Delete an additional posterior line

    @param ea: linear address
    @param n: number of posterior additioal line (0..500)

    @return: None
    """
    idaapi.ExtraDel(ea, idaapi.E_NEXT + n)


def SetManualInsn(ea, insn):
    """
    Specify instruction represenation manually.

    @param ea: linear address
    @param insn: a string represenation of the operand

    @note: IDA will not check the specified instruction, it will simply 
    display it instead of the orginal representation.
    """
    return idaapi.set_manual_insn(ea, insn)


def GetManualInsn(ea):
    """
    Get manual representation of instruction

    @param ea: linear address

    @note: This function returns value set by SetManualInsn earlier.
    """
    return idaapi.get_manual_insn(ea)


def PatchByte(ea, value):
    """
    Change value of a program byte

    @param ea: linear address
    @param value: new value of the byte

    @return: None
    """
    return idaapi.patch_byte(ea, value)


def PatchWord(ea, value):
    """
    Change value of a program word (2 bytes)

    @param ea: linear address
    @param value: new value of the word
    """
    return idaapi.patch_word(ea, value)


def PatchDword(ea, value):
    """
    Change value of a double word

    @param ea: linear address
    @param value: new value of the double word
    """
    return idaapi.patch_long(ea, value)


def SetFlags(ea, flags):
    """
    Set new value of flags
    This function should not used be used directly if possible.
    It changes properties of a program byte and if misused, may lead to
    very-very strange results.

    @param ea: adress
    @param flags: new flags value
    """
    return idaapi.setFlags(ea, flags)

_REGMAP = {
    'es' : idaapi.R_es,
    'cs' : idaapi.R_cs,
    'ss' : idaapi.R_ss,
    'ds' : idaapi.R_ds,
    'fs' : idaapi.R_fs,
    'gs' : idaapi.R_gs
}

def SetReg(ea, reg, value):
    """
    Set value of a segment register.

    @param ea: linear address
    @param reg: name of a register, like "cs", "ds", "es", etc.
    @param value: new value of the segment register.

    @note: IDA keeps tracks of all the points where segment register change their
           values. This function allows you to specify the correct value of a segment
           register if IDA is not able to find the corrent value.

    """