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
	Read i/o port definitions from a config file. More...

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, 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); }

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:

each directory specified by IDAUSR%

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

◆ 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

Detailed Description

Classes

Functions

Loader Input Source

Macros

Typedefs

Macro Definition Documentation

◆ DEF_LREADBYTES

Enumeration Type Documentation

◆ linput_type_t

Function Documentation

◆ getsysfile()

◆ get_user_idadir()

◆ get_ida_subdirs()

◆ get_special_folder()

◆ fopenWT()

◆ fopenWB()

◆ fopenRT()

◆ fopenRB()

◆ fopenM()

◆ fopenA()

◆ openR()

◆ openRT()

◆ openM()

◆ echsize()

◆ get_free_disk_space()

◆ choose_ioport_device()

◆ call_system()

◆ lread()

◆ qlread()

◆ qlgets()

◆ qlgetc()

◆ lreadbytes()

◆ qlgetz()

◆ qlseek()

◆ qlfile()

◆ make_linput()

◆ create_generic_linput()

◆ create_memory_linput()