Module ida_loader

Definitions of IDP, LDR, PLUGIN module interfaces.

This file also contains: * functions to load files into the database * functions to generate output files * high level functions to work with the database (open, save, close)

The LDR interface consists of one structure: loader_t The IDP interface consists of one structure: processor_t The PLUGIN interface consists of one structure: plugin_t

Modules can't use standard FILE* functions. They must use functions from

Modules can't use standard memory allocation functions. They must use functions from

The exported entry #1 in the module should point to the the appropriate structure. (loader_t for LDR module, for example)

Global variables

var ACCEPT_ARCHIVE

Specify that a file format is served by archive loader See loader_t::accept_file

var ACCEPT_CONTINUE

Specify that the function must be called another time See loader_t::accept_file

var ACCEPT_FIRST

Specify that a file format should be place first in "load file" dialog box. See loader_t::accept_file

var DBFL_BAK

create backup file (if !DBFL_KILL)

var DBFL_COMP

collect garbage

var DBFL_KILL

delete unpacked database

var DBFL_TEMP

temporary database

var FILEREG_NOTPATCHABLE

the data is kept in some encoded form in the file.

var FILEREG_PATCHABLE

means that the input file may be patched (i.e. no compression, no iterated data, etc)

var GENFLG_ASMINC

OFILE_ASM,OFILE_LST: gen information only about types

var GENFLG_ASMTYPE

OFILE_ASM,OFILE_LST: gen information about types too

var GENFLG_GENHTML

OFILE_ASM,OFILE_LST: generate html (ui_genfile_callback will be used)

var GENFLG_IDCTYPE

OFILE_IDC: gen only information about types

var GENFLG_MAPDMNG

OFILE_MAP: demangle names

var GENFLG_MAPLOC

OFILE_MAP: include local names

var GENFLG_MAPNAME

OFILE_MAP: include dummy names

var GENFLG_MAPSEG

OFILE_MAP: generate map of segments

var LDRF_RELOAD

loader recognizes NEF_RELOAD flag

var LDRF_REQ_PROC

Requires a processor to be set. if this bit is not set, load_file() must call set_processor_type(…, SETPROC_LOADER)

var MAX_DATABASE_DESCRIPTION

Maximum database snapshot description length.

var NEF_CODE

for load_binary_file(): load as a code segment

var NEF_FILL

Fill segment gaps.

var NEF_FIRST

This is the first file loaded into the database.

var NEF_FLAT

Autocreate FLAT group (PE)

var NEF_IMPS

Create import segment.

var NEF_LALL

Load all segments without questions.

var NEF_LOPT

Display additional loader options dialog.

var NEF_MAN

Manual load.

var NEF_MINI

Create mini database (do not copy segment bytes from the input file; use only the file header metadata)

var NEF_NAME

Rename entries.

var NEF_RELOAD

reload the file at the same place: * don't create segments * don't create fixup info * don't import segments * etc.

Load only the bytes into the base. A loader should have the LDRF_RELOAD bit set.

var NEF_RSCS

Load resources.

var NEF_SEGS

Create segments.

var OFILE_ASM

Assembly.

var OFILE_DIF

Difference.

var OFILE_EXE

Executable file.

var OFILE_IDC

IDC file.

var OFILE_LST

Disassembly listing.

var OFILE_MAP

MAP file.

var PATH_TYPE_CMD

full path to the file specified in the command line

var PATH_TYPE_ID0

full path of ID0 file

var PATH_TYPE_IDB

full path of IDB file

var PLUGIN_DLL

Pattern to find plugin files.

var SSF_AUTOMATIC

automatic snapshot

var SSUF_DESC

Update the description.

var SSUF_FLAGS

Update the flags.

var SSUF_PATH

Update the path.

Functions

def base2file(fp: FILE *, pos: qoff64_t, ea1: ea_t, ea2: ea_t)

base2file(fp, pos, ea1, ea2) -> int Unload database to a binary file. This function works for wide byte processors too.

@param fp: (C++: FILE *) pointer to file @param pos: (C++: qoff64_t) position in the file @param ea1: (C++: ea_t) ,ea2: range of source linear addresses @param ea2: (C++: ea_t) @return: 1-ok(always), write error leads to immediate exit

def build_snapshot_tree(root: snapshot_t) ‑> bool

build_snapshot_tree(root) -> bool Build the snapshot tree.

@param root: (C++: snapshot_t *) snapshot root that will contain the snapshot tree elements. @return: success

def clr_database_flag(dbfl: uint32)

clr_database_flag(dbfl)

@param dbfl: uint32

def extract_module_from_archive(fname: char const *, is_remote: bool = False)

extract_module_from_archive(fname, is_remote=False) -> PyObject Extract a module for an archive file. Parse an archive file, show the list of modules to the user, allow him to select a module, extract the selected module to a file (if the extract module is an archive, repeat the process). This function can handle ZIP, AR, AIXAR, OMFLIB files. The temporary file will be automatically deleted by IDA at the end.

@param filename: (C++: char *) in: input file. out: name of the selected module. @param is_remote: (C++: bool) is the input file remote? @retval true: ok @retval false: something bad happened (error message has been displayed to the user)

def file2base(li: linput_t *, pos: qoff64_t, ea1: ea_t, ea2: ea_t, patchable: int)

file2base(li, pos, ea1, ea2, patchable) -> int Load portion of file into the database. This function will include (ea1..ea2) into the addressing space of the program (make it enabled).

@param li: (C++: linput_t *) pointer of input source @param pos: (C++: qoff64_t) position in the file @param ea1: (C++: ea_t) ,ea2: range of destination linear addresses @param patchable: (C++: int) should the kernel remember correspondence of file offsets to linear addresses. @retval 1: ok @retval 0: read error, a warning is displayed @note: The storage type of the specified range will be changed to STT_VA. @param patchable: (C++: int) should the kernel remember correspondence of file offsets to linear addresses. @retval 1: ok @retval 0: read error, a warning is displayed @note: The storage type of the specified range will be changed to STT_VA.

def find_plugin(name: char const *, load_if_needed: bool = False)

find_plugin(name, load_if_needed=False) -> plugin_t Find a user-defined plugin and optionally load it.

@param name: (C++: const char *) short plugin name without path and extension, or absolute path to the file name @param load_if_needed: (C++: bool) if the plugin is not present in the memory, try to load it @return: pointer to plugin description block

def flush_buffers() ‑> int

flush_buffers() -> int Flush buffers to the disk.

def gen_exe_file(fp: FILE *)

gen_exe_file(fp) -> int Generate an exe file (unload the database in binary form).

@param fp: (C++: FILE *) @return: fp the output file handle. if fp == nullptr then return: * 1: can generate an executable file * 0: can't generate an executable file @retval 1: ok @retval 0: failed

def gen_file(otype: ofile_type_t, fp: FILE *, ea1: ea_t, ea2: ea_t, flags: int)

gen_file(otype, fp, ea1, ea2, flags) -> int Generate an output file.

@param otype: (C++: ofile_type_t) type of output file. @param fp: (C++: FILE *) the output file handle @param ea1: (C++: ea_t) start address. For some file types this argument is ignored @param ea2: (C++: ea_t) end address. For some file types this argument is ignored as usual in ida, the end address of the range is not included @param flags: (C++: int) Generate file flagsOFILE_EXE: @retval 0: can't generate exe file @retval 1: ok @return: number of the generated lines. -1 if an error occurred

def get_basic_file_type(li: linput_t *)

get_basic_file_type(li) -> filetype_t Get the input file type. This function can recognize libraries and zip files.

@param li: (C++: linput_t *)

def get_elf_debug_file_directory()

get_elf_debug_file_directory() -> char const * Get the value of the ELF_DEBUG_FILE_DIRECTORY configuration directive.

def get_file_type_name()

get_file_type_name() -> str Get name of the current file type. The current file type is kept in idainfo::filetype.

@return: size of answer, this function always succeeds

def get_fileregion_ea(offset: qoff64_t)

get_fileregion_ea(offset) -> ea_t Get linear address which corresponds to the specified input file offset. If can't be found, return BADADDR

@param offset: (C++: qoff64_t)

def get_fileregion_offset(ea: ea_t)

get_fileregion_offset(ea) -> qoff64_t Get offset in the input file which corresponds to the given ea. If the specified ea can't be mapped into the input file offset, return -1.

@param ea: (C++: ea_t)

def get_path(pt: path_type_t)

get_path(pt) -> char const * Get the file path

@param pt: (C++: path_type_t) file path type Types of the file pathes @return: file path, never returns nullptr

def get_plugin_options(plugin: char const *)

get_plugin_options(plugin) -> char const * Get plugin options from the command line. If the user has specified the options in the -Oplugin_name:options format, them this function will return the 'options' part of it The 'plugin' parameter should denote the plugin name Returns nullptr if there we no options specified

@param plugin: (C++: const char *) char const *

def is_database_flag(dbfl: uint32)

is_database_flag(dbfl) -> bool Get the current database flag

@param dbfl: (C++: uint32) flag Database flags @return: the state of the flag (set or cleared)

def is_trusted_idb() ‑> bool

is_trusted_idb() -> bool Is the database considered as trusted?

def load_and_run_plugin(name: char const *, arg: size_t)

load_and_run_plugin(name, arg) -> bool Load & run a plugin.

@param name: (C++: const char *) char const * @param arg: (C++: size_t)

def load_binary_file(filename: char const *, li: linput_t *, _neflags: ushort, fileoff: qoff64_t, basepara: ea_t, binoff: ea_t, nbytes: uint64)

load_binary_file(filename, li, _neflags, fileoff, basepara, binoff, nbytes) -> bool Load a binary file into the database. This function usually is called from ui.

@param filename: (C++: const char ) the name of input file as is (if the input file is from library, then this is the name from the library) @param li: (C++: linput_t ) loader input source @param _neflags: (C++: ushort) Load file flags. For the first file, the flag NEF_FIRST must be set. @param fileoff: (C++: qoff64_t) Offset in the input file @param basepara: (C++: ea_t) Load address in paragraphs @param binoff: (C++: ea_t) Load offset (load_address=(basepara<<4)+binoff) @param nbytes: (C++: uint64) Number of bytes to load from the file. * 0: up to the end of the file @retval true: ok @retval false: failed (couldn't open the file)

def load_ids_module(fname: char *)

load_ids_module(fname) -> int Load and apply IDS file. This function loads the specified IDS file and applies it to the database. If the program imports functions from a module with the same name as the name of the ids file being loaded, then only functions from this module will be affected. Otherwise (i.e. when the program does not import a module with this name) any function in the program may be affected.

@param fname: (C++: char *) name of file to apply @retval 1: ok @retval 0: some error (a message is displayed). if the ids file does not exist, no message is displayed

def load_plugin(name: char const *)

load_plugin(name) -> PyCapsule or None Loads a plugin

@param name: char const * @return: - None if plugin could not be loaded - An opaque object representing the loaded plugin

def mem2base(py_mem: PyObject *, ea: ea_t, fpos: qoff64_t = -1)

mem2base(py_mem, ea, fpos=-1) -> int Load database from the memory.

@param py_mem: the buffer @param ea: start linear addresses @param fpos: position in the input file the data is taken from. if == -1, then no file position correspond to the data. @return: - Returns zero if the passed buffer was not a string - Otherwise 1 is returned

def process_archive(temp_file: qstring *, li: linput_t *, module_name: qstring *, neflags: ushort *, defmember: char const *, loader: load_info_t const *)

process_archive(temp_file, li, module_name, neflags, defmember, loader) -> str Calls loader_t::process_archive() For parameters and return value description look at loader_t::process_archive(). Additional parameter 'loader' is a pointer to load_info_t structure.

@param temp_file: (C++: qstring ) @param li: (C++: linput_t ) @param module_name: (C++: qstring ) @param neflags: (C++: ushort ) @param defmember: (C++: const char ) char const * @param loader: (C++: const load_info_t ) load_info_t const *

def reload_file(file: char const *, is_remote: bool)

reload_file(file, is_remote) -> bool Reload the input file. This function reloads the byte values from the input file. It doesn't modify the segmentation, names, comments, etc.

@param file: (C++: const char *) name of the input file. if file == nullptr then returns: * 1: can reload the input file * 0: can't reload the input file @param is_remote: (C++: bool) is the file located on a remote computer with the debugger server? @return: success

def run_plugin(plg: PyObject *, arg: size_t)

run_plugin(plg, arg) -> bool Runs a plugin

@param plg: A plugin object (returned by load_plugin()) @param arg: size_t @return: Boolean

def save_database(outfile: char const * = None, flags: uint32 = -1, root: snapshot_t = None, attr: snapshot_t = None)

save_database(outfile=None, flags=-1, root=None, attr=None) -> bool Save current database using a new file name.

@param outfile: (C++: const char ) output database file name; nullptr means the current path @param flags: (C++: uint32) Database flags; -1 means the current flags @param root: (C++: const snapshot_t ) optional: snapshot tree root. @param attr: (C++: const snapshot_t *) optional: snapshot attributes @note: when both root and attr are not nullptr then the snapshot attributes will be updated, otherwise the snapshot attributes will be inherited from the current database. @return: success

def set_database_flag(dbfl: uint32, cnd: bool = True)

set_database_flag(dbfl, cnd=True) Set or clear database flag

@param dbfl: (C++: uint32) flag Database flags @param cnd: (C++: bool) set if true or clear flag otherwise

def set_import_name(modnode: uval_t, ea: ea_t, name: char const *)

set_import_name(modnode, ea, name) Set information about the named import entry. This function performs 'modnode.supset_ea(ea, name);'

@param modnode: (C++: uval_t) node with information about imported entries @param ea: (C++: ea_t) linear address of the entry @param name: (C++: const char *) name of the entry

def set_import_ordinal(modnode: uval_t, ea: ea_t, ord: uval_t)

set_import_ordinal(modnode, ea, ord) Set information about the ordinal import entry. This function performs 'modnode.altset(ord, ea2node(ea));'

@param modnode: (C++: uval_t) node with information about imported entries @param ea: (C++: ea_t) linear address of the entry @param ord: (C++: uval_t) ordinal number of the entry

def set_path(pt: path_type_t, path: char const *)

set_path(pt, path) Set the file path

@param pt: (C++: path_type_t) file path type Types of the file pathes @param path: (C++: const char *) new file path, use nullptr or empty string to clear the file path

Classes

class idp_desc_t

Proxy of C++ idp_desc_t class.

init(self) -> idp_desc_t

Instance variables

var checked : bool

internal, for cache management

var family : qstring

processor's family

var is_script : bool

the processor module is a script

var mtime : time_t

time of last modification

var names : idp_names_t

processor names

var path : qstring

module file name

var thisown

The membership flag

class idp_name_t

Proxy of C++ idp_name_t class.

init(self) -> idp_name_t

Instance variables

var hidden : bool

is hidden

var lname : qstring

long processor name

var sname : qstring

short processor name

var thisown

The membership flag

class loader_t

Proxy of C++ loader_t class.

init(self) -> loader_t

Instance variables

var flags : uint32

Loader flags

var thisown

The membership flag

var version : uint32

api version, should be IDP_INTERFACE_VERSION

class plugin_info_t

Proxy of C++ plugin_info_t class.

init(self) -> plugin_info_t

Instance variables

var arg : size_t

argument used to call the plugin

var comment : char *

a copy of plugin_t::comment

var dllmem : idadll_t

dllmem

var entry : plugin_t *

pointer to the plugin if it is already loaded

var flags : int

a copy of plugin_t::flags

var hotkey : ushort

current hotkey to run the plugin

var idaplg_name : qstring

"name" provided by ida-plugin.json or basename of path (without extension)

var name : char *

short name of the plugin it will appear in the menu

var next : plugin_info_t *

next plugin information

var org_hotkey : ushort

original hotkey to run the plugin

var org_name : char *

original short name of the plugin

var path : char *

full path to the plugin

var thisown

The membership flag

class qvector_snapshotvec_t (*args)

Proxy of C++ qvector< snapshot_t * > class.

init(self) -> qvector_snapshotvec_t init(self, x) -> qvector_snapshotvec_t

@param x: qvector< snapshot_t * > const &

Instance variables

var thisown

The membership flag

Methods

def add_unique(self, x: snapshot_t) ‑> bool

add_unique(self, x) -> bool

@param x: snapshot_t *const &

def at(self, _idx: size_t)

at(self, _idx) -> snapshot_t

@param _idx: size_t

def back(self)

def begin(self, *args)

begin(self) -> qvector< snapshot_t * >::iterator begin(self) -> qvector< snapshot_t * >::const_iterator

def capacity(self)

capacity(self) -> size_t

def clear(self)

clear(self)

def empty(self) ‑> bool

empty(self) -> bool

def end(self, *args)

end(self) -> qvector< snapshot_t * >::iterator end(self) -> qvector< snapshot_t * >::const_iterator

def erase(self, *args)

erase(self, it) -> qvector< snapshot_t * >::iterator

@param it: qvector< snapshot_t * >::iterator

erase(self, first, last) -> qvector< snapshot_t * >::iterator

@param first: qvector< snapshot_t * >::iterator @param last: qvector< snapshot_t * >::iterator

def extract(self)

extract(self) -> snapshot_t **

def find(self, *args)

find(self, x) -> qvector< snapshot_t * >::iterator

@param x: snapshot_t *const &

find(self, x) -> qvector< snapshot_t * >::const_iterator

@param x: snapshot_t *const &

def front(self)

def has(self, x: snapshot_t) ‑> bool

has(self, x) -> bool

@param x: snapshot_t *const &

def inject(self, s: snapshot_t **, len: size_t)

inject(self, s, len)

@param s: snapshot_t ** @param len: size_t

def insert(self, it: qvector< snapshot_t * >::iterator, x: snapshot_t)

insert(self, it, x) -> qvector< snapshot_t * >::iterator

@param it: qvector< snapshot_t * >::iterator @param x: snapshot_t *const &

def pop_back(self)

pop_back(self)

def push_back(self, *args)

push_back(self, x)

@param x: snapshot_t *const &

push_back(self) -> snapshot_t *&

def qclear(self)

qclear(self)

def reserve(self, cnt: size_t)

reserve(self, cnt)

@param cnt: size_t

def resize(self, *args)

resize(self, _newsize, x)

@param _newsize: size_t @param x: snapshot_t *const &

resize(self, _newsize)

@param _newsize: size_t

def size(self)

size(self) -> size_t

def swap(self, r: qvector_snapshotvec_t)

swap(self, r)

@param r: qvector< snapshot_t * > &

def truncate(self)

truncate(self)

class snapshot_t

Proxy of C++ snapshot_t class.

init(self) -> snapshot_t

Instance variables

var children : snapshots_t

snapshot children

var desc : char [128]

snapshot description

var filename : char [QMAXPATH]

snapshot file name

var flags : uint16

Snapshot flags

var id : qtime64_t

snapshot ID. This value is computed using qgettimeofday()

var thisown

The membership flag

Methods

def clear(self)

clear(self)