File System Utilities

Typedefs
typedef FILE	file_t
	File handle type.

Enumerations
enum	f_result_t {   FR_OK , FR_EOF , FR_DISK_ERR , FR_NO_FILE ,   FR_BUFFER_TOO_SMALL , FR_INVALID_PARAM }
	File system operation result codes. More...
enum	f_mode_t {   WRITE_OVERWRITE , WRITE_APPEND , READ , BWRITE_OVERWRITE ,   BWRITE_APPEND , BREAD }
	File access and operation modes. More...

Functions
bool	path_exists (const char *path)
	Check whether a path exists.
bool	dir_exists (const char *path)
	Check whether a directory exists.
bool	file_exists (const char *path)
	Check whether a file exists.
f_result_t	dir_list (const char *path)
	List contents of a directory.
f_result_t	file_open (file_t **const file, const char *path, f_mode_t mode)
	Open a file with the specified mode and initilize a file descriptor.
f_result_t	file_close (file_t **file)
	Close an open file from its descriptor.
f_result_t	file_remove (const char *path)
	Remove a file from the file system.
f_result_t	file_writeline (file_t *const file, const char *const restrict str)
	Write a null-terminated string to an open file.
f_result_t	file_write (file_t *const file, const void *const restrict data, size_t sz, size_t n)
	Write raw data to an open file.
f_result_t	file_readline (file_t *const file, char *const restrict buf, size_t n)
	Read a newline-terminated string from an open file.
f_result_t	file_read (file_t *const file, void *const restrict buf, size_t sz, size_t n)
	Read raw data from an open file.

Detailed Description

Copyright

Copyright (c) 2026 Adrien Chevrier. Under AGPL-3.0-or-later license.

A collection of useful POSIX wrappers for file / directory handling.

Typedef Documentation

file_t

typedef FILE file_t

File handle type.

Enumeration Type Documentation

f_mode_t

enum f_mode_t

File access and operation modes.

Enumerator
WRITE_OVERWRITE	Open text file for overwrite.
WRITE_APPEND	Open text file for append.
READ	Open text file for reading.
BWRITE_OVERWRITE	Open binary file for overwrite.
BWRITE_APPEND	Open binary file for append.
BREAD	Open binary file for reading.

f_result_t

enum f_result_t

File system operation result codes.

Enumerator
FR_OK	Operation successful.
FR_EOF	End of file reached.
FR_DISK_ERR	I/O or disk error.
FR_NO_FILE	File or directory not found.
FR_BUFFER_TOO_SMALL	Provided buffer too small.
FR_INVALID_PARAM	Invalid parameter.

Function Documentation

dir_exists()

bool dir_exists

(

const char *

path

)

Check whether a directory exists.

Parameters

[in]

path

Directory path.

Return values

true	The directory exists.
false	The directory does not exists.

dir_list()

f_result_t dir_list

(

const char *

path

)

List contents of a directory.

Parameters

[in]

path

Directory path.

Return values

FR_OK	On success.
FR_INVALID_PARAM	path is NULL.
FR_DISK_ERR	Failed to open the directory.

file_close()

f_result_t file_close

(

file_t **

file

)

Close an open file from its descriptor.

Parameters

[in,out]

file

Pointer to the file handle to close.

Return values

FR_OK	On success.
FR_INVALID_PARAM	file or *file is NULL.
FR_DISK_ERR	Failed to close the file.

file_exists()

bool file_exists

(

const char *

path

)

Check whether a file exists.

Parameters

[in]

path

File path.

Return values

true	The file exists.
false	The file does not exists.

file_open()

f_result_t file_open	(	file_t **const	file,
		const char *	path,
		f_mode_t	mode )

Open a file with the specified mode and initilize a file descriptor.

Note

The file will be created if it does not exist.

Parameters

[out]	file	Pointer to a file handle to be initialized.
[in]	path	File path.
[in]	mode	File open mode.

Return values

FR_OK	On success.
FR_INVALID_PARAM	Any parameter is NULL or mode is invalid.
FR_DISK_ERR	Failed to open the file.

file_read()

f_result_t file_read	(	file_t *const	file,
		void *const restrict	buf,
		size_t	sz,
		size_t	n )

Read raw data from an open file.

Parameters

[in]	file	File handle.
[out]	buf	Buffer to store read data.
[in]	sz	Size of each element in bytes.
[in]	n	Number of elements to read.

Return values

FR_OK	On success.
FR_INVALID_PARAM	Any parameter is NULL / equal to 0.
FR_DISK_ERR	Failed to read bytes.
FR_EOF	End of file reached.

file_readline()

f_result_t file_readline	(	file_t *const	file,
		char *const restrict	buf,
		size_t	n )

Read a newline-terminated string from an open file.

Note

The newline character is replaced by a null terminator.

The string is always null-terminated.

Parameters

[in]	file	File handle.
[out]	buf	Buffer to store the string.
[in]	n	Size of the buffer in bytes.

Return values

FR_OK	On success.
FR_INVALID_PARAM	Any parameter is NULL / equal to 0.
FR_DISK_ERR	Failed to read the string.
FR_EOF	End of file reached.
FR_BUFFER_TOO_SMALL	The string has been truncated due to the buffer size.

file_remove()

f_result_t file_remove

(

const char *

path

)

Remove a file from the file system.

Parameters

[in]

path

File path.

Return values

FR_OK	On success.
FR_INVALID_PARAM	path is NULL.
FR_NO_FILE	The file does not exists.
FR_DISK_ERR	Failed to remove the file.

file_write()

f_result_t file_write	(	file_t *const	file,
		const void *const restrict	data,
		size_t	sz,
		size_t	n )

Write raw data to an open file.

Parameters

[in]	file	File handle.
[in]	data	Pointer to data buffer.
[in]	sz	Size of each element in bytes.
[in]	n	Number of elements to write.

Return values

FR_OK	On success.
FR_INVALID_PARAM	Any parameter is NULL / equal to 0.
FR_DISK_ERR	Failed to write to the file.

file_writeline()

f_result_t file_writeline	(	file_t *const	file,
		const char *const restrict	str )

Write a null-terminated string to an open file.

Note

No newline character is added to the string.

Parameters

[in]	file	File handle.
[in]	str	String to write.

Return values

FR_OK	On success.
FR_INVALID_PARAM	Any parameter is NULL.
FR_DISK_ERR	Failed to write to the file.

path_exists()

bool path_exists

(

const char *

path

)

Check whether a path exists.

Parameters

[in]

path

File or directory path.

Return values

true	The path exists.
false	The path does not exists.