File I/O

Read/write to files. More...

Data Structures
struct	bio_file_t
	Handle to a file. More...
struct	bio_stat_t
	Statistics about a file. More...

Functions
bool	bio_fdopen (bio_file_t *file_ptr, uintptr_t fd, bio_error_t *error)
	Wraps a handle from the OS into a bio_file_t.
uintptr_t	bio_funwrap (bio_file_t file)
	Retrieve an OS handle from a bio_file_t.
bool	bio_fopen (bio_file_t *file_ptr, const char *restrict filename, const char *restrict mode, bio_error_t *error)
	Open a file for reading or writing.
size_t	bio_fwrite (bio_file_t file, const void *buf, size_t size, bio_error_t *error)
	Write to a file.
size_t	bio_fread (bio_file_t file, void *buf, size_t size, bio_error_t *error)
	Read from a file.
bool	bio_fseek (bio_file_t file, int64_t offset, int origin, bio_error_t *error)
	Modify the file offset.
int64_t	bio_ftell (bio_file_t file, bio_error_t *error)
	Retrieve the file offset.
bool	bio_fflush (bio_file_t file, bio_error_t *error)
	Flush the file buffer.
bool	bio_fclose (bio_file_t file, bio_error_t *error)
	Close a file handle.
bool	bio_fstat (bio_file_t file, bio_stat_t *stat, bio_error_t *error)
	Retrieves statistics about a file.
static size_t	bio_fwrite_exactly (bio_file_t file, const void *buf, size_t size, bio_error_t *error)
	Convenient function to write exactly a number of bytes to a file without short write.
static size_t	bio_fread_exactly (bio_file_t file, void *buf, size_t size, bio_error_t *error)
	Convenient function to read exactly a number of bytes from a file without short read.

Variables
bio_file_t	BIO_STDIN
	Standard input.
bio_file_t	BIO_STDOUT
	Standard output.
bio_file_t	BIO_STDERR
	Standard error.

Detailed Description

Read/write to files.

Function Documentation

bio_fclose()

bool bio_fclose	(	bio_file_t	file,
		bio_error_t *	error
	)

Close a file handle.

bio_fdopen()

bool bio_fdopen	(	bio_file_t *	file_ptr,
		uintptr_t	fd,
		bio_error_t *	error
	)

Wraps a handle from the OS into a bio_file_t.

This can be used for platform-specific special files (e.g: memfd in Linux, mailslot in Windows).

Remarks

bio has its own internal file offset handling. This is required when using asynchronous I/O API in many platforms. Thus, if a file offset was set before being passed to this function, it will have no effect.

Parameters

file_ptr	Pointer to a file handle. This will only be set if the open was successful.
fd	A platform-specific handle. For Unix platforms, it is a file descriptor. For Windows, it is a HANDLE.
error	See Error handling.

Returns

Whether this was successful.

bio_fflush()

bool bio_fflush	(	bio_file_t	file,
		bio_error_t *	error
	)

Flush the file buffer.

This is similar to stdlib flush.

Remarks

Unlike the stdlib, bio does not do any userspace buffering. This flushes the OS buffer.

bio_fopen()

bool bio_fopen	(	bio_file_t *	file_ptr,
		const char *restrict	filename,
		const char *restrict	mode,
		bio_error_t *	error
	)

Open a file for reading or writing.

This is similar to stdlib fopen_s.

Parameters

file_ptr	Pointer to a file handle. This will only be set if the open was successful.
filename	The file to open.
mode	Mode string
error	See Error handling

Returns

Whether this was successful.

bio_fread()

size_t bio_fread	(	bio_file_t	file,
		void *	buf,
		size_t	size,
		bio_error_t *	error
	)

Read from a file.

This is similar to stdlib fread.

Remarks

Short read is possible.

See also

bio_fread_exactly

bio_fread_exactly()

static size_t bio_fread_exactly ( bio_file_t  file, void *  buf, size_t  size, bio_error_t *  error  )

inlinestatic

Convenient function to read exactly a number of bytes from a file without short read.

Remarks

If an error was encountered while reading, it is still possible for this function to read fewer bytes. Always check error.

bio_fseek()

bool bio_fseek	(	bio_file_t	file,
		int64_t	offset,
		int	origin,
		bio_error_t *	error
	)

Modify the file offset.

This is similar to stdlib fseek.

Remarks

bio maintains its own file offset which has no relation to the offset maintained by synchronous file API provided by the OS.

bio_fstat()

bool bio_fstat	(	bio_file_t	file,
		bio_stat_t *	stat,
		bio_error_t *	error
	)

Retrieves statistics about a file.

bio_ftell()

int64_t bio_ftell	(	bio_file_t	file,
		bio_error_t *	error
	)

Retrieve the file offset.

This is similar to stdlib ftell.

bio_funwrap()

uintptr_t bio_funwrap

(

bio_file_t

file

)

Retrieve an OS handle from a bio_file_t.

This can be used to call platform-specific API such as ioctl or flock.

For Unix platforms, this is will return a file descriptor. A value of -1 is possible if the file was closed with bio_fclose.

For Windows, this will return a HANDLE. A value of INVALID_HANDLE_VALUE may be returned.

Remarks

It is important not to interfere with bio when manipulating the OS handle directly. Please refer to the implementation details for the given platform.

bio_fwrite()

size_t bio_fwrite	(	bio_file_t	file,
		const void *	buf,
		size_t	size,
		bio_error_t *	error
	)

Write to a file.

This is similar to stdlib fwrite.

Remarks

Short write is possible.

See also

bio_fwrite_exactly

bio_fwrite_exactly()

static size_t bio_fwrite_exactly ( bio_file_t  file, const void *  buf, size_t  size, bio_error_t *  error  )

inlinestatic

Convenient function to write exactly a number of bytes to a file without short write.

Remarks

If an error was encountered while writing, it is still possible for this function to write fewer bytes. Always check error.

Variable Documentation

BIO_STDERR

bio_file_t BIO_STDERR

extern

Standard error.

BIO_STDIN

bio_file_t BIO_STDIN

extern

Standard input.

BIO_STDOUT

bio_file_t BIO_STDOUT

extern

Standard output.