#include <libcork/os.h>
The functions in this section let you interact with files and directories in the local filesystem.
We provide several functions for constructing and handling paths into the local filesystem.
Represents a path in the local filesystem. The path can be relative or absolute. The paths don’t have to refer to existing files or directories.
Construct a new path object from the given path string, or as a copy of another path object.
Return the string content of a path. This is not normalized in any way. The result is guaranteed to be non-NULL, but may refer to an empty string. The return value belongs to the path object; you must not modify the contents of the string, nor should you try to free the underlying memory.
Convert a relative path into an absolute path. The first variant constructs a new path object to hold the result; the second variant overwritesthe contents of path.
If there is a problem obtaining the current working directory, these functions will return an error condition.
Concatenate two paths together. The join variants create a new path object containing the concatenated results. The append variants overwrite the contents of path with the concatenated results.
Extract the base name of path. This is the portion after the final trailing slash. The first variant constructs a new path object to hold the result; the second variant overwritesthe contents of path.
Note
These functions return a different result than the standard basename(3) function. We consider a trailing slash to be significant, whereas basename(3) does not:
basename("a/b/c/") == "c"
cork_path_basename("a/b/c/") == ""
Extract the directory name of path. This is the portion before the final trailing slash. The first variant constructs a new path object to hold the result; the second variant overwritesthe contents of path.
Note
These functions return a different result than the standard dirname(3) function. We consider a trailing slash to be significant, whereas dirname(3) does not:
dirname("a/b/c/") == "a/b"
cork_path_dirname("a/b/c/") == "a/b/c"
A list of paths in the local filesystem.
Create a new list of paths. The first variant creates a list that is initially empty. The second variant takes in a colon-separated list of paths as a single string, and adds each of those paths to the new list.
Free a path list.
Add path to list. The list takes control of the path instance; you must not try to free path yourself.
Return the number of paths in list.
Return the path in list at the given index. The list still owns the path instance that’s returned; you must not try to free it or modify its contents.
Return a string containing all of the paths in list separated by colons.
Search for a file in a list of paths. rel_path gives the path of the sought-after file, relative to each of the directories in list.
The first variant returns a cork_file instance for the first match. In no file can be found, it returns NULL and sets an error condition.
The second variant returns a cork_file_list instance containing all of the matches. In no file can be found, we return an empty list. (Unlike the first variant, this is not considered an error.)
Return a cork_path that refers to the current user’s home directory. If we can’t determine the current user’s home directory, we set an error condition and return NULL.
On POSIX systems, this directory is determined by the HOME environment variable.
Return a cork_path_list that includes all of the standard directories that can be used to store configuration files. This includes a user-specific directory that allows the user to override any global configuration files.
On POSIX systems, these directories are defined XDG Base Directory Specification.
Return a cork_path_list that includes all of the standard directories that can be used to store application data files. This includes a user-specific directory that allows the user to override any global data files.
On POSIX systems, these directories are defined XDG Base Directory Specification.
Return a cork_path that refers to a directory that can be used to store cache files created on behalf of the current user. This directory should only be used to store data that you can reproduce if needed.
On POSIX systems, these directories are defined XDG Base Directory Specification.
Represents a file on the local filesystem. The file in question does not necessarily have to exist; you can use cork_file instances to refer to files that you have not yet created, for instance.
Represents a Unix-style file permission set.
Create a new cork_file instance to represent the file with the given path. The _from_path variant uses an existing cork_path instance to specify the path. The new file instance will take control of the :c:type`cork_path` instance, so you should not try to free it yourself.
Return the path of a file. The cork_path instance belongs to the file; you must not try to modify or free the path instance.
Check whether a file exists in the filesystem, storing the result in exists. The function returns an error condition if we are unable to determine whether the file exists — for instance, because you do not have permission to look into one of the containing directories.
Return what kind of file the given cork_file instance refers to. The function returns an error condition if there is an error accessing the file — for instance, because you do not have permission to look into one of the containing directories.
If the function succeeds, it will fill in type with one of the following values:
Remove file from the filesystem. flags must be the bitwise OR (|) of the following flags. (Use 0 if you do not want any of the flags.)
If this flag is given, then it is not considered an error if file does not exist. If the flag is not given, then the function function returns an error if file doesn’t exist. (This mimics the standard rm -f command.)
If this flag is given, and file refers to a directory, then the function will automatically remove the directory and all of its contents. If the flag is not given, and file refers to a directory, then the directory must be empty for this function to succeed. If file does not refer to a directory, this flag has no effect. (This mimics the standard rmdir -r command.)
Certain functions can only be applied to a cork_file instance that refers to a directory.
Create a new directory in the filesystem, with permissions given by mode. flags must be the bitwise OR (|) of the following flags. (Use 0 if you do not want any of the flags.)
If this flag is given, then it is not considered an error if directory already exists. If the flag is not given, then the function function returns an error if directory exists. (This mimics part of the standard mkdir -p command.)
If this flag is given, then the function will ensure that all of the parent directories of directory exist, creating them if necessary. Each directory created will have permissions given by mode. (This mimics part of the standard mkdir -p command.)
Call iterator for each file or subdirectory contained in directory (not including the directory’s . and .. entries). This function does not recurse into any subdirectories; it only iterates through the immediate children of directory.
If your iteration function returns a non-zero result, we will abort the iteration and return that value. Otherwise, if each call to the iteration function returns 0, then we will return 0 as well.
iterator must be an instance of the following function type:
A list of files in the local filesystem.
Create a new list of files. The first variant creates a list that is initially empty. The second variant adds a new file instance for each of the paths in path_list.
Free a file list.
Add file to list. The list takes control of the file instance; you must not try to free file yourself.
Return the number of files in list.
Return the file in list at the given index. The list still owns the file instance that’s returned; you must not try to free it.
Walk through the contents of a directory. path can be an absolute or relative path. If it’s relative, it will be interpreted relative to the current directory. If path doesn’t exist, or there are any problems reading the contents of the directory, we’ll set an error condition and return -1.
To process the contents of the directory, you must provide a walker object, which contains several callback methods that we will call when files and subdirectories of path are encountered. Each method should return 0 on success. Unless otherwise noted, if we receive any other return result, we will abort the directory walk, and return that same result from the cork_walk_directory() call itself.
In all of the following methods, base_name will be the base name of the entry within its immediate subdirectory. rel_path will be the relative path of the entry within the path that you originally asked to walk through. full_path will the full path to the entry, including path itself.
Called when a regular file is encountered.
Called when a subdirectory of path of encountered. If you don’t want to recurse into this directory, return CORK_SKIP_DIRECTORY.
Called when a subdirectory has been fully processed.