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

#include "defines.h"

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 "core/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...

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 "core/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_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_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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CLOSE_IF_FAILED

Typedef Documentation

◆ file_handle

◆ file_modes

Enumeration Type Documentation

◆ file_modes

Function Documentation

◆ filesystem_close()

◆ filesystem_exists()

◆ filesystem_open()

◆ filesystem_read()

◆ filesystem_read_all_bytes()

◆ filesystem_read_all_text()

◆ filesystem_read_line()

◆ filesystem_size()

◆ filesystem_write()

◆ filesystem_write_line()