IDA SDK
Classes | Functions | Macros | Typedefs
diskio.hpp File Reference

Detailed Description

File I/O functions for IDA.

You should not use standard C file I/O functions in modules. Use functions from this header, pro.h and fpro.h instead.

This file also declares a call_system() function.

Classes

struct  ioport_bit_t
 Describes an I/O port bit. More...
 
struct  ioport_t
 Describes an I/O port. More...
 
struct  generic_linput_t
 Generic linput class - may be used to create a linput_t instance for any data source. More...
 
class  linput_buffer_t
 Helper class - adapts linput to be used in extract_... More...
 

Functions

idaman THREAD_SAFE const char *ida_export idadir (const char *subdir)
 Get IDA directory (if subdir==NULL) or the specified subdirectory (see IDA subdirectories)
 
idaman THREAD_SAFE char *ida_export getsysfile (char *buf, size_t bufsize, const char *filename, const char *subdir)
 Search for IDA system file. More...
 
idaman THREAD_SAFE const char *ida_export get_user_idadir (void)
 Get user ida related directory. More...
 
idaman THREAD_SAFE int ida_export get_ida_subdirs (qstrvec_t *dirs, const char *subdir, int flags=0)
 Get list of directories in which to find a specific IDA resource (see IDA subdirectories). More...
 
idaman THREAD_SAFE bool ida_export get_special_folder (char *buf, size_t bufsize, int csidl)
 Get a folder location by CSIDL (see Common CSIDLs). More...
 
idaman THREAD_SAFE int ida_export enumerate_files (char *answer, size_t answer_size, const char *path, const char *fname, int(idaapi *func)(const char *file, void *ud), void *ud=NULL)
 Enumerate files in the specified directory. More...
 
idaman THREAD_SAFE uint64 ida_export qfsize (FILE *fp)
 Get length of file in bytes. More...
 
idaman THREAD_SAFE void ida_export echsize (FILE *fp, uint64 size)
 Change size of file or die. More...
 
idaman THREAD_SAFE uint64 ida_export get_free_disk_space (const char *path)
 Get free disk space in bytes. More...
 
idaman THREAD_SAFE ssize_t ida_export read_ioports (ioports_t *ports, qstring *device, const char *file, const char *(idaapi *callback)( const ioports_t &ports, const char *line)=NULL)
 Read i/o port definitions from a config file. More...
 
idaman THREAD_SAFE bool ida_export choose_ioport_device (qstring *_device, const char *file, const char *(idaapi *parse_params)( qstring *buf, const char *line)=NULL)
 Allow the user to choose the ioport device. More...
 
idaman THREAD_SAFE const ioport_t *ida_export find_ioport (const ioports_t &ports, ea_t address)
 Find ioport in the array of ioports.
 
idaman THREAD_SAFE const ioport_bit_t *ida_export find_ioport_bit (const ioports_t &ports, ea_t address, size_t bit)
 Find ioport bit in the array of ioports.
 
idaman THREAD_SAFE int ida_export call_system (const char *command)
 Execute a operating system command. More...
 
Open/Read/Write/Close Files

There are two sets of "open file" functions.

The first set tries to open a file and returns success or failure. The second set is "open or die": if the file cannot be opened then the function will display an error message and exit.

idaman THREAD_SAFE FILE *ida_export fopenWT (const char *file)
 Open a new file for write in text mode, deny write. More...
 
idaman THREAD_SAFE FILE *ida_export fopenWB (const char *file)
 Open a new file for write in binary mode, deny read/write. More...
 
idaman THREAD_SAFE FILE *ida_export fopenRT (const char *file)
 Open a file for read in text mode, deny none. More...
 
idaman THREAD_SAFE FILE *ida_export fopenRB (const char *file)
 Open a file for read in binary mode, deny none. More...
 
idaman THREAD_SAFE FILE *ida_export fopenM (const char *file)
 Open a file for read/write in binary mode, deny write. More...
 
idaman THREAD_SAFE FILE *ida_export fopenA (const char *file)
 Open a file for append in text mode, deny none. More...
 
idaman THREAD_SAFE FILE *ida_export openR (const char *file)
 Open a file for read in binary mode or die, deny none. More...
 
idaman THREAD_SAFE FILE *ida_export openRT (const char *file)
 Open a file for read in text mode or die, deny none. More...
 
idaman THREAD_SAFE FILE *ida_export openM (const char *file)
 Open a file for read/write in binary mode or die, deny write. More...
 

Loader Input Source

Starting with v4.8 IDA can load and run remote files.

In order to do that, we replace the FILE* in the loader modules with an abstract input source (linput_t). The source might be linked to a local or remote file.

#define DEF_LREADBYTES(read, type, size)
 Helper to define lread2bytes(), lread4bytes(), etc. More...
 
enum  linput_type_t {
  LINPUT_NONE, LINPUT_LOCAL, LINPUT_RFILE, LINPUT_PROCMEM,
  LINPUT_GENERIC
}
 loader input source More...
 
typedef janitor_t< linput_t * > linput_janitor_t
 Object that will free an linput_t upon deletion.
 
idaman void ida_export lread (linput_t *li, void *buf, size_t size)
 Read the input source. More...
 
idaman ssize_t ida_export qlread (linput_t *li, void *buf, size_t size)
 Read the input source. More...
 
idaman char *ida_export qlgets (char *s, size_t len, linput_t *li)
 Read one line from the input source. More...
 
idaman int ida_export qlgetc (linput_t *li)
 Read one character from the input source. More...
 
idaman int ida_export lreadbytes (linput_t *li, void *buf, size_t size, bool mf)
 Read multiple bytes and swap if necessary. More...
 
int idaapi lread2bytes (linput_t *li, int16 *res, bool mf)
 Read a value from linput - also see lreadbytes()
 
int idaapi lread2bytes (linput_t *li, uint16 *res, bool mf)
 Read a value from linput - also see lreadbytes()
 
int idaapi lread4bytes (linput_t *li, int32 *res, bool mf)
 Read a value from linput - also see lreadbytes()
 
int idaapi lread4bytes (linput_t *li, uint32 *res, bool mf)
 Read a value from linput - also see lreadbytes()
 
int idaapi lread8bytes (linput_t *li, int64 *res, bool mf)
 Read a value from linput - also see lreadbytes()
 
int idaapi lread8bytes (linput_t *li, uint64 *res, bool mf)
 Read a value from linput - also see lreadbytes()
 
idaman char *ida_export qlgetz (linput_t *li, int64 fpos, char *buf, size_t bufsize)
 Read a zero-terminated string from the input. More...
 
idaman int64 ida_export qlsize (linput_t *li)
 Get the input source size.
 
idaman qoff64_t ida_export qlseek (linput_t *li, qoff64_t pos, int whence=SEEK_SET)
 Set input source position. More...
 
int64 idaapi qltell (linput_t *li)
 Get input source position.
 
idaman linput_t *ida_export open_linput (const char *file, bool remote)
 Open loader input.
 
idaman THREAD_SAFE void ida_export close_linput (linput_t *li)
 Close loader input.
 
idaman THREAD_SAFE FILE *ida_export qlfile (linput_t *li)
 Get FILE* from the input source. More...
 
idaman THREAD_SAFE linput_t *ida_export make_linput (FILE *fp)
 Convert FILE * to input source. More...
 
idaman THREAD_SAFE void ida_export unmake_linput (linput_t *li)
 Free an linput_t object (also see make_linput())
 
idaman THREAD_SAFE linput_t *ida_export create_generic_linput (generic_linput_t *gl)
 Create a generic linput. More...
 
idaman THREAD_SAFE linput_t *ida_export create_bytearray_linput (const uchar *start, size_t size)
 Trivial memory linput.
 
idaman linput_t *ida_export create_memory_linput (ea_t start, asize_t size)
 Create a linput for process memory. More...
 
linput_type_t idaapi get_linput_type (linput_t *li)
 Get linput type.
 

Macros

#define CFG_SUBDIR   "cfg"
 
#define IDC_SUBDIR   "idc"
 
#define IDS_SUBDIR   "ids"
 
#define IDP_SUBDIR   "procs"
 
#define LDR_SUBDIR   "loaders"
 
#define SIG_SUBDIR   "sig"
 
#define TIL_SUBDIR   "til"
 
#define PLG_SUBDIR   "plugins"
 
#define IDA_SUBDIR_IDP   0x0001
 append the processor name as a subdirectory
 
#define CSIDL_APPDATA   0x001a
 
#define CSIDL_LOCAL_APPDATA   0x001c
 
#define CSIDL_PROGRAM_FILES   0x0026
 
#define CSIDL_PROGRAM_FILES_COMMON   0x002b
 
#define CSIDL_PROGRAM_FILESX86   0x002a
 
#define IOPORT_SKIP_DEVICE   ((const char *)(-1))
 See 'parse_params' parameter to choose_ioport_device()
 

Typedefs

typedef qvector< ioport_bit_tioport_bits_t
 
typedef qvector< ioport_tioports_t
 

Macro Definition Documentation

#define DEF_LREADBYTES (   read,
  type,
  size 
)
Value:
\
inline int idaapi read(linput_t *li, type *res, bool mf) \
{ return lreadbytes(li, res, size, mf); }
idaman int ida_export lreadbytes(linput_t *li, void *buf, size_t size, bool mf)
Read multiple bytes and swap if necessary.
#define idaapi
specifies __stdcall calling convention
Definition: pro.h:239

Helper to define lread2bytes(), lread4bytes(), etc.

Enumeration Type Documentation

loader input source

linput types

Enumerator
LINPUT_NONE 

invalid linput

LINPUT_LOCAL 

local file

LINPUT_RFILE 

remote file ( debugger_t::open_file, debugger_t::read_file)

LINPUT_PROCMEM 

debugged process memory (read_dbg_memory())

LINPUT_GENERIC 

generic linput

Function Documentation

idaman THREAD_SAFE char* ida_export getsysfile ( char *  buf,
size_t  bufsize,
const char *  filename,
const char *  subdir 
)

Search for IDA system file.

This function searches for a file in:

  1. each directory specified by IDAUSR%
  2. ida directory [+ subdir] and returns the first match.
    Parameters
    [out]bufbuffer for file name
    bufsizesize of output buffer
    filenamename of file to search
    subdirif specified, the file is looked for in the specified subdirectory of the ida directory first (see IDA subdirectories)
    Returns
    NULL if not found, otherwise a pointer to full file name.
idaman THREAD_SAFE const char* ida_export get_user_idadir ( void  )

Get user ida related directory.

  • if $IDAUSR is defined:
    • the first element in $IDAUSR
  • else
    • default user directory ($HOME/.idapro or APPDATAHex-Rays/IDA Pro)
idaman THREAD_SAFE int ida_export get_ida_subdirs ( qstrvec_t dirs,
const char *  subdir,
int  flags = 0 
)

Get list of directories in which to find a specific IDA resource (see IDA subdirectories).

The order of the resulting list is as follows:

  • [$IDAUSR/subdir (0..N entries)]
  • $ENVVAR for backwards compatibility with some subdirs that could be overriden with environment variables, such as $IDASGN, $IDAIDS, $IDAIDC, and $IDATIL.
  • $IDADIR/subdir
    Parameters
    [out]dirsoutput vector for directory names
    subdirname of the resource to list
    flagsSubdirectory modification flags bits
    Returns
    number of directories appended to 'dirs'
idaman THREAD_SAFE bool ida_export get_special_folder ( char *  buf,
size_t  bufsize,
int  csidl 
)

Get a folder location by CSIDL (see Common CSIDLs).

Path should be of at least MAX_PATH size

idaman THREAD_SAFE int ida_export enumerate_files ( char *  answer,
size_t  answer_size,
const char *  path,
const char *  fname,
int(idaapi *)(const char *file, void *ud)  func,
void *  ud = NULL 
)

Enumerate files in the specified directory.

Parameters
[out]answerbuffer to contain the file name for which func()!=0 (may be NULL)
answer_sizesize of 'answer'
pathdirectory to enumerate files in
fnamemask of file names to enumerate
funccallback function called for each file
  • file: full file name (with path)
  • ud: user data
  • if returns non-zero value, the enumeration is stopped and the return code is is returned to the caller.
uduser data. this pointer will be passed to the callback function
Returns
zero or the code returned by 'func'
idaman THREAD_SAFE FILE* ida_export fopenWT ( const char *  file)

Open a new file for write in text mode, deny write.

If a file exists, it will be removed.

Returns
NULL if failure
idaman THREAD_SAFE FILE* ida_export fopenWB ( const char *  file)

Open a new file for write in binary mode, deny read/write.

If a file exists, it will be removed.

Returns
NULL if failure
idaman THREAD_SAFE FILE* ida_export fopenRT ( const char *  file)

Open a file for read in text mode, deny none.

Returns
NULL if failure
idaman THREAD_SAFE FILE* ida_export fopenRB ( const char *  file)

Open a file for read in binary mode, deny none.

Returns
NULL if failure
idaman THREAD_SAFE FILE* ida_export fopenM ( const char *  file)

Open a file for read/write in binary mode, deny write.

Returns
NULL if failure
idaman THREAD_SAFE FILE* ida_export fopenA ( const char *  file)

Open a file for append in text mode, deny none.

Returns
NULL if failure
idaman THREAD_SAFE FILE* ida_export openR ( const char *  file)

Open a file for read in binary mode or die, deny none.

If a file cannot be opened, this function displays a message and exits.

idaman THREAD_SAFE FILE* ida_export openRT ( const char *  file)

Open a file for read in text mode or die, deny none.

If a file cannot be opened, this function displays a message and exits.

idaman THREAD_SAFE FILE* ida_export openM ( const char *  file)

Open a file for read/write in binary mode or die, deny write.

If a file cannot be opened, this function displays a message and exits.

idaman THREAD_SAFE uint64 ida_export qfsize ( FILE *  fp)

Get length of file in bytes.

Parameters
fppointer to file
idaman THREAD_SAFE void ida_export echsize ( FILE *  fp,
uint64  size 
)

Change size of file or die.

If an error occurs, this function displays a message and exits.

Parameters
fppointer to file
sizenew size of file
idaman THREAD_SAFE uint64 ida_export get_free_disk_space ( const char *  path)

Get free disk space in bytes.

Parameters
pathname of any directory on the disk to get information about
idaman THREAD_SAFE ssize_t ida_export read_ioports ( ioports_t ports,
qstring device,
const char *  file,
const char *(idaapi *)( const ioports_t &ports, const char *line)  callback = NULL 
)

Read i/o port definitions from a config file.

Each device definition in the input file begins with a line like this:

.devicename 

After it go the port definitions in this format:

portname          address 

The bit definitions (optional) are represented like this:

portname.bitname  bitnumber 

Lines beginning with a space are ignored. comment lines should be started with ';' character.

The default device is specified at the start of the file:

.default device_name 
Note
It is permissible to have a symbol mapped to several addresses but all addresses must be unique.
Parameters
[out]portsoutput vector
devicecontains device name to load. If default_device[0] == 0 then the default device is determined by .default directive in the config file.
fileconfig file name
callbackcallback to call when the input line can't be parsed normally.
  • line: input line to parse
  • returns error message. if NULL, then the line is parsed ok.
Returns
-1 on error or size of vector
idaman THREAD_SAFE bool ida_export choose_ioport_device ( qstring _device,
const char *  file,
const char *(idaapi *)( qstring *buf, const char *line)  parse_params = NULL 
)

Allow the user to choose the ioport device.

Parameters
[in,out]devicein: contains default device name. If default_device[0] == 0 then the default device is determined by .default directive in the config file. out: the selected device name
fileconfig file name
parse_paramsif present (non NULL), then defines a callback which will be called for all lines not starting with a dot (.) This callback may parse these lines are prepare a simple processor parameter string. This string will be displayed along with the device name. If it returns IOPORT_SKIP_DEVICE, then the current device will not be included in the list.
Return values
truethe user selected a device, its name is in 'device'
falsethe selection was cancelled. if device=="NONE" upon return, then no devices were found in the configuration file
idaman THREAD_SAFE int ida_export call_system ( const char *  command)

Execute a operating system command.

This function suspends the interface (Tvision), runs the command and redraws the screen.

Parameters
commandcommand to execute. If NULL, an interactive shell is activated
Returns
the error code returned by system() call
idaman void ida_export lread ( linput_t *  li,
void *  buf,
size_t  size 
)

Read the input source.

If failed, inform the user and ask him if he wants to continue. If he does not, this function will not return (loader_failure() will be called). This function may be called only from loaders!

idaman ssize_t ida_export qlread ( linput_t *  li,
void *  buf,
size_t  size 
)

Read the input source.

Returns
number of read bytes or -1
idaman char* ida_export qlgets ( char *  s,
size_t  len,
linput_t *  li 
)

Read one line from the input source.

Returns
NULL if failure, otherwise 's'
idaman int ida_export qlgetc ( linput_t *  li)

Read one character from the input source.

Returns
EOF if failure, otherwise the read character
idaman int ida_export lreadbytes ( linput_t *  li,
void *  buf,
size_t  size,
bool  mf 
)

Read multiple bytes and swap if necessary.

Parameters
liinput file
bufpointer to output buffer
sizenumber of bytes to read
mfbig endian?
Return values
0ok
-1failure
idaman char* ida_export qlgetz ( linput_t *  li,
int64  fpos,
char *  buf,
size_t  bufsize 
)

Read a zero-terminated string from the input.

If fpos == -1 then no seek will be performed.

idaman qoff64_t ida_export qlseek ( linput_t *  li,
qoff64_t  pos,
int  whence = SEEK_SET 
)

Set input source position.

Returns
the new position (not 0 as fseek!)
idaman THREAD_SAFE FILE* ida_export qlfile ( linput_t *  li)

Get FILE* from the input source.

If the input source is linked to a remote file, then return NULL. Otherwise return the underlying FILE* Please do not use this function if possible.

idaman THREAD_SAFE linput_t* ida_export make_linput ( FILE *  fp)

Convert FILE * to input source.

Used for temporary linput_t objects - call unmake_linput() to free the slot after the use.

idaman THREAD_SAFE linput_t* ida_export create_generic_linput ( generic_linput_t gl)

Create a generic linput.

Parameters
gllinput description. this object will be destroyed by close_linput() using "delete gl;"
idaman linput_t* ida_export create_memory_linput ( ea_t  start,
asize_t  size 
)

Create a linput for process memory.

This linput will use read_dbg_memory() to read data.

Parameters
startstarting address of the input
sizesize of the memory area to represent as linput if unknown, may be passed as 0