qfile.c File Reference

File handling APIs. More...

Go to the source code of this file.

Macros
#define	MAX_EXTENSION_LENGTH   (8)

Functions
bool	qfile_lock (int fd)
	Lock file.
bool	qfile_unlock (int fd)
	Unlock file which is locked by qfile_lock().
bool	qfile_exist (const char *filepath)
	Check file existence.
void *	qfile_load (const char *filepath, size_t *nbytes)
	Load a file into memory.
void *	qfile_read (FILE *fp, size_t *nbytes)
	Read data from a file stream.
ssize_t	qfile_save (const char *filepath, const void *buf, size_t size, bool append)
	Save data into file.
bool	qfile_mkdir (const char *dirpath, mode_t mode, bool recursive)
	Attempts to create a directory recursively.
bool	qfile_check_path (const char *path)
	Check path string contains invalid characters.
char *	qfile_get_name (const char *filepath)
	Get the file name from a path.
char *	qfile_get_dir (const char *filepath)
	Get the directory part of a path.
char *	qfile_get_ext (const char *filepath)
	Get the file extension from a path.
off_t	qfile_get_size (const char *filepath)
	Get file size.
char *	qfile_correct_path (char *path)
	Correct path string.
char *	qfile_abspath (char *buf, size_t bufsize, const char *path)
	Make full absolute system path string.

Detailed Description

File handling APIs.

Definition in file qfile.c.

Function Documentation

qfile_lock()

bool qfile_lock

(

int

fd

)

Lock file.

Parameters

fd	file descriptor

Returns

true on success, otherwise false.

// for file descriptor
int fd = open(...);
if(qfile_lock(fd) == true) {
  (...atomic file access...)
  qfile_unlock(fd);
}
 
// for FILE stream object
FILE *fp = fopen(...);
int fd = fileno(fp);
if(qfile_lock(fd) == true) {
  (...atomic file access...)
  qfile_unlock(fd);
}

Definition at line 74 of file qfile.c.

qfile_unlock()

bool qfile_unlock

(

int

fd

)

Unlock file which is locked by qfile_lock().

Parameters

fd	file descriptor

Returns

true on success, otherwise false.

Definition at line 98 of file qfile.c.

qfile_exist()

bool qfile_exist

(

const char *

filepath

)

Check file existence.

Parameters

filepath

file or directory path

Returns

true if exists, otherwise false.

Definition at line 122 of file qfile.c.

qfile_load()

void * qfile_load	(	const char *	filepath,
		size_t *	nbytes )

Load a file into memory.

Parameters

filepath	file path
nbytes	has two purposes. You can set it to limit how many bytes are read, and the actual number of loaded bytes is stored back through the same pointer. Set it to 0 or NULL to read the entire file.

Returns

allocated memory on success, or NULL on failure.

// loading text file
char *text = (char *)qfile_load("/tmp/text.txt", NULL);
 
// loading binary file
int binlen = 0;
char *bin = (char *)qfile_load("/tmp/binary.bin", &binlen);
 
// loading partial
int binlen = 10;
char *bin = (char *)qfile_load("/tmp/binary.bin", &binlen);

Note

This function allocates one extra byte after the file size and appends a NULL character at the end. For example, if the file size is 10 bytes, 11 bytes are allocated and the last byte is always NULL. This makes it safe to use the loaded data as a text string. The actual file size is returned through nbytes.

Definition at line 159 of file qfile.c.

qfile_read()

void * qfile_read	(	FILE *	fp,
		size_t *	nbytes )

Read data from a file stream.

Parameters

fp	FILE pointer
nbytes	has two purposes. You can set it to limit how many bytes are read, and the actual number of loaded bytes is stored back through the same pointer. Set it to 0 or NULL to read until the end of the stream.

Returns

allocated memory on success, or NULL on failure.

int binlen = 0;
char *bin = (char *)qfile_read(fp, &binlen);

Note

This function appends a NULL character at the end of the stream, but nbytes only counts the actual number of bytes read.

Definition at line 215 of file qfile.c.

qfile_save()

ssize_t qfile_save	(	const char *	filepath,
		const void *	buf,
		size_t	size,
		bool	append )

Save data into file.

Parameters

filepath	file path
buf	data
size	the number of bytes to save
append	false for new(if exists truncate), true for appending

Returns

the number of bytes written if successful, otherwise returns -1.

// save text
char *text = "hello";
qfile_save("/tmp/text.txt", (void*)text, strlen(text), false);
 
// save binary
int integer1 = 75;
qfile_save("/tmp/integer.bin", (void*)&integer1, sizeof(int), false);

Definition at line 284 of file qfile.c.

qfile_mkdir()

bool qfile_mkdir	(	const char *	dirpath,
		mode_t	mode,
		bool	recursive )

Attempts to create a directory recursively.

Parameters

dirpath	directory path
mode	permissions to use
recursive	whether or not to create parent directories automatically

Returns

true on success, otherwise false.

Definition at line 313 of file qfile.c.

qfile_check_path()

bool qfile_check_path

(

const char *

path

)

Check path string contains invalid characters.

Parameters

path	path string

Returns

true if ok, otherwise false.

Definition at line 338 of file qfile.c.

qfile_get_name()

char * qfile_get_name

(

const char *

filepath

)

Get the file name from a path.

Parameters

filepath

file or directory path

Returns

allocated file name string.

Definition at line 357 of file qfile.c.

qfile_get_dir()

char * qfile_get_dir

(

const char *

filepath

)

Get the directory part of a path.

Parameters

filepath

file or directory path

Returns

allocated directory string.

Definition at line 372 of file qfile.c.

qfile_get_ext()

char * qfile_get_ext

(

const char *

filepath

)

Get the file extension from a path.

Parameters

filepath

file or directory path

Returns

allocated extension string in lower case.

Definition at line 387 of file qfile.c.

qfile_get_size()

off_t qfile_get_size

(

const char *

filepath

)

Get file size.

Parameters

filepath

file or directory path

Returns

the file size if exists, otherwise returns -1.

Definition at line 411 of file qfile.c.

qfile_correct_path()

char * qfile_correct_path

(

char *

path

)

Correct path string.

Parameters

path	path string

Returns

path string pointer

Note

This function modifies path argument itself.

"/hello//my/../world" => "/hello/world"
"././././hello/./world" => "./hello/world"
"/../hello//world" => "/hello/world"
"/../hello//world/" => "/hello/world"

Definition at line 435 of file qfile.c.

qfile_abspath()

char * qfile_abspath	(	char *	buf,
		size_t	bufsize,
		const char *	path )

Make full absolute system path string.

Parameters

buf	buffer string pointer
bufsize	buffer size
path	path string

Returns

buffer pointer on success, or NULL on failure.

char buf[PATH_MAX];
chdir("/usr/local");
qfile_abspath(buf, sizeof(buf), ".");    // returns "/usr/local"
qfile_abspath(buf, sizeof(buf), "..");   // returns "/usr"
qfile_abspath(buf, sizeof(buf), "etc");  // returns "/usr/local/etc"
qfile_abspath(buf, sizeof(buf), "/etc"); // returns "/etc"
qfile_abspath(buf, sizeof(buf), "/etc/"); // returns "/etc/"

Definition at line 531 of file qfile.c.