File-IO

Typedefs
typedef struct ASYNCIO	ASYNCIO
typedef void *	IOHANDLE

Enumerations
enum	{ IOFLAG_READ = 1 , IOFLAG_WRITE = 2 , IOFLAG_APPEND = 4 }
enum	ESeekOrigin { IOSEEK_START = 0 , IOSEEK_CUR = 1 , IOSEEK_END = 2 }

Functions
IOHANDLE	io_open (const char *filename, int flags)
unsigned	io_read (IOHANDLE io, void *buffer, unsigned size)
bool	io_read_all (IOHANDLE io, void **result, unsigned *result_len)
char *	io_read_all_str (IOHANDLE io)
int	io_skip (IOHANDLE io, int64_t size)
int	io_seek (IOHANDLE io, int64_t offset, ESeekOrigin origin)
int64_t	io_tell (IOHANDLE io)
int64_t	io_length (IOHANDLE io)
unsigned	io_write (IOHANDLE io, const void *buffer, unsigned size)
bool	io_write_newline (IOHANDLE io)
int	io_close (IOHANDLE io)
int	io_flush (IOHANDLE io)
int	io_sync (IOHANDLE io)
int	io_error (IOHANDLE io)
IOHANDLE	io_stdin ()
IOHANDLE	io_stdout ()
IOHANDLE	io_stderr ()
IOHANDLE	io_current_exe ()
ASYNCIO *	aio_new (IOHANDLE io)
void	aio_lock (ASYNCIO *aio)
void	aio_unlock (ASYNCIO *aio)
void	aio_write (ASYNCIO *aio, const void *buffer, unsigned size)
void	aio_write_newline (ASYNCIO *aio)
void	aio_write_unlocked (ASYNCIO *aio, const void *buffer, unsigned size)
void	aio_write_newline_unlocked (ASYNCIO *aio)
int	aio_error (ASYNCIO *aio)
void	aio_close (ASYNCIO *aio)
void	aio_wait (ASYNCIO *aio)
void	aio_free (ASYNCIO *aio)

Detailed Description

I/O related operations.

Typedef Documentation

ASYNCIO

typedef struct ASYNCIO ASYNCIO

Wrapper for asynchronously writing to an IOHANDLE.

IOHANDLE

typedef void* IOHANDLE

Handle for input/output files/streams.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
IOFLAG_READ	Open file for reading. See also io_open
IOFLAG_WRITE	Open file for writing. See also io_open
IOFLAG_APPEND	Open file for appending at the end. See also io_open

ESeekOrigin

enum ESeekOrigin

Enumerator
IOSEEK_START	Start seeking from the beginning of the file. See also io_seek
IOSEEK_CUR	Start seeking from the current position. See also io_seek
IOSEEK_END	Start seeking from the end of the file. See also io_seek

Function Documentation

aio_close()

void aio_close

(

ASYNCIO *

aio

)

Queues file closing.

Parameters

aio	Handle to the file.

aio_error()

int aio_error

(

ASYNCIO *

aio

)

Checks whether errors have occurred during the asynchronous writing.

Call this function regularly to see if there are errors. Call this function after aio_wait to see if the process of writing to the file succeeded.

Parameters

aio	Handle to the file.

Returns

0 on success, or non-0 on error.

aio_free()

void aio_free

(

ASYNCIO *

aio

)

Frees the resources associated with the asynchronous file handle.

Parameters

aio	Handle to the file.

aio_lock()

void aio_lock

(

ASYNCIO *

aio

)

Locks the ASYNCIO structure so it can't be written into by other threads.

Parameters

aio	Handle to the file.

aio_new()

ASYNCIO * aio_new

(

IOHANDLE

io

)

Wraps a IOHANDLE for asynchronous writing.

Parameters

io	Handle to the file.

Returns

The handle for asynchronous writing.

aio_unlock()

void aio_unlock

(

ASYNCIO *

aio

)

Unlocks the ASYNCIO structure after finishing the contiguous write.

Parameters

aio	Handle to the file.

aio_wait()

void aio_wait

(

ASYNCIO *

aio

)

Wait for the asynchronous operations to complete.

Parameters

aio	Handle to the file.

aio_write()

void aio_write	(	ASYNCIO *	aio,
		const void *	buffer,
		unsigned	size
	)

Queues a chunk of data for writing.

Parameters

aio	Handle to the file.
buffer	Pointer to the data that should be written.
size	Number of bytes to write.

aio_write_newline()

void aio_write_newline

(

ASYNCIO *

aio

)

Queues a newline for writing.

Parameters

aio	Handle to the file.

aio_write_newline_unlocked()

void aio_write_newline_unlocked

(

ASYNCIO *

aio

)

Queues a newline for writing. The ASYNCIO struct must be locked using aio_lock first.

Parameters

aio	Handle to the file.

aio_write_unlocked()

void aio_write_unlocked	(	ASYNCIO *	aio,
		const void *	buffer,
		unsigned	size
	)

Queues a chunk of data for writing. The ASYNCIO struct must be locked using aio_lock first.

Parameters

aio	Handle to the file.
buffer	Pointer to the data that should be written.
size	Number of bytes to write.

io_close()

int io_close

(

IOHANDLE

io

)

Closes a file.

Parameters

io	Handle to the file.

Returns

0 on success.

io_current_exe()

IOHANDLE io_current_exe

(

)

Returns a handle for the current executable.

Returns

An IOHANDLE for the current executable.

io_error()

int io_error

(

IOHANDLE

io

)

Checks whether an error occurred during I/O with the file.

Parameters

io	Handle to the file.

Returns

0 on success, or non-0 on error.

io_flush()

int io_flush

(

IOHANDLE

io

)

Empties all buffers and writes all pending data.

Parameters

io	Handle to the file.

Returns

0 on success.

io_length()

int64_t io_length

(

IOHANDLE

io

)

Gets the total length of the file. Resets cursor to the beginning.

Parameters

io	Handle to the file.

Returns

The total size, or -1 on failure.

io_open()

IOHANDLE io_open	(	const char *	filename,
		int	flags
	)

Opens a file.

Parameters

filename	File to open.
flags	A set of IOFLAG flags.

See also

IOFLAG_READ, IOFLAG_WRITE, IOFLAG_APPEND.

Returns

A handle to the file on success, or nullptr on failure.

io_read()

unsigned io_read	(	IOHANDLE	io,
		void *	buffer,
		unsigned	size
	)

Reads data into a buffer from a file.

Parameters

io	Handle to the file to read data from.
buffer	Pointer to the buffer that will receive the data.
size	Number of bytes to read from the file.

Returns

Number of bytes read.

io_read_all()

bool io_read_all	(	IOHANDLE	io,
		void **	result,
		unsigned *	result_len
	)

Reads the rest of the file into a buffer.

Parameters

io	Handle to the file to read data from.
result	Receives the file's remaining contents.
result_len	Receives the file's remaining length.

Returns

true on success, false on failure.

Remarks

Does NOT guarantee that there are no internal null bytes.

The result must be freed after it has been used.

The function will fail if more than 1 GiB of memory would have to be allocated. Large files should not be loaded into memory.

io_read_all_str()

char * io_read_all_str

(

IOHANDLE

io

)

Reads the rest of the file into a null-terminated buffer with no internal null bytes.

Parameters

io	Handle to the file to read data from.

Returns

The file's remaining contents, or nullptr on failure.

Remarks

Guarantees that there are no internal null bytes.

Guarantees that result will contain null-termination.

The result must be freed after it has been used.

The function will fail if more than 1 GiB of memory would have to be allocated. Large files should not be loaded into memory.

io_seek()

int io_seek	(	IOHANDLE	io,
		int64_t	offset,
		ESeekOrigin	origin
	)

Seeks to a specified offset in the file.

Parameters

io	Handle to the file.
offset	Offset from position to search.
origin	Position to start searching from.

Returns

0 on success.

io_skip()

int io_skip	(	IOHANDLE	io,
		int64_t	size
	)

Skips data in a file.

Parameters

io	Handle to the file.
size	Number of bytes to skip.

Returns

0 on success.

io_stderr()

IOHANDLE io_stderr

(

)

Returns a handle for the standard error.

Returns

An IOHANDLE for the standard error.

Remarks

The handle must not be closed.

io_stdin()

IOHANDLE io_stdin

(

)

Returns a handle for the standard input.

Returns

An IOHANDLE for the standard input.

Remarks

The handle must not be closed.

io_stdout()

IOHANDLE io_stdout

(

)

Returns a handle for the standard output.

Returns

An IOHANDLE for the standard output.

Remarks

The handle must not be closed.

io_sync()

int io_sync

(

IOHANDLE

io

)

Synchronize file changes to disk.

Parameters

io	Handle to the file.

Returns

0 on success.

io_tell()

int64_t io_tell

(

IOHANDLE

io

)

Gets the current position in the file.

Parameters

io	Handle to the file.

Returns

The current position, or -1 on failure.

io_write()

unsigned io_write	(	IOHANDLE	io,
		const void *	buffer,
		unsigned	size
	)

Writes data from a buffer to a file.

Parameters

io	Handle to the file.
buffer	Pointer to the data that should be written.
size	Number of bytes to write.

Returns

Number of bytes written.

io_write_newline()

bool io_write_newline

(

IOHANDLE

io

)

Writes a platform dependent newline to a file.

Parameters

io	Handle to the file.

Returns

true on success, false on failure.