idc.py

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

    if not name:
        return ""
    else:
        return name


def GetTrueNameEx(fromaddr, ea):
    """
    Get true name of program byte

    This function returns name of byte as is without any replacements.

    @param fromaddr: the referring address. May be BADADDR.
           Allows to retrieve local label addresses in functions.
           If a local name is not found, then a global name is returned.
    @param ea: linear address

    @return: "" - byte has no name
    """
    name = idaapi.get_true_name(fromaddr, ea)

    if not name:
        return ""
    else:
        return name


def Demangle(name, disable_mask):
    """
    Demangle a name

    @param name: name to demangle
    @param disable_mask: a mask that tells how to demangle the name
            it is a good idea to get this mask using
            GetLongPrm(INF_SHORT_DN) or GetLongPrm(INF_LONG_DN)

    @return: a demangled name
        If the input name cannot be demangled, returns None
    """
    return idaapi.demangle_name(name, disable_mask)


def GetDisasm(ea):
    """
    Get disassembly line

    @param ea: linear address of instruction

    @return: "" - no instruction at the specified location

    @note: this function may not return exactly the same mnemonics 
           as you see on the screen.
    """
    text = idaapi.generate_disasm_line(ea)
    if text:
        return idaapi.tag_remove(text)
    else:
        return ""


def GetMnem(ea):
    """
    Get instruction mnemonics

    @param ea: linear address of instruction
    
    @return: "" - no instruction at the specified location

    @note: this function may not return exactly the same mnemonics
    as you see on the screen.
    """
    res = idaapi.ua_mnem(ea)

    if not res:
        return ""
    else:
        return res


def GetOpnd(ea, n):
    """
    Get operand of an instruction

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

    @return: the current text representation of operand
    """
    res = idaapi.ua_outop(ea, n)

    if not res:
        return ""
    else:
        return idaapi.tag_remove(res)


def GetOpType(ea, n):
    """
    Get type of instruction operand

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

    @return:
        - -1      bad operand number passed
        - 0       None
        - 1       General Register
        - 2       Memory Reference
        - 3       Base + Index
        - 4       Base + Index + Displacement
        - 5       Immediate
        - 6       Immediate Far Address (with a Segment Selector)
        - 7       Immediate Near Address
        
        B{PC:}
        
        - 8       386 Trace register
        - 9       386 Debug register
        - 10      386 Control register
        - 11      FPP register
        - 12      MMX register
        
        B{8051:}

        - 8       bit
        - 9       /bit
        - 10      bit
        
        B{80196:}

        - 8       [intmem]
        - 9       [intmem]+
        - 10      offset[intmem]
        - 11      bit
        
        B{ARM:}
        
        - 8       shifted register
        - 9       MLA operands
        - 10      register list (for LDM/STM)
        - 11      coprocessor register list (for CDP)
        - 12      coprocessor register (for LDC/STC)
        
        B{PPC:}
        
        - 8       SPR
        - 9       2 FPRs
        - 10      SH & MB & ME
        - 11      CR field
        - 12      CR bit
        
        B{TMS320C5:}
        
        - 8       bit
        - 9       bit not
        - 10      condition
        
        B{TMS320C6:}
        
        - 8       register pair (A1:A0..B15:B14)
        
        B{Z8:}
        
        - 8       @intmem
        - 9       @Rx
        
        B{Z80:}
        
        - 8       condition
    """
    inslen = idaapi.ua_code(ea)

    if inslen == 0:
        return -1

    insn = idaapi.get_current_instruction()

    if not insn:
        return -1

    op = idaapi.get_instruction_operand(insn, n)

    if not op:
        return -1

    return op.type


def GetOperandValue(ea, n):
    """
    Get number used in the operand

    This function returns an immediate number used in the operand

    @param ea: linear address of instruction
    @param n: the operand number

    @return: value
        operand is an immediate value  => immediate value
        operand has a displacement     => displacement
        operand is a direct memory ref => memory address
        operand is a register          => register number
        operand is a register phrase   => phrase number
        otherwise                      => -1
    """
    inslen = idaapi.ua_code(ea)
    if inslen == 0:
        return -1

    insn = idaapi.get_current_instruction()
    if not insn:
        return -1

    op = idaapi.get_instruction_operand(insn, n)
    if not op:
        return -1

    if op.type in [ idaapi.o_mem, idaapi.o_far, idaapi.o_near, idaapi.o_displ ]:
        value = op.addr
    elif op.type == idaapi.o_reg:
        value = op.reg
    elif op.type == idaapi.o_imm:
        value = op.value
    elif op.type == idaapi.o_phrase:
        value = op.phrase
    else:
        value = -1
    return value


def LineA(ea, num):
    """
    Get anterior line

    @param ea: linear address
    @param num: number of anterior line (0..MAX_ITEM_LINES)
          MAX_ITEM_LINES is defined in IDA.CFG
    
    @return: anterior line string
    """
    return idaapi.ExtraGet(ea, idaapi.E_PREV + num)


def LineB(ea, num):
    """
    Get posterior line

    @param ea: linear address
    @param num: number of posterior line (0..MAX_ITEM_LINES)

    @return: posterior line string
    """
    return idaapi.ExtraGet(ea, idaapi.E_NEXT + num)


def GetCommentEx(ea, repeatable):
    """
    Get regular indented comment
    
    @param ea: linear address

    @return: string or None if it fails
    """
    return idaapi.get_cmt(ea, repeatable)


def CommentEx(ea, repeatable): GetCommentEx(ea, repeatable)


def AltOp(ea, n):
    """
    Get manually entered operand string

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

    @return: string or None if it fails
    """
    return idaapi.get_forced_operand(ea, n)


def GetString(ea, length, strtype):
    """
    Get string contents
    @param ea: linear address
    @param len: string length. -1 means to calculate the max string length
    @param type: the string type (one of ASCSTR_... constants)

    @return: string contents or empty string
    """
    if length == -1:
        length = idaapi.get_max_ascii_length(ea, strtype)

    return idaapi.get_ascii_contents(ea, length, strtype)


def GetStringType(ea):
    """
    Get string type

    @param ea: linear address

    @return: One of ASCSTR_... constants
    """
    ti = idaapi.typeinfo_t()

    if idaapi.get_typeinfo(ea, 0, GetFlags(ea), ti):
        return ti.strtype
    else:
        return None

ASCSTR_C       = idaapi.ASCSTR_TERMCHR # C-style ASCII string
ASCSTR_PASCAL  = idaapi.ASCSTR_PASCAL  # Pascal-style ASCII string (length byte)
ASCSTR_LEN2    = idaapi.ASCSTR_LEN2    # Pascal-style, length is 2 bytes
ASCSTR_UNICODE = idaapi.ASCSTR_UNICODE # Unicode string
ASCSTR_LEN4    = idaapi.ASCSTR_LEN4    # Pascal-style, length is 4 bytes
ASCSTR_ULEN2   = idaapi.ASCSTR_ULEN2   # Pascal-style Unicode, length is 2 bytes
ASCSTR_ULEN4   = idaapi.ASCSTR_ULEN4   # Pascal-style Unicode, length is 4 bytes
ASCSTR_LAST    = idaapi.ASCSTR_LAST    # Last string type


#      The following functions search for the specified byte
#          ea - address to start from
#          flag is combination of the following bits

#      returns BADADDR - not found
def FindVoid        (ea, flag): return idaapi.find_void(ea, flag)
def FindCode        (ea, flag): return idaapi.find_code(ea, flag)
def FindData        (ea, flag): return idaapi.find_data(ea, flag)
def FindUnexplored  (ea, flag): return idaapi.find_unknown(ea, flag)
def FindExplored    (ea, flag): return idaapi.find_defined(ea, flag)
def FindImmediate   (ea, flag, value): return idaapi.find_imm(ea, flag, value)

SEARCH_UP       = idaapi.SEARCH_UP       # search backward
SEARCH_DOWN     = idaapi.SEARCH_DOWN     # search forward
SEARCH_NEXT     = idaapi.SEARCH_NEXT     # search next occurence
SEARCH_CASE     = idaapi.SEARCH_CASE     # search case-sensitive
                                         # (only for bin&txt search)
SEARCH_REGEX    = idaapi.SEARCH_REGEX    # enable regular expressions (only for text)
SEARCH_NOBRK    = idaapi.SEARCH_NOBRK    # don't test ctrl-break
SEARCH_NOSHOW   = idaapi.SEARCH_NOSHOW   # don't display the search progress

def FindText(ea, flag, y, x, searchstr):
    """
    @param ea: start address
    @param flag: combination of SEARCH_* flags
    @param y: number of text line at ea to start from (0..MAX_ITEM_LINES)
    @param x: coordinate in this line
    @param searchstr: search string

    @return: ea of result or BADADDR if not found
    """
    return idaapi.find_text(ea, y, x, searchstr, flag)


def FindBinary(ea, flag, searchstr, radix=16):
    """
    @param ea: start address
    @param flag: combination of SEARCH_* flags
    @param searchstr: a string as a user enters it for Search Text in Core
    @param radix: radix of the numbers (default=16)

    @return: ea of result or BADADDR if not found

    @note: Example: "41 42" - find 2 bytes 41h,42h (radix is 16)
    """
    endea = flag & 1 and idaapi.cvar.inf.maxEA or idaapi.cvar.inf.minEA
    return idaapi.find_binary(ea, endea, searchstr, radix, flag)


#----------------------------------------------------------------------------
#       G L O B A L   S E T T I N G S   M A N I P U L A T I O N
#----------------------------------------------------------------------------

# The following functions allow you to set/get common parameters.
# Please note that not all parameters can be set directly.

def GetLongPrm (offset):
    """
    """
    return _IDC_GetAttr(idaapi.cvar.inf, _INFMAP, offset)


def GetShortPrm(offset):
    return GetLongPrm(offset)


def GetCharPrm (offset):
    return GetLongPrm(offset)


def SetLongPrm (offset, value):
    """
    """
    return _IDC_SetAttr(idaapi.cvar.inf, _INFMAP, offset, value)


def SetShortPrm(offset, value):
    SetLongPrm(offset, value)


def SetCharPrm (offset, value):
    SetLongPrm(offset, value)


INF_VERSION     = 3       # short;   Version of database
INF_PROCNAME    = 5       # char[8]; Name of current processor
INF_LFLAGS      = 13      # char;    IDP-dependent flags
LFLG_PC_FPP     = 0x01    #              decode floating point processor
                          #              instructions?
LFLG_PC_FLAT    = 0x02    #              Flat model?
LFLG_64BIT      = 0x04    #              64-bit program?
LFLG_DBG_NOPATH = 0x08    #              do not store input full path
LFLG_SNAPSHOT   = 0x10    #              is memory snapshot?
                          #              in debugger process options
INF_DEMNAMES    = 14      # char;    display demangled names as:
DEMNAM_CMNT  = 0          #              comments
DEMNAM_NAME  = 1          #              regular names
DEMNAM_NONE  = 2          #              don't display
INF_FILETYPE    = 15      # short;   type of input file (see ida.hpp)
FT_EXE_OLD      = 0       #              MS DOS EXE File (obsolete)
FT_COM_OLD      = 1       #              MS DOS COM File (obsolete)
FT_BIN          = 2       #              Binary File
FT_DRV          = 3       #              MS DOS Driver
FT_WIN          = 4       #              New Executable (NE)
FT_HEX          = 5       #              Intel Hex Object File
FT_MEX          = 6       #              MOS Technology Hex Object File
FT_LX           = 7       #              Linear Executable (LX)
FT_LE           = 8       #              Linear Executable (LE)
FT_NLM          = 9       #              Netware Loadable Module (NLM)
FT_COFF         = 10      #              Common Object File Format (COFF)
FT_PE           = 11      #              Portable Executable (PE)
FT_OMF          = 12      #              Object Module Format
FT_SREC         = 13      #              R-records
FT_ZIP          = 14      #              ZIP file (this file is never loaded to IDA database)
FT_OMFLIB       = 15