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.
- Parameters:
directory – The path to the directory.
- Returns:
TRUE if the directory exists, FALSE if not.
-
int file_exists(const char *path)¶
Test if a file exists.
Remark
This function may return FALSE if the file exists, but with insufficient permissions to access it.
- Parameters:
path – The pathname of the file.
- Returns:
TRUE if the file exists or FALSE if it does not.
-
long get_fsize(const char *name)¶
Get the size of a file in bytes.
- Parameters:
name – The pathname of the file.
- Returns:
The number of bytes in 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.
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.
- Returns:
A list of file pathnames. Directories will end with a ‘/’ character.
File Functions¶
These functions read and write file contents.
-
int append_file(const char *name, const char *data)¶
Append text to a file.
- Parameters:
name – The pathname of the file.
data – The text to append.
- Returns:
TRUE if the function succeeds. If there is an error the function will return FALSE and errno will reflect the error.
-
char *read_file(MEM_SCOPE mem, const char *name)¶
Read all text from a file.
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.
- Returns:
The text within the file, or NULL if an error occurred. Errors are reported in errno.
-
int write_file(const char *name, const char *data)¶
Write text to a file.
Remark
Any previous file content will be overwritten.
- Parameters:
name – The pathname of the file.
data – The text to write.
- Returns:
TRUE if the function succeeds. If there is an error the function will return FALSE and errno will reflect the error.
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.
- Parameters:
mem – A memory scope to own the result.
pathname – The file pathname.
- Returns:
The path component, excluding the trailing ‘/’ character.
-
char *fchext(MEM_SCOPE mem, const char *pathname, const char *ext)¶
Create a new file name swapping the extension with a new extension.
- Parameters:
mem – A memory scope to own the result.
pathname – The file pathname.
ext – The new extension.
- Returns:
The new file name with the new extension.
-
char *fext(const char *pathname)¶
Extract the file name extension from a path name.
- Parameters:
pathname – The file pathname.
- Returns:
The file name extension, IE the part following a ‘.’ character, excluding the ‘.’ character.
-
char *fname(const char *pathname)¶
Extract the file name with extension from a path name.
- Parameters:
pathname – The file pathname.
- Returns:
The file name with the path element removed.
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.
- Parameters:
file – The pathname of the file.
fp – The stream to redirect, commonly stdout or stderr.
- Returns:
The file descriptor of the redirected stream, needed to restore later.
-
int redir_input(const char *file)¶
Redirect a file to stdin.
- Parameters:
file – The pathname of the file.
- Returns:
The file descriptor of stdin, needed to restore later.
-
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.
