| 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 | file_enumerator_t
| Enumerate files in the specified directory. More...
struct | ioport_bit_t
| Describes an I/O port bit. More...
struct | ioport_t
| Describes an I/O port. More...
struct | ioports_fallback_t
struct | choose_ioport_parser_t
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_... functions as a data supplier (see kernwin.hpp) More...

## Functions
idaman THREAD_SAFE const char *ida_export | idadir (const char *subdir)
| Get IDA directory (if subdir==nullptr) 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, file_enumerator_t &fv)
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)=nullptr)
| Read i/o port definitions from a config file. More...
idaman THREAD_SAFE ssize_t ida_export | read_ioports2 (ioports_t *ports, qstring *device, const char *file, ioports_fallback_t *callback=nullptr)
idaman THREAD_SAFE bool ida_export | choose_ioport_device (qstring *_device, const char *file, const char *(idaapi *parse_params)(qstring *buf, const char *line)=nullptr)
| Allow the user to choose the ioport device. More...
idaman THREAD_SAFE bool ida_export | choose_ioport_device2 (qstring *_device, const char *file, choose_ioport_parser_t *parse_params)
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 at destruction-time.
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...
qoff64_t 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...
THREAD_SAFE 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 | THM_SUBDIR "themes"
#define | IDA_SUBDIR_IDP 0x0001
| append the processor name as a subdirectory
#define | IDA_SUBDIR_IDADIR_FIRST 0x0002
| $IDADIR/subdir will be first, not last
#define | IDA_SUBDIR_ONLY_EXISTING 0x0004
| only existing directories will be present
#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_t > | ioport_bits_t
typedef qvector< ioport_t > | ioports_t

## Macro Definition Documentation

## ◆ DEF_LREADBYTES

#define DEF_LREADBYTES | ( |  | read,
|  |  | type,
|  |  | size
| ) |  |

Value:
\
inline int idaapi read(linput_t *li, type *res, bool mf) \
{ return lreadbytes(li, res, size, mf); }
lreadbytes
idaman int ida_export lreadbytes(linput_t *li, void *buf, size_t size, bool mf)
Read multiple bytes and swap if necessary.

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

## Enumeration Type Documentation

## ◆ linput_type_t

enum linput_type_t

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

## ◆ getsysfile()

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] | buf | buffer for file name
     | bufsize | size of output buffer
     | filename | name of file to search
     | subdir | if specified, the file is looked for in the specified subdirectory of the ida directory first (see IDA subdirectories)

   Returns
     nullptr if not found, otherwise a pointer to full file name.

## ◆ get_user_idadir()

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 %APPDATA%Hex-Rays/IDA Pro)

## ◆ get_ida_subdirs()

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)]
- $IDADIR/subdir

Parameters

  [out] | dirs | output vector for directory names
  | subdir | name of the resource to list (can be nullptr)
  | flags | Subdirectory modification flags bits

Returns
  number of directories appended to 'dirs'

## ◆ get_special_folder()

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

## ◆ fopenWT()

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
  nullptr if failure

## ◆ fopenWB()

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
  nullptr if failure

## ◆ fopenRT()

idaman THREAD_SAFE FILE *ida_export fopenRT | ( | const char * | file | ) |

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

Returns
  nullptr if failure

## ◆ fopenRB()

idaman THREAD_SAFE FILE *ida_export fopenRB | ( | const char * | file | ) |

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

Returns
  nullptr if failure

## ◆ fopenM()

idaman THREAD_SAFE FILE *ida_export fopenM | ( | const char * | file | ) |

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

Returns
  nullptr if failure

## ◆ fopenA()

idaman THREAD_SAFE FILE *ida_export fopenA | ( | const char * | file | ) |

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

Returns
  nullptr if failure

## ◆ openR()

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.

## ◆ openRT()

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.

## ◆ openM()

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.

## ◆ echsize()

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

  fp | pointer to file
  size | new size of file

## ◆ get_free_disk_space()

idaman THREAD_SAFE uint64 ida_export get_free_disk_space | ( | const char * | path | ) |

Get free disk space in bytes.

Parameters

  path | name of any directory on the disk to get information about

## ◆ read_ioports()

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 = `nullptr`
| ) |  |

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] | ports | output vector
  | device | contains device name to load. If default_device[0] == 0 then the default device is determined by .default directive in the config file.
  | file | config file name
  | callback | callback to call when the input line can't be parsed normally. line: input line to parse returns error message. if nullptr, then the line is parsed ok.

Returns
  -1 on error or size of vector

## ◆ choose_ioport_device()

idaman THREAD_SAFE bool ida_export choose_ioport_device | ( | qstring * | _device,
|  | const char * | file,
|  | const char *(idaapi *)(qstring *buf, const char *line) | parse_params = `nullptr`
| ) |  |

Allow the user to choose the ioport device.

Parameters

  [in,out] | _device | in: 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
  | file | config file name
  | parse_params | if present (non nullptr), 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

  true | the user selected a device, its name is in 'device'
  false | the selection was cancelled. if device=="NONE" upon return, then no devices were found in the configuration file

## ◆ call_system()

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

  command | command to execute. If nullptr, an interactive shell is activated

Returns
  the error code returned by system() call

## ◆ lread()

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!

## ◆ qlread()

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

## ◆ qlgets()

idaman char *ida_export qlgets | ( | char * | s,
|  | size_t | len,
|  | linput_t * | li
| ) |  |

Read one line from the input source.

Returns
  nullptr if failure, otherwise 's'

## ◆ qlgetc()

idaman int ida_export qlgetc | ( | linput_t * | li | ) |

Read one character from the input source.

Returns
  EOF if failure, otherwise the read character

## ◆ lreadbytes()

idaman int ida_export lreadbytes | ( | linput_t * | li,
|  | void * | buf,
|  | size_t | size,
|  | bool | mf
| ) |  |

Read multiple bytes and swap if necessary.

Parameters

  li | input file
  buf | pointer to output buffer
  size | number of bytes to read
  mf | big endian?

Return values

  0 | ok
  -1 | failure

## ◆ qlgetz()

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.

## ◆ qlseek()

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!)

## ◆ qlfile()

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 nullptr. Otherwise return the underlying FILE* Please do not use this function if possible.

## ◆ make_linput()

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.

## ◆ create_generic_linput()

idaman THREAD_SAFE linput_t *ida_export create_generic_linput | ( | generic_linput_t * | gl | ) |

Create a generic linput.

Parameters

  gl | linput description. this object will be destroyed by close_linput() using "delete gl;"

## ◆ create_memory_linput()

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

  start | starting address of the input
  size | size of the memory area to represent as linput if unknown, may be passed as 0