filesystem.h File Reference

This file contains structures and functions for interacting with the file system. More...

#include "defines.h"

Go to the source code of this file.

Data Structures
struct	file_handle
	Holds a handle to a file. More...

Macros
#define	CLOSE_IF_FAILED(func, handle)
	If func returns false, closes the provided file handle and logs an error. Also returns false, so the calling function must return a boolean. Calling file must #include "logger.h". More...

Typedefs
typedef struct file_handle	file_handle
	Holds a handle to a file. More...
typedef enum file_modes	file_modes
	File open modes. Can be combined. More...

Enumerations
enum	file_modes { FILE_MODE_READ = 0x1 , FILE_MODE_WRITE = 0x2 }
	File open modes. Can be combined. More...

Functions
KAPI b8	filesystem_exists (const char *path)
	Checks if a file with the given path exists. More...
KAPI b8	filesystem_open (const char *path, file_modes mode, b8 binary, file_handle *out_handle)
	Attempt to open file located at path. More...
KAPI void	filesystem_close (file_handle *handle)
	Closes the provided handle to a file. More...
KAPI b8	filesystem_size (file_handle *handle, u64 *out_size)
	Attempts to read the size of the file to which handle is attached. More...
KAPI b8	filesystem_read_line (file_handle *handle, u64 max_length, char **line_buf, u64 *out_line_length)
	Reads up to a newline or EOF. More...
KAPI b8	filesystem_write_line (file_handle *handle, const char *text)
	Writes text to the provided file, appending a ' ' afterward. More...
KAPI b8	filesystem_read (file_handle *handle, u64 data_size, void *out_data, u64 *out_bytes_read)
	Reads up to data_size bytes of data into out_bytes_read. Allocates *out_data, which must be freed by the caller. More...
KAPI b8	filesystem_read_all_bytes (file_handle *handle, u8 *out_bytes, u64 *out_bytes_read)
	Reads all bytes of data into out_bytes. More...
KAPI b8	filesystem_read_all_text (file_handle *handle, char *out_text, u64 *out_bytes_read)
	Reads all characters of data into out_text. More...
KAPI b8	filesystem_write (file_handle *handle, u64 data_size, const void *data, u64 *out_bytes_written)
	Writes provided data to the file. More...
KAPI const char *	filesystem_read_entire_text_file (const char *filepath)
	Opens and reads all text content of the file at the provided path. No file handle required. File is closed automatically. Memory is dynamically allocated tagged as MEMORY_TAG_STRING) and should be freed by the caller. NOTE: This function also handles size disparity between text read in and files that contain CRLF. More...
KAPI const void *	filesystem_read_entire_binary_file (const char *filepath, u64 *out_size)
	Opens and reads all content of the file at the provided path. No file handle required. File is closed automatically. Memory is dynamically allocated (tagged as MEMORY_TAG_ARRAY) and should be freed by the caller. More...
KAPI b8	filesystem_write_entire_text_file (const char *filepath, const char *content)
KAPI b8	filesystem_write_entire_binary_file (const char *filepath, u64 size, const void *content)

Detailed Description

This file contains structures and functions for interacting with the file system.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version

1.0

Date

2022-01-10

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2022

Macro Definition Documentation

CLOSE_IF_FAILED

#define CLOSE_IF_FAILED	(		func,
			handle
	)

Value:

    if (!func) {                          \
        KERROR("File operation failed."); \
        filesystem_close(handle);         \
        return false;                     \
    }

If func returns false, closes the provided file handle and logs an error. Also returns false, so the calling function must return a boolean. Calling file must #include "logger.h".

Parameters

func	The function whose result is a boolean.
handle	The file handle to be closed on a false function result.

Returns

False if the provided function fails.

Typedef Documentation

file_handle

typedef struct file_handle file_handle

Holds a handle to a file.

file_modes

typedef enum file_modes file_modes

File open modes. Can be combined.

Enumeration Type Documentation

file_modes

enum file_modes

File open modes. Can be combined.

Enumerator
FILE_MODE_READ	Read mode
FILE_MODE_WRITE	Write mode

Function Documentation

filesystem_close()

KAPI void filesystem_close

(

file_handle *

handle

)

Closes the provided handle to a file.

Parameters

handle

A pointer to a file_handle structure which holds the handle to be closed.

filesystem_exists()

KAPI b8 filesystem_exists

(

const char *

path

)

Checks if a file with the given path exists.

Parameters

path	The path of the file to be checked.

Returns

True if exists; otherwise false.

filesystem_open()

KAPI b8 filesystem_open	(	const char *	path,
		file_modes	mode,
		b8	binary,
		file_handle *	out_handle
	)

Attempt to open file located at path.

Parameters

path	The path of the file to be opened.
mode	Mode flags for the file when opened (read/write). See file_modes enum in filesystem.h.
binary	Indicates if the file should be opened in binary mode.
out_handle	A pointer to a file_handle structure which holds the handle information.

Returns

True if opened successfully; otherwise false.

filesystem_read()

KAPI b8 filesystem_read	(	file_handle *	handle,
		u64	data_size,
		void *	out_data,
		u64 *	out_bytes_read
	)

Reads up to data_size bytes of data into out_bytes_read. Allocates *out_data, which must be freed by the caller.

Parameters

handle	A pointer to a file_handle structure.
data_size	The number of bytes to read.
out_data	A pointer to a block of memory to be populated by this method.
out_bytes_read	A pointer to a number which will be populated with the number of bytes actually read from the file.

Returns

True if successful; otherwise false.

filesystem_read_all_bytes()

KAPI b8 filesystem_read_all_bytes	(	file_handle *	handle,
		u8 *	out_bytes,
		u64 *	out_bytes_read
	)

Reads all bytes of data into out_bytes.

Parameters

handle	A pointer to a file_handle structure.
out_bytes	A byte array which will be populated by this method.
out_bytes_read	A pointer to a number which will be populated with the number of bytes actually read from the file.

Returns

True if successful; otherwise false.

filesystem_read_all_text()

KAPI b8 filesystem_read_all_text	(	file_handle *	handle,
		char *	out_text,
		u64 *	out_bytes_read
	)

Reads all characters of data into out_text.

Parameters

handle	A pointer to a file_handle structure.
out_text	A character array which will be populated by this method.
out_bytes_read	A pointer to a number which will be populated with the number of bytes actually read from the file.

Returns

True if successful; otherwise false.

filesystem_read_entire_binary_file()

KAPI const void* filesystem_read_entire_binary_file	(	const char *	filepath,
		u64 *	out_size
	)

Opens and reads all content of the file at the provided path. No file handle required. File is closed automatically. Memory is dynamically allocated (tagged as MEMORY_TAG_ARRAY) and should be freed by the caller.

Parameters

filepath	The path to the file to read.
A	pointer to hold the size of the file read in.

Returns

A binary block of data read from the file.

filesystem_read_entire_text_file()

KAPI const char* filesystem_read_entire_text_file

(

const char *

filepath

)

Opens and reads all text content of the file at the provided path. No file handle required. File is closed automatically. Memory is dynamically allocated tagged as MEMORY_TAG_STRING) and should be freed by the caller. NOTE: This function also handles size disparity between text read in and files that contain CRLF.

Parameters

filepath

The path to the file to read.

Returns

A string containing the file contents if successful; otherwise 0/null.

filesystem_read_line()

KAPI b8 filesystem_read_line	(	file_handle *	handle,
		u64	max_length,
		char **	line_buf,
		u64 *	out_line_length
	)

Reads up to a newline or EOF.

Parameters

handle	A pointer to a file_handle structure.
max_length	The maximum length to be read from the line.
line_buf	A pointer to a character array populated by this method. Must already be allocated.
out_line_length	A pointer to hold the line length read from the file.

Returns

True if successful; otherwise false.

filesystem_size()

KAPI b8 filesystem_size	(	file_handle *	handle,
		u64 *	out_size
	)

Attempts to read the size of the file to which handle is attached.

Parameters

handle	The file handle.
out_size	A pointer to hold the file size.

Returns

KAPI

filesystem_write()

KAPI b8 filesystem_write	(	file_handle *	handle,
		u64	data_size,
		const void *	data,
		u64 *	out_bytes_written
	)

Writes provided data to the file.

Parameters

handle	A pointer to a file_handle structure.
data_size	The size of the data in bytes.
data	The data to be written.
out_bytes_written	A pointer to a number which will be populated with the number of bytes actually written to the file.

Returns

True if successful; otherwise false.

filesystem_write_entire_binary_file()

KAPI b8 filesystem_write_entire_binary_file	(	const char *	filepath,
		u64	size,
		const void *	content
	)

filesystem_write_entire_text_file()

KAPI b8 filesystem_write_entire_text_file	(	const char *	filepath,
		const char *	content
	)

filesystem_write_line()

KAPI b8 filesystem_write_line	(	file_handle *	handle,
		const char *	text
	)

Writes text to the provided file, appending a '
' afterward.

Parameters

handle	A pointer to a file_handle structure.
text	The text to be written.

Returns

True if successful; otherwise false.