IDA C++ SDK 9.2
Loading...
Searching...
No Matches
loader.hpp File Reference

Definitions of IDP, LDR, PLUGIN module interfaces. More...

Go to the source code of this file.

Classes

struct  loader_t
 Loader description block - must be exported from the loader module. More...
struct  load_info_t
 List of loaders. More...
struct  impinfo_t
 See importer_t. More...
class  plugin_t
 A plugin is a module in the plugins subdirectory that can perform an action asked by the user. More...
struct  idp_name_t
 Processor name. More...
struct  idp_desc_t
 Processor module description. More...
struct  plugin_info_t
 Structure to store plugin information. More...
struct  dbg_info_t
 Information for the user interface about available debuggers. More...
class  snapshot_t
 Snapshot attributes. More...

Typedefs

typedef int idaapi importer_t(linput_t *li, impinfo_t *ii)
 Callback for checking dll module - passed to import_module().
typedef qvector< idp_name_tidp_names_t
 vector of processor names
typedef qvector< idp_desc_tidp_descs_t
 vector of processor module descriptions
typedef qvector< snapshot_t * > snapshots_t
 vector of database snapshots

Enumerations

enum  ofile_type_t {
  OFILE_MAP = 0 , OFILE_EXE = 1 , OFILE_IDC = 2 , OFILE_LST = 3 ,
  OFILE_ASM = 4 , OFILE_DIF = 5
}
 Output file types. More...
enum  path_type_t { PATH_TYPE_CMD , PATH_TYPE_IDB , PATH_TYPE_ID0 }

Functions

idaman AS_PRINTF (1, 0) NORETURN void ida_export vloader_failure(const char *format
 See loader_failure()
 AS_PRINTF (1, 2) NORETURN inline void loader_failure(const char *format
 Display a message about a loader failure and stop the loading process.
 va_start (va, format)
 vloader_failure (format, va)
 DECLARE_TYPE_AS_MOVABLE (load_info_t)
idaman load_info_t *ida_export build_loaders_list (linput_t *li, const char *filename)
 Build list of potential loaders.
idaman void ida_export free_loaders_list (load_info_t *list)
 Free the list of loaders.
idaman char *ida_export get_loader_name_from_dll (char *dllname)
 Get name of loader from its DLL file (for example, for PE files we will get "PE").
idaman ssize_t ida_export get_loader_name (char *buf, size_t bufsize)
 Get name of loader used to load the input file into the database.
idaman bool ida_export load_binary_file (const char *filename, linput_t *li, ushort _neflags, qoff64_t fileoff, ea_t basepara, ea_t binoff, uint64 nbytes)
 Load a binary file into the database.
idaman bool ida_export load_nonbinary_file (const char *filename, linput_t *li, const char *sysdlldir, ushort _neflags, load_info_t *loader)
 Load a non-binary file into the database.
idaman int ida_export process_archive (qstring *temp_file, linput_t *li, qstring *module_name, ushort *neflags, const char *defmember, const load_info_t *loader, qstring *errbuf=nullptr)
 Calls loader_t::process_archive() For parameters and return value description look at loader_t::process_archive().
idaman int ida_export gen_file (ofile_type_t otype, FILE *fp, ea_t ea1, ea_t ea2, int flags)
 Generate an output file.
idaman int ida_export file2base (linput_t *li, qoff64_t pos, ea_t ea1, ea_t ea2, int patchable)
 Load portion of file into the database.
idaman int ida_export mem2base (const void *memptr, ea_t ea1, ea_t ea2, qoff64_t fpos)
 Load database from the memory.
idaman int ida_export base2file (FILE *fp, qoff64_t pos, ea_t ea1, ea_t ea2)
 Unload database to a binary file.
idaman bool ida_export extract_module_from_archive (char *filename, size_t bufsize, char **temp_file_ptr, bool is_remote)
 Extract a module for an archive file.
idaman void ida_export create_filename_cmt (void)
 Add long comment at idainfo::min_ea.
idaman filetype_t ida_export get_basic_file_type (linput_t *li)
 Get the input file type.
idaman size_t ida_export get_file_type_name (char *buf, size_t bufsize)
 Get name of the current file type.
idaman void ida_export import_module (const char *module, const char *windir, uval_t modnode, importer_t *importer, const char *ostype)
 Find and import a DLL module.
idaman void ida_export set_import_ordinal (uval_t modnode, ea_t ea, uval_t ord)
 Set information about the ordinal import entry.
idaman void ida_export set_import_name (uval_t modnode, ea_t ea, const char *name)
 Set information about the named import entry.
idaman int ida_export load_ids_module (char *fname)
 Load and apply IDS file.
 CASSERT (sizeof(plugin_t)==64)
idaman const char *ida_export get_plugin_options (const char *plugin)
 Get plugin options from the command line.
 DECLARE_TYPE_AS_MOVABLE (idp_name_t)
 DECLARE_TYPE_AS_MOVABLE (idp_desc_t)
idaman const idp_descs_t *ida_export get_idp_descs (void)
 Get IDA processor modules descriptions.
idaman plugin_info_t *ida_export get_plugins (void)
 Get pointer to the list of plugins.
idaman plugin_t *ida_export find_plugin (const char *name, bool load_if_needed=false)
 Find a user-defined plugin and optionally load it.
plugin_tload_plugin (const char *name)
idaman bool ida_export run_plugin (const plugin_t *ptr, size_t arg)
 Run a loaded plugin with the specified argument.
bool idaapi load_and_run_plugin (const char *name, size_t arg)
 Load & run a plugin.
idaman bool ida_export invoke_plugin (plugin_info_t *ptr)
 Run a plugin as configured.
 DECLARE_TYPE_AS_MOVABLE (dbg_info_t)
idaman size_t ida_export get_debugger_plugins (const dbg_info_t **array)
 Get information about available debuggers.
idaman void ida_export init_plugins (int flag)
 Initialize plugins with the specified flag.
idaman void ida_export term_plugins (int flag)
 Terminate plugins with the specified flag.
idaman qoff64_t ida_export get_fileregion_offset (ea_t ea)
 Get offset in the input file which corresponds to the given ea.
idaman ea_t ida_export get_fileregion_ea (qoff64_t offset)
 Get linear address which corresponds to the specified input file offset.
idaman int ida_export gen_exe_file (FILE *fp)
 Generate an exe file (unload the database in binary form).
idaman bool ida_export reload_file (const char *file, bool is_remote)
 Reload the input file.
 DECLARE_TYPE_AS_MOVABLE (snapshot_t)
idaman bool ida_export build_snapshot_tree (snapshot_t *root)
 Build the snapshot tree.
idaman bool ida_export update_snapshot_attributes (const char *filename, const snapshot_t *root, const snapshot_t *attr, int uf)
 Update the snapshot attributes.
idaman int ida_export visit_snapshot_tree (snapshot_t *root, int(idaapi *callback)(snapshot_t *ss, void *ud), void *ud=nullptr)
 Visit the snapshot tree.
idaman int ida_export flush_buffers (void)
 Flush buffers to the disk.
idaman bool ida_export is_trusted_idb (void)
 Is the database considered as trusted?
idaman bool ida_export save_database (const char *outfile=nullptr, uint32 flags=-1, const snapshot_t *root=nullptr, const snapshot_t *attr=nullptr)
 Save current database using a new file name.
idaman bool ida_export is_database_flag (uint32 dbfl)
 Get the current database flag.
idaman void ida_export set_database_flag (uint32 dbfl, bool cnd=true)
 Set or clear database flag.
void clr_database_flag (uint32 dbfl)
bool is_temp_database (void)
 Is a temporary database?
idaman const char *ida_export get_path (path_type_t pt)
 Get the file path.
idaman void ida_export set_path (path_type_t pt, const char *path)
 Set the file path.
idaman bool ida_export is_database_ext (const char *ext)
 Check the file extension.
idaman const char *ida_export get_elf_debug_file_directory ()
 Get the value of the ELF_DEBUG_FILE_DIRECTORY configuration directive.

Variables

idaman va_list va
idaman ida_module_data plugin_t PLUGIN

Detailed Description

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 <fpro.h>

Modules can't use standard memory allocation functions. They must use functions from <pro.h>

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

Typedef Documentation

◆ importer_t

typedef int idaapi importer_t(linput_t *li, impinfo_t *ii)

Callback for checking dll module - passed to import_module().

Parameters
lipointer to input file
iiimport info. If the function finds that ii.dllname does not match the module name passed to import_module(), it returns 0.
Otherwise it calls ii.func for each exported entry.
If ii.dllname==nullptr then ii.func will be called with num==0 and name==dllname.
Return values
0dllname doesn't match, import_module() should continue
1ok

◆ idp_names_t

vector of processor names

◆ idp_descs_t

vector of processor module descriptions

◆ snapshots_t

vector of database snapshots

Enumeration Type Documentation

◆ ofile_type_t

Output file types.

Enumerator
OFILE_MAP 

MAP file.

OFILE_EXE 

Executable file.

OFILE_IDC 

IDC file.

OFILE_LST 

Disassembly listing.

OFILE_ASM 

Assembly.

OFILE_DIF 

Difference.

Function Documentation

◆ AS_PRINTF() [1/2]

idaman AS_PRINTF ( 1 ,
0  ) const

See loader_failure()

◆ AS_PRINTF() [2/2]

AS_PRINTF ( 1 ,
2  ) const

Display a message about a loader failure and stop the loading process.

The kernel will destroy the database. If format == nullptr, no message will be displayed This function does not return (it longjumps)! It may be called only from loader_t::load_file

◆ va_start()

va_start ( va ,
format  )

◆ vloader_failure()

vloader_failure ( format ,
va  )

◆ DECLARE_TYPE_AS_MOVABLE() [1/5]

DECLARE_TYPE_AS_MOVABLE ( load_info_t )

◆ build_loaders_list()

idaman load_info_t *ida_export build_loaders_list ( linput_t * li,
const char * filename )

Build list of potential loaders.

◆ free_loaders_list()

idaman void ida_export free_loaders_list ( load_info_t * list)

Free the list of loaders.

◆ get_loader_name_from_dll()

idaman char *ida_export get_loader_name_from_dll ( char * dllname)

Get name of loader from its DLL file (for example, for PE files we will get "PE").

This function modifies the original string and returns a pointer into it. NB: if the file extension is a registered extlang extension (e.g. py or idc) the extension is retained

◆ get_loader_name()

idaman ssize_t ida_export get_loader_name ( char * buf,
size_t bufsize )

Get name of loader used to load the input file into the database.

If no external loader was used, returns -1. Otherwise copies the loader file name without the extension in the buf and returns its length (for example, for PE files we will get "PE"). For scripted loaders, the file extension is retained.

◆ load_binary_file()

idaman bool ida_export load_binary_file ( const char * filename,
linput_t * li,
ushort _neflags,
qoff64_t fileoff,
ea_t basepara,
ea_t binoff,
uint64 nbytes )

Load a binary file into the database.

This function usually is called from ui.

Parameters
filenamethe name of input file as is (if the input file is from library, then this is the name from the library)
liloader input source
_neflagsLoad file flags. For the first file, the flag #NEF_FIRST must be set.
fileoffOffset in the input file
baseparaLoad address in paragraphs
binoffLoad offset (load_address=(basepara<<4)+binoff)
nbytesNumber of bytes to load from the file.
  • 0: up to the end of the file

If nbytes is bigger than the number of bytes rest, the kernel will load as much as possible

Return values
trueok
falsefailed (couldn't open the file)

◆ load_nonbinary_file()

idaman bool ida_export load_nonbinary_file ( const char * filename,
linput_t * li,
const char * sysdlldir,
ushort _neflags,
load_info_t * loader )

Load a non-binary file into the database.

This function usually is called from ui.

Parameters
filenamethe name of input file as is (if the input file is from library, then this is the name from the library)
liloader input source
sysdlldira directory with system dlls. Pass "." if unknown.
_neflagsLoad file flags. For the first file the flag #NEF_FIRST must be set.
loaderpointer to load_info_t structure. If the current IDP module has processor_t::loader != nullptr then this argument is ignored.
Returns
success

◆ process_archive()

idaman int ida_export process_archive ( qstring * temp_file,
linput_t * li,
qstring * module_name,
ushort * neflags,
const char * defmember,
const load_info_t * loader,
qstring * errbuf = nullptr )

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.

◆ gen_file()

idaman int ida_export gen_file ( ofile_type_t otype,
FILE * fp,
ea_t ea1,
ea_t ea2,
int flags )

Generate an output file.

Parameters
otypetype of output file.
fpthe output file handle
ea1start address. For some file types this argument is ignored
ea2end address. For some file types this argument is ignored as usual in ida, the end address of the range is not included
flagsGenerate file flags

For OFILE_EXE:

Return values
0can't generate exe file
1ok

For other file types:

Returns
number of the generated lines. -1 if an error occurred

◆ file2base()

idaman int ida_export file2base ( linput_t * li,
qoff64_t pos,
ea_t ea1,
ea_t ea2,
int patchable )

Load portion of file into the database.

This function will include (ea1..ea2) into the addressing space of the program (make it enabled).

Parameters
lipointer of input source
posposition in the file
ea1,ea2range of destination linear addresses
patchableshould the kernel remember correspondence of file offsets to linear addresses.
Return values
1ok
0read error, a warning is displayed
Note
The storage type of the specified range will be changed to STT_VA.

◆ mem2base()

idaman int ida_export mem2base ( const void * memptr,
ea_t ea1,
ea_t ea2,
qoff64_t fpos )

Load database from the memory.

This function works for wide byte processors too.

Parameters
memptrpointer to buffer with bytes
ea1,ea2range of destination linear addresses
fposposition in the input file the data is taken from. if == -1, then no file position correspond to the data.
Returns
1 always
Note
The storage type of the specified range will be changed to STT_VA.

◆ base2file()

idaman int ida_export base2file ( FILE * fp,
qoff64_t pos,
ea_t ea1,
ea_t ea2 )

Unload database to a binary file.

This function works for wide byte processors too.

Parameters
fppointer to file
posposition in the file
ea1,ea2range of source linear addresses
Returns
1-ok(always), write error leads to immediate exit

◆ extract_module_from_archive()

idaman bool ida_export extract_module_from_archive ( char * filename,
size_t bufsize,
char ** temp_file_ptr,
bool is_remote )

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.

Parameters
[in,out]filenamein: input file. out: name of the selected module.
bufsizesize of the buffer with 'filename'
[out]temp_file_ptrwill point to the name of the file that contains the extracted module
is_remoteis the input file remote?
Return values
trueok
falsesomething bad happened (error message has been displayed to the user)

◆ create_filename_cmt()

idaman void ida_export create_filename_cmt ( void )

Add long comment at idainfo::min_ea.

  • Input file: ....
  • File format: ....

This function should be called only from the loader to describe the input file.

◆ get_basic_file_type()

idaman filetype_t ida_export get_basic_file_type ( linput_t * li)

Get the input file type.

This function can recognize libraries and zip files.

◆ get_file_type_name()

idaman size_t ida_export get_file_type_name ( char * buf,
size_t bufsize )

Get name of the current file type.

The current file type is kept in idainfo::filetype.

Parameters
bufbuffer for the file type name
bufsizeits size
Returns
size of answer, this function always succeeds

◆ import_module()

idaman void ida_export import_module ( const char * module,
const char * windir,
uval_t modnode,
importer_t * importer,
const char * ostype )

Find and import a DLL module.

This function adds information to the database (renames functions, etc).

Parameters
modulename of DLL
windirsystem directory with dlls
modnodenode with information about imported entries. either altval or supval arrays may be absent. the node should never be deleted.
  • imports by ordinals: altval(ord) contains linear address
  • imports by name: supval(ea) contains the imported name please use set_import_ordinal()/set_import_name() to work with MODNODE
importercallback function (may be nullptr) to check dll module
ostypetype of operating system (subdir name). nullptr means the IDS directory itself (not recommended)

◆ set_import_ordinal()

idaman void ida_export set_import_ordinal ( uval_t modnode,
ea_t ea,
uval_t ord )

Set information about the ordinal import entry.

This function performs 'modnode.altset(ord, ea2node(ea));'

Parameters
modnodenode with information about imported entries
ealinear address of the entry
ordordinal number of the entry

◆ set_import_name()

idaman void ida_export set_import_name ( uval_t modnode,
ea_t ea,
const char * name )

Set information about the named import entry.

This function performs 'modnode.supset_ea(ea, name);'

Parameters
modnodenode with information about imported entries
ealinear address of the entry
namename of the entry

◆ load_ids_module()

idaman int ida_export load_ids_module ( char * fname)

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.

Parameters
fnamename of file to apply
Return values
1ok
0some error (a message is displayed). if the ids file does not exist, no message is displayed

◆ CASSERT()

CASSERT ( sizeof(plugin_t) = =64)

◆ get_plugin_options()

idaman const char *ida_export get_plugin_options ( const char * plugin)

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

◆ DECLARE_TYPE_AS_MOVABLE() [2/5]

DECLARE_TYPE_AS_MOVABLE ( idp_name_t )

◆ DECLARE_TYPE_AS_MOVABLE() [3/5]

DECLARE_TYPE_AS_MOVABLE ( idp_desc_t )

◆ get_idp_descs()

idaman const idp_descs_t *ida_export get_idp_descs ( void )

Get IDA processor modules descriptions.

◆ get_plugins()

idaman plugin_info_t *ida_export get_plugins ( void )

Get pointer to the list of plugins.

(some plugins might be listed several times in the list - once for each configured argument)

◆ find_plugin()

idaman plugin_t *ida_export find_plugin ( const char * name,
bool load_if_needed = false )

Find a user-defined plugin and optionally load it.

Parameters
nameshort plugin name without path and extension, or absolute path to the file name
load_if_neededif the plugin is not present in the memory, try to load it
Returns
pointer to plugin description block

◆ load_plugin()

plugin_t * load_plugin ( const char * name)
inline

◆ run_plugin()

idaman bool ida_export run_plugin ( const plugin_t * ptr,
size_t arg )

Run a loaded plugin with the specified argument.

Parameters
ptrpointer to plugin description block
argargument to run with

◆ load_and_run_plugin()

bool idaapi load_and_run_plugin ( const char * name,
size_t arg )
inline

Load & run a plugin.

◆ invoke_plugin()

idaman bool ida_export invoke_plugin ( plugin_info_t * ptr)

Run a plugin as configured.

Parameters
ptrpointer to plugin information block

◆ DECLARE_TYPE_AS_MOVABLE() [4/5]

DECLARE_TYPE_AS_MOVABLE ( dbg_info_t )

◆ get_debugger_plugins()

idaman size_t ida_export get_debugger_plugins ( const dbg_info_t ** array)

Get information about available debuggers.

◆ init_plugins()

idaman void ida_export init_plugins ( int flag)

Initialize plugins with the specified flag.

◆ term_plugins()

idaman void ida_export term_plugins ( int flag)

Terminate plugins with the specified flag.

◆ get_fileregion_offset()

idaman qoff64_t ida_export get_fileregion_offset ( ea_t ea)

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.

◆ get_fileregion_ea()

idaman ea_t ida_export get_fileregion_ea ( qoff64_t offset)

Get linear address which corresponds to the specified input file offset.

If can't be found, return #BADADDR

◆ gen_exe_file()

idaman int ida_export gen_exe_file ( FILE * fp)

Generate an exe file (unload the database in binary form).

Returns
fp the output file handle. if fp == nullptr then return:
  • 1: can generate an executable file
  • 0: can't generate an executable file
Return values
1ok
0failed

◆ reload_file()

idaman bool ida_export reload_file ( const char * file,
bool is_remote )

Reload the input file.

This function reloads the byte values from the input file. It doesn't modify the segmentation, names, comments, etc.

Parameters
filename of the input file. if file == nullptr then returns:
  • 1: can reload the input file
  • 0: can't reload the input file
is_remoteis the file located on a remote computer with the debugger server?
Returns
success

◆ DECLARE_TYPE_AS_MOVABLE() [5/5]

DECLARE_TYPE_AS_MOVABLE ( snapshot_t )

◆ build_snapshot_tree()

idaman bool ida_export build_snapshot_tree ( snapshot_t * root)

Build the snapshot tree.

Parameters
rootsnapshot root that will contain the snapshot tree elements.
Returns
success

◆ update_snapshot_attributes()

idaman bool ida_export update_snapshot_attributes ( const char * filename,
const snapshot_t * root,
const snapshot_t * attr,
int uf )

Update the snapshot attributes.

Note
only the snapshot description can be updated.
Parameters
filenamesnapshot file name or nullptr for the current database
rootsnapshot root (returned from build_snapshot_tree())
attrsnapshot instance containing the updated attributes
ufSnapshot update flags
Returns
success

◆ visit_snapshot_tree()

idaman int ida_export visit_snapshot_tree ( snapshot_t * root,
int(idaapi *callback)(snapshot_t *ss, void *ud) ,
void * ud = nullptr )

Visit the snapshot tree.

Parameters
rootsnapshot root to start the enumeration from
callbackcallback called for each child. return 0 to continue enumeration and non-zero to abort enumeration
uduser data. will be passed back to the callback
Returns
true-ok, false-failed

◆ flush_buffers()

idaman int ida_export flush_buffers ( void )

Flush buffers to the disk.

◆ is_trusted_idb()

idaman bool ida_export is_trusted_idb ( void )

Is the database considered as trusted?

◆ save_database()

idaman bool ida_export save_database ( const char * outfile = nullptr,
uint32 flags = -1,
const snapshot_t * root = nullptr,
const snapshot_t * attr = nullptr )

Save current database using a new file name.

Parameters
outfileoutput database file name; nullptr means the current path
flagsDatabase flags; -1 means the current flags
rootoptional: snapshot tree root.
attroptional: 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.
Returns
success

◆ is_database_flag()

idaman bool ida_export is_database_flag ( uint32 dbfl)

Get the current database flag.

Parameters
dbflflag Database flags
Returns
the state of the flag (set or cleared)

◆ set_database_flag()

idaman void ida_export set_database_flag ( uint32 dbfl,
bool cnd = true )

Set or clear database flag.

Parameters
dbflflag Database flags
cndset if true or clear flag otherwise

◆ clr_database_flag()

void clr_database_flag ( uint32 dbfl)
inline

◆ is_temp_database()

bool is_temp_database ( void )
inline

Is a temporary database?

◆ get_path()

idaman const char *ida_export get_path ( path_type_t pt)

Get the file path.

Parameters
ptfile path type Types of the file pathes
Returns
file path, never returns nullptr

◆ set_path()

idaman void ida_export set_path ( path_type_t pt,
const char * path )

Set the file path.

Parameters
ptfile path type Types of the file pathes
pathnew file path, use nullptr or empty string to clear the file path

◆ is_database_ext()

idaman bool ida_export is_database_ext ( const char * ext)

Check the file extension.

Returns
true if it is the reserved extension

◆ get_elf_debug_file_directory()

idaman const char *ida_export get_elf_debug_file_directory ( )

Get the value of the ELF_DEBUG_FILE_DIRECTORY configuration directive.

Variable Documentation

◆ va

idaman va_list va

◆ PLUGIN

idaman ida_module_data plugin_t PLUGIN