Contains common file related functions. More...

#include "common.h"
#include <stdio.h>

Macros
#define	QSC_FILEUTILS_CHUNK_SIZE 4096ULL
	[size_t] The default file chunk size.

#define	QSC_FILEUTILS_MAX_EXTENSION 16ULL
	[size_t] The maximum file extension size.

#define	QSC_FILEUTILS_MAX_FILENAME QSC_SYSTEM_MAX_PATH
	[size_t] The maximum file name size.

#define	QSC_FILEUTILS_MAX_PATH QSC_SYSTEM_MAX_PATH
	[size_t] The maximum file path size.

Enumerations
enum	qsc_fileutils_access_rights { qsc_fileutils_access_exists = 0x00U , qsc_fileutils_access_read = 0x04U , qsc_fileutils_access_write = 0x02U , qsc_fileutils_access_execute = 0x06U }
	Enumerates the file access rights. More...

enum	qsc_fileutils_mode { qsc_fileutils_mode_none = 0x00U , qsc_fileutils_mode_read = 0x01U , qsc_fileutils_mode_read_update = 0x02U , qsc_fileutils_mode_write = 0x03U , qsc_fileutils_mode_write_update = 0x04U , qsc_fileutils_mode_append = 0x05U , qsc_fileutils_mode_append_update = 0x06U }
	Enumerates the file open modes. More...

Functions
QSC_EXPORT_API bool	qsc_fileutils_append_to_file (const char fpath, const char stream, size_t length)
	Append an array of characters to a file.

QSC_EXPORT_API size_t	qsc_fileutils_copy_file_to_object (const char fpath, void obj, size_t length)
	Copy a file to an object.

QSC_EXPORT_API size_t	qsc_fileutils_copy_file_to_stream (const char fpath, char stream, size_t length)
	Copy elements from a file to a byte array.

QSC_EXPORT_API bool	qsc_fileutils_copy_object_to_file (const char fpath, const void obj, size_t length)
	Copy an object to a file.

QSC_EXPORT_API bool	qsc_fileutils_copy_stream_to_file (const char fpath, const char stream, size_t length)
	Copy the contents of a stream to a file.

QSC_EXPORT_API bool	qsc_fileutils_create (const char *fpath)
	Create a new file.

QSC_EXPORT_API bool	qsc_fileutils_delete (const char *fpath)
	Delete a file.

QSC_EXPORT_API bool	qsc_fileutils_erase (const char *fpath)
	Erase a file's contents.

QSC_EXPORT_API bool	qsc_fileutils_file_copy (const char inpath, const char outpath)
	Copy a file to a new location.

QSC_EXPORT_API bool	qsc_fileutils_get_access (const char *fpath, qsc_fileutils_access_rights level)
	Test a user's access right to a file.

QSC_EXPORT_API size_t	qsc_fileutils_get_directory (char directory, size_t dirlen, const char fpath)
	Get the file directory.

QSC_EXPORT_API size_t	qsc_fileutils_get_extension (char extension, size_t extlen, const char fpath)
	Get the file extension.

QSC_EXPORT_API size_t	qsc_fileutils_get_name (char name, size_t namelen, const char fpath)
	Get the file name.

QSC_EXPORT_API int64_t	qsc_fileutils_get_line (char *line, size_t length, FILE *fp)
	Reads a line of text from a formatted file.

QSC_EXPORT_API size_t	qsc_fileutils_get_size (const char *fpath)
	Get the file size in bytes.

QSC_EXPORT_API bool	qsc_fileutils_get_working_directory (char *fpath)
	Get the working directory fpath.

QSC_EXPORT_API size_t	qsc_fileutils_list_files (char result, size_t reslen, const char directory)
	Get the filenames in a directory delineated with a newline.

QSC_EXPORT_API void	qsc_fileutils_close (FILE *fp)
	Close a file.

QSC_EXPORT_API bool	qsc_fileutils_exists (const char *fpath)
	Test to see if a file exists.

QSC_EXPORT_API FILE *	qsc_fileutils_open (const char *fpath, qsc_fileutils_mode mode, bool binary)
	Open a file and return the handle.

QSC_EXPORT_API size_t	qsc_fileutils_read (char output, size_t otplen, size_t position, FILE fp)
	Read data from a file into an output stream.

QSC_EXPORT_API size_t	qsc_fileutils_safe_read (const char fpath, size_t position, char output, size_t length)
	Read data from a binary file.

QSC_EXPORT_API size_t	qsc_fileutils_safe_write (const char fpath, size_t position, const char input, size_t length)
	Write data to a binary file.

QSC_EXPORT_API bool	qsc_fileutils_seekto (FILE *fp, size_t position)
	Set the file pointer position.

QSC_EXPORT_API int64_t	qsc_fileutils_read_line (const char fpath, char buffer, size_t buflen, size_t linenum)
	Read a line of text from a file.

QSC_EXPORT_API bool	qsc_fileutils_truncate_file (FILE *fp, size_t length)
	Truncate a file to a specified byte size.

QSC_EXPORT_API bool	qsc_fileutils_valid_path (const char *fpath)
	Checks if the fpath is valid.

QSC_EXPORT_API size_t	qsc_fileutils_write (const char input, size_t inplen, size_t position, FILE fp)
	Write data to a file.

QSC_EXPORT_API bool	qsc_fileutils_write_line (const char fpath, const char input, size_t inplen)
	Append a line of text to the end of a file.

QSC_EXPORT_API void	qsc_fileutils_zeroise (const char *fpath)
	Truncate a file to zero bytes.

Detailed Description

Contains common file related functions.

Provides a suite of file utility functions for reading, writing, copying, and managing files and directories. This includes operations such as appending to files, copying files to objects or streams, checking file existence and access rights, retrieving file size, and listing files in a directory.

// Example: Reading a file into memory
uint8_t* data = qsc_file_read("example.txt", &filesize);
if (data != NULL) {
    // Process the file data as needed.
    qsc_file_free(data);
}

Reference Links:

Enumeration Type Documentation

◆ qsc_fileutils_access_rights

enum qsc_fileutils_access_rights

Enumerates the file access rights.

Enumerator
qsc_fileutils_access_exists	No access right specified.
qsc_fileutils_access_read	The read access right.
qsc_fileutils_access_write	The write access right.
qsc_fileutils_access_execute	The execute access right.

◆ qsc_fileutils_mode

enum qsc_fileutils_mode

Enumerates the file open modes.

Enumerator
qsc_fileutils_mode_none	No mode was specified.
qsc_fileutils_mode_read	Open file for input operations.
qsc_fileutils_mode_read_update	Open file for update (input and output).
qsc_fileutils_mode_write	Create an empty file for output operations.
qsc_fileutils_mode_write_update	Create an empty file and open it for update.
qsc_fileutils_mode_append	Open file for output at the end of the file.
qsc_fileutils_mode_append_update	Open file for update in append mode.

Function Documentation

◆ qsc_fileutils_append_to_file()

QSC_EXPORT_API bool qsc_fileutils_append_to_file	(	const char *	fpath,
		const char *	stream,
		size_t	length )

Append an array of characters to a file.

Writes new data to the end of a binary file.

Parameters

fpath	[const char*] The full fpath to the file.
stream	[const char*] The array to write to the file.
length	[size_t] The stream size.

Returns: [bool] Returns true if the operation succeeded.

◆ qsc_fileutils_close()

QSC_EXPORT_API void qsc_fileutils_close ( FILE * fp )

Close a file.

Parameters

fp	[FILE*] The file pointer.

◆ qsc_fileutils_copy_file_to_object()

QSC_EXPORT_API size_t qsc_fileutils_copy_file_to_object	(	const char *	fpath,
		void *	obj,
		size_t	length )

Copy a file to an object.

Parameters

fpath	[const char*] The full fpath to the file.
obj	[void*] The object to write to.
length	[size_t] The size of the object.

Returns: [size_t] Returns the number of characters written to the object.

◆ qsc_fileutils_copy_file_to_stream()

QSC_EXPORT_API size_t qsc_fileutils_copy_file_to_stream	(	const char *	fpath,
		char *	stream,
		size_t	length )

Copy elements from a file to a byte array.

Parameters

fpath	[const char*] The full fpath to the stream.
stream	[char*] The stream receiving the file.
length	[size_t] The number of bytes to write to the stream.

Returns: [size_t] Returns the number of characters written to the stream.

◆ qsc_fileutils_copy_object_to_file()

QSC_EXPORT_API bool qsc_fileutils_copy_object_to_file	(	const char *	fpath,
		const void *	obj,
		size_t	length )

Copy an object to a file.

Parameters

fpath	[const char*] The full fpath to the file.
obj	[const void*] The object to write to the file.
length	[size_t] The size of the object.

Returns: [bool] Returns true if the operation succeeded.

◆ qsc_fileutils_copy_stream_to_file()

QSC_EXPORT_API bool qsc_fileutils_copy_stream_to_file	(	const char *	fpath,
		const char *	stream,
		size_t	length )

Copy the contents of a stream to a file.

Parameters

fpath	[const char*] The full fpath to the file.
stream	[const char*] The array to write to the file.
length	[size_t] The length of the array.

Returns: [bool] Returns true if the operation succeeded.

◆ qsc_fileutils_create()

QSC_EXPORT_API bool qsc_fileutils_create ( const char * fpath )

Create a new file.

Parameters

fpath [const char*] The full fpath to the file to be created.

Returns: [bool] Returns true for success.

◆ qsc_fileutils_delete()

QSC_EXPORT_API bool qsc_fileutils_delete ( const char * fpath )

Delete a file.

Parameters

fpath [const char*] The full fpath to the file to be deleted.

Returns: [bool] Returns true for success.

◆ qsc_fileutils_erase()

QSC_EXPORT_API bool qsc_fileutils_erase ( const char * fpath )

Erase a file's contents.

Parameters

fpath [const char*] The full fpath to the file.

Returns: [bool] Returns true for success.

◆ qsc_fileutils_exists()

QSC_EXPORT_API bool qsc_fileutils_exists ( const char * fpath )

Test to see if a file exists.

Parameters

fpath [const char*] The fully qualified fpath to the file.

Returns: [bool] Returns true if the file exists.

◆ qsc_fileutils_file_copy()

QSC_EXPORT_API bool qsc_fileutils_file_copy	(	const char *	inpath,
		const char *	outpath )

Copy a file to a new location.

Parameters

inpath	[const char*] The full fpath to the input file.
outpath	[const char*] The full fpath to the output file.

Returns: [bool] Returns true if the file was copied.

◆ qsc_fileutils_get_access()

QSC_EXPORT_API bool qsc_fileutils_get_access	(	const char *	fpath,
		qsc_fileutils_access_rights	level )

Test a user's access right to a file.

Parameters

fpath	[const char*] The fully qualified fpath to the file.
level	[qsc_fileutils_access_rights] The access level to check.

Returns: [bool] Returns true if the specified access level is present.

◆ qsc_fileutils_get_directory()

QSC_EXPORT_API size_t qsc_fileutils_get_directory	(	char *	directory,
		size_t	dirlen,
		const char *	fpath )

Get the file directory.

Parameters

directory	[char*] The output directory buffer.
dirlen	[size_t] The length of the directory buffer.
fpath	[const char*] The full fpath to the file.

Returns: [size_t] Returns the length of the directory string.

◆ qsc_fileutils_get_extension()

QSC_EXPORT_API size_t qsc_fileutils_get_extension	(	char *	extension,
		size_t	extlen,
		const char *	fpath )

Get the file extension.

Parameters

extension	[char*] The output extension buffer.
extlen	[size_t] The length of the extension buffer.
fpath	[const char*] The full fpath to the file.

Returns: [size_t] Returns the length of the file extension.

◆ qsc_fileutils_get_line()

QSC_EXPORT_API int64_t qsc_fileutils_get_line	(	char **	line,
		size_t *	length,
		FILE *	fp )

Reads a line of text from a formatted file.

Warning: The line buffer must be freed after the last call.

Parameters

line	[char**] Pointer to the line buffer (dynamically allocated).
length	[size_t*] Pointer to the buffer size.
fp	[FILE*] The file stream handle.

Returns: [int64_t] Returns the number of characters read.

◆ qsc_fileutils_get_name()

QSC_EXPORT_API size_t qsc_fileutils_get_name	(	char *	name,
		size_t	namelen,
		const char *	fpath )

Get the file name.

Parameters

name	[char*] The output file name buffer.
namelen	[size_t] The length of the name buffer.
fpath	[const char*] The full fpath to the file.

Returns: [size_t] Returns the length of the file name.

◆ qsc_fileutils_get_size()

QSC_EXPORT_API size_t qsc_fileutils_get_size ( const char * fpath )

Get the file size in bytes.

Parameters

fpath [const char*] The full fpath to the file.

Returns: [size_t] Returns the size of the file in bytes.

◆ qsc_fileutils_get_working_directory()

QSC_EXPORT_API bool qsc_fileutils_get_working_directory ( char * fpath )

Get the working directory fpath.

Parameters

fpath [char*] The output buffer for the current working directory.

Returns: [bool] Returns true if the working directory was successfully retrieved.

◆ qsc_fileutils_list_files()

QSC_EXPORT_API size_t qsc_fileutils_list_files	(	char *	result,
		size_t	reslen,
		const char *	directory )

Get the filenames in a directory delineated with a newline.

Parameters

result	[char*] The output result string.
reslen	[size_t] The length of the output string.
directory	[const char*] The starting directory.

Returns: [size_t] Returns the length of the output string.

◆ qsc_fileutils_open()

QSC_EXPORT_API FILE * qsc_fileutils_open	(	const char *	fpath,
		qsc_fileutils_mode	mode,
		bool	binary )

Open a file and return the handle.

Parameters

fpath	[const char*] The fully qualified file fpath.
mode	[qsc_fileutils_mode] The file access mode.
binary	[bool] Open the file in binary mode (true) or ANSI mode (false).

Returns: [FILE*] Returns the file handle, or NULL on failure.

◆ qsc_fileutils_read()

QSC_EXPORT_API size_t qsc_fileutils_read	(	char *	output,
		size_t	otplen,
		size_t	position,
		FILE *	fp )

Read data from a file into an output stream.

Parameters

output	[char*] The output buffer.
otplen	[size_t] The size of the output buffer.
position	[size_t] The starting position within the file.
fp	[FILE*] The file pointer.

Returns: [size_t] Returns the number of bytes read.

◆ qsc_fileutils_read_line()

QSC_EXPORT_API int64_t qsc_fileutils_read_line	(	const char *	fpath,
		char *	buffer,
		size_t	buflen,
		size_t	linenum )

Read a line of text from a file.

Parameters

fpath	[const char*] The full fpath to the file.
buffer	[char*] The string buffer.
buflen	[size_t] The size of the string buffer.
linenum	[size_t] The line number to read.

Returns: [int64_t] Returns the length of the line or -1 at EOF.

◆ qsc_fileutils_safe_read()

QSC_EXPORT_API size_t qsc_fileutils_safe_read	(	const char *	fpath,
		size_t	position,
		char *	output,
		size_t	length )

Read data from a binary file.

Parameters

fpath	[const char*] The file fpath.
position	[size_t] The position to start reading from.
output	[char*] The output character stream.
length	[size_t] The number of bytes to read.

Returns: [size_t] Returns the number of characters read.

◆ qsc_fileutils_safe_write()

QSC_EXPORT_API size_t qsc_fileutils_safe_write	(	const char *	fpath,
		size_t	position,
		const char *	input,
		size_t	length )

Write data to a binary file.

Parameters

fpath	[const char*] The file fpath.
position	[size_t] The position to start writing to.
input	[const char*] The input character string.
length	[size_t] The number of bytes to write.

Returns: [size_t] Returns the number of characters written.

◆ qsc_fileutils_seekto()

QSC_EXPORT_API bool qsc_fileutils_seekto	(	FILE *	fp,
		size_t	position )

Set the file pointer position.

Parameters

fp	[FILE*] The file pointer.
position	[size_t] The position within the file.

Returns: [bool] Returns true if the pointer has been moved.

◆ qsc_fileutils_truncate_file()

QSC_EXPORT_API bool qsc_fileutils_truncate_file	(	FILE *	fp,
		size_t	length )

Truncate a file to a specified byte size.

Parameters

fp	[FILE*] The file pointer.
length	[size_t] The new file size.

Returns: [bool] Returns true if the file was successfully truncated.

◆ qsc_fileutils_valid_path()

QSC_EXPORT_API bool qsc_fileutils_valid_path ( const char * fpath )

Checks if the fpath is valid.

Parameters

fpath [const char*] The full fpath to the file.

Returns: [bool] Returns true if the fpath is formed properly.

◆ qsc_fileutils_write()

QSC_EXPORT_API size_t qsc_fileutils_write	(	const char *	input,
		size_t	inplen,
		size_t	position,
		FILE *	fp )

Write data to a file.

Parameters

input	[const char*] The input buffer.
inplen	[size_t] The size of the input buffer.
position	[size_t] The starting position within the file.
fp	[FILE*] The file pointer.

Returns: [size_t] Returns the number of bytes written.

◆ qsc_fileutils_write_line()

QSC_EXPORT_API bool qsc_fileutils_write_line	(	const char *	fpath,
		const char *	input,
		size_t	inplen )

Append a line of text to the end of a file.

Parameters

fpath	[const char*] The file fpath.
input	[const char*] The input buffer.
inplen	[size_t] The size of the input buffer.

Returns: [bool] Returns true if the operation succeeded.

◆ qsc_fileutils_zeroise()

QSC_EXPORT_API void qsc_fileutils_zeroise ( const char * fpath )

Truncate a file to zero bytes.

Parameters

fpath [const char*] The file fpath.

Macros

Enumerations

Functions

Detailed Description

Reference Links:

Enumeration Type Documentation

◆ qsc_fileutils_access_rights

◆ qsc_fileutils_mode

Function Documentation

◆ qsc_fileutils_append_to_file()

◆ qsc_fileutils_close()

◆ qsc_fileutils_copy_file_to_object()

◆ qsc_fileutils_copy_file_to_stream()

◆ qsc_fileutils_copy_object_to_file()

◆ qsc_fileutils_copy_stream_to_file()

◆ qsc_fileutils_create()

◆ qsc_fileutils_delete()

◆ qsc_fileutils_erase()

◆ qsc_fileutils_exists()

◆ qsc_fileutils_file_copy()

◆ qsc_fileutils_get_access()

◆ qsc_fileutils_get_directory()

◆ qsc_fileutils_get_extension()

◆ qsc_fileutils_get_line()

◆ qsc_fileutils_get_name()

◆ qsc_fileutils_get_size()

◆ qsc_fileutils_get_working_directory()

◆ qsc_fileutils_list_files()

◆ qsc_fileutils_open()

◆ qsc_fileutils_read()

◆ qsc_fileutils_read_line()

◆ qsc_fileutils_safe_read()

◆ qsc_fileutils_safe_write()

◆ qsc_fileutils_seekto()

◆ qsc_fileutils_truncate_file()

◆ qsc_fileutils_valid_path()

◆ qsc_fileutils_write()

◆ qsc_fileutils_write_line()

◆ qsc_fileutils_zeroise()