Reference

File System Functions

These functions operate on files that reside on the file system.

int dir_exists(const char *directory)

Test if a directory exists.

Return
TRUE if the directory exists, FALSE if not.
Parameters
  • directory: The path to the directory.

int file_exists(const char *path)

Test if a file exists.

Return
TRUE if the file exists or FALSE if it does not.
Remark
This function may return FALSE if the file exists, but with insufficient permissions to access it.
Parameters
  • path: The pathname of the file.

long get_fsize(const char *name)

Get the size of a file in bytes.

Return
The number of bytes in the file.
Parameters
  • name: The pathname of the file.

void mkpath(const char *path)

Create all folders in the path, if they do not exist.

Parameters
  • path: The path to create.

void mkpath_to(const char *file)

Create all folders in the path to the given file, if they do not exist.

Remark
This is a convenience method to avoid extracting a path from a pathname purely to create the intervening folders.
Parameters
  • file: The pathname of the file.

LIST_STR list_dir(MEM_SCOPE mem, const char *path, int recurse)

Read the contents of a file system directory.

Return
A list of file pathnames. Directories will end with a ‘/’ character.
Remark
The path argument must end with a ‘/’ or the results may not be what you expect.
Parameters
  • mem: A memory scope to own the result.
  • path: The directory path to list.
  • recurse: Whether or not to recurse into sub directories.

File Functions

These functions read and write file contents.

int append_file(const char *name, const char *data)

Append text to a file.

Return
TRUE if the function succeeds. If there is an error the function will return FALSE and errno will reflect the error.
Parameters
  • name: The pathname of the file.
  • data: The text to append.

char *read_file(MEM_SCOPE mem, const char *name)

Read all text from a file.

Return
The text within the file, or NULL if an error occurred. Errors are reported in errno.
Remark
A non-existent file will return an empty string, rather than NULL.
Parameters
  • mem: A memory scope to contain the text.
  • name: The pathname of the file.

int write_file(const char *name, const char *data)

Write text to a file.

Return
TRUE if the function succeeds. If there is an error the function will return FALSE and errno will reflect the error.
Remark
Any previous file content will be overwritten.
Parameters
  • name: The pathname of the file.
  • data: The text to write.

File Name Functions

These functions operate on file and path names.

char *fpath(MEM_SCOPE mem, const char *pathname)

Extract the path component from a complete pathname to a file.

Return
The path component, excluding the trailing ‘/’ character.
Parameters
  • mem: A memory scope to own the result.
  • pathname: The file pathname.

char *fchext(MEM_SCOPE mem, const char *pathname, const char *ext)

Create a new file name swapping the extension with a new extension.

Return
The new file name with the new extension.
Parameters
  • mem: A memory scope to own the result.
  • pathname: The file pathname.
  • ext: The new extension.

char *fext(const char *pathname)

Extract the file name extension from a path name.

Return
The file name extension, IE the part following a ‘.’ character, excluding the ‘.’ character.
Parameters
  • pathname: The file pathname.

char *fname(const char *pathname)

Extract the file name with extension from a path name.

Return
The file name with the path element removed.
Parameters
  • pathname: The file pathname.

char *fbasename(MEM_SCOPE mem, const char *pathname)

Extract the file base name (without extension) from a path name.

Return
The file name with the path and extension elements removed.
Parameters
  • mem: A memory scope to own the result.
  • pathname: The file pathname.

Stream Functions

These functions allow redirect and restore of operating system streams stdin, stdout and stderr.

int redir_stream(const char *file, FILE *fp)

Redirect a stream to a file.

Return
The file descriptor of the redirected stream, needed to restore later.
Parameters
  • file: The pathname of the file.
  • fp: The stream to redirect, commonly stdout or stderr.

int redir_input(const char *file)

Redirect a file to stdin.

Return
The file descriptor of stdin, needed to restore later.
Parameters
  • file: The pathname of the file.

void restore_stream(int fd, FILE *fp)

Restore a previously redirected stream.

Parameters
  • fd: The file descriptor of the previously redirected stream.
  • fp: The stream to restore, commonly stdin, stdout or stderr.