X_FILESYSTEM_VERSION_MAJOR
#define X_FILESYSTEM_VERSION_MAJOR 1stdx_filesystem.h
homeSTDX - Filesystem Utilities Part of the STDX General Purpose C Library by marciovmf License: MIT https://github.com/marciovmf/stdx
Overview
Provides a cross-platform filesystem abstraction including:
- Directory and file operations (create, delete, copy, rename, enumerate)
- Filesystem monitoring via watch APIs
- Rich path manipulation utilities (normalize, join, basename, dirname, extension, relative paths)
- File metadata retrieval and modification (timestamps, permissions)
- Utilities for symbolic links and file type queries
- Temporary file and directory creation
- Functions accepts and preserves valid UTF-8 paths.
How to compile
To compile the implementation define X_IMPL_FILESYSTEM
in one source file before including this header.
To customize how this module allocates memory, define
X_FILESYSTEM_ALLOC / X_FILESYSTEM_CALLOC / X_FILESYSTEM_FREE before including.
Dependencies
stdx_string.h
X_FILESYSTEM_VERSION_MINOR
#define X_FILESYSTEM_VERSION_MINOR 0X_FILESYSTEM_VERSION_PATCH
#define X_FILESYSTEM_VERSION_PATCH 0X_FILESYSTEM_VERSION
#define X_FILESYSTEM_VERSION(X_FILESYSTEM_VERSION_MAJOR *10000+X_FILESYSTEM_VERSION_MINOR *100+X_FILESYSTEM_VERSION_PATCH)X_FS_PAHT_MAX_LENGTH
#define X_FS_PAHT_MAX_LENGTH 512X_FS_PATH_SEPARATOR
#define X_FS_PATH_SEPARATOR '\\'X_FS_ALT_PATH_SEPARATOR
#define X_FS_ALT_PATH_SEPARATOR '/'X_FS_PATH_SEPARATOR
#define X_FS_PATH_SEPARATOR '/'X_FS_ALT_PATH_SEPARATOR
#define X_FS_ALT_PATH_SEPARATOR '\\'XFSPath
typedef XSmallstr XFSPath;XFSDireEntry
typedef struct XFSDireEntry_t XFSDireEntry;XFSDireHandle
typedef struct XFSDireHandle_t XFSDireHandle;XFSWatch
typedef struct XFSWatch_t XFSWatch;XFSDireEntry_t
struct XFSDireEntry_t{
char name[X_FS_PAHT_MAX_LENGTH];
size_t size;
time_t last_modified;
int32_t is_directory;
};XFSWatchEventType
typedef enum{
x_fs_watch_CREATED,
x_fs_watch_DELETED,
x_fs_watch_MODIFIED,
x_fs_watch_RENAMED_FROM,
x_fs_watch_RENAMED_TO,
x_fs_watch_UNKNOWN
}XFSWatchEventType;XFSWatchEvent
typedef struct{
XFSWatchEventType action;
const char *filename;
}XFSWatchEvent;XFSTime
typedef struct XFSTime{
int year;
int month;
int day;
int hour;
int minute;
int second;
}XFSTime;x_fs_path
#define x_fs_path(out, ...) x_fs_path_(out, __VA_ARGS__, 0)x_fs_path_join
#define x_fs_path_join(path, ...) x_fs_path_join_(path, __VA_ARGS__, 0)x_fs_path_join_slice
#define x_fs_path_join_slice(path, ...) x_fs_path_join_slice_(path, __VA_ARGS__, 0)FSFileStat
typedef struct{
size_t size;
time_t creation_time;
time_t modification_time;
uint32_t permissions;
}FSFileStat;x_fs_find_first_file
Begin a directory enumeration and retrieve the first entry.
X_FILESYSTEM_API XFSDireHandle * x_fs_find_first_file(
const char *path,
XFSDireEntry *entry
);Parameters
const char *path- Directory path to search.
XFSDireEntry *entry- Output directory entry filled with the first result.
Returns
Handle used for subsequent enumeration, or NULL on failure.
x_fs_directory_create
Create a directory.
X_FILESYSTEM_API bool x_fs_directory_create(const char *path);Parameters
const char *path- Directory path to create.
Returns
True on success, false on failure.
x_fs_directory_create_recursive
Create a directory and any missing parent directories.
X_FILESYSTEM_API bool x_fs_directory_create_recursive(const char *path);Parameters
const char *path- Directory path to create.
Returns
True on success, false on failure.
x_fs_directory_delete
Delete an empty directory.
X_FILESYSTEM_API bool x_fs_directory_delete(const char *directory);Parameters
const char *directory- Directory path to delete.
Returns
True on success, false on failure.
x_fs_file_copy
Copy a file to a new path.
X_FILESYSTEM_API bool x_fs_file_copy(
const char *file,
const char *newFile
);Parameters
const char *file- Source file path.
const char *newFile- Destination file path.
Returns
True on success, false on failure.
x_fs_file_rename
Rename (move) a file to a new path.
X_FILESYSTEM_API bool x_fs_file_rename(
const char *file,
const char *newFile
);Parameters
const char *file- Source file path.
const char *newFile- Destination file path.
Returns
True on success, false on failure.
x_fs_find_next_file
Continue a directory enumeration and retrieve the next entry.
X_FILESYSTEM_API bool x_fs_find_next_file(
XFSDireHandle *dirHandle,
XFSDireEntry *entry
);Parameters
XFSDireHandle *dirHandle- Enumeration handle returned by x_fs_find_first_file().
XFSDireEntry *entry- Output directory entry filled with the next result.
Returns
True if an entry was written, false if no more entries or on failure.
x_fs_get_temp_folder
Get the system temporary folder path.
X_FILESYSTEM_API size_t x_fs_get_temp_folder(XFSPath *out);Parameters
XFSPath *out- Output path buffer to receive the temp folder.
Returns
Length of the written path (in bytes/chars, excluding terminator), or 0 on failure.
x_fs_cwd_get
Get the current working directory.
X_FILESYSTEM_API size_t x_fs_cwd_get(XFSPath *path);Parameters
XFSPath *path- Output path buffer to receive the current working directory.
Returns
Length of the written path (in bytes/chars, excluding terminator), or 0 on failure.
x_fs_cwd_set
Set the current working directory.
X_FILESYSTEM_API size_t x_fs_cwd_set(const char *path);Parameters
const char *path- New working directory path.
Returns
Non-zero on success, 0 on failure.
x_fs_cwd_set_from_executable_path
Set the current working directory to the executable's directory.
X_FILESYSTEM_API size_t x_fs_cwd_set_from_executable_path(void);Returns
Non-zero on success, 0 on failure.
x_fs_find_close
Close a directory enumeration handle.
X_FILESYSTEM_API void x_fs_find_close(XFSDireHandle *dirHandle);Parameters
XFSDireHandle *dirHandle- Enumeration handle to close.
Returns
Nothing.
x_fs_watch_open
Open a filesystem watcher for the given path.
X_FILESYSTEM_API XFSWatch * x_fs_watch_open(const char *path);Parameters
const char *path- Path to watch (directory or file, depending on platform support).
Returns
Watch handle, or NULL on failure.
x_fs_watch_close
Close a filesystem watcher.
X_FILESYSTEM_API void x_fs_watch_close(XFSWatch *fw);Parameters
XFSWatch *fw- Watch handle to close.
Returns
Nothing.
x_fs_watch_poll
Poll a filesystem watcher for pending events.
X_FILESYSTEM_API int32_t x_fs_watch_poll(
XFSWatch *fw,
XFSWatchEvent *out_events,
int32_t max_events
);Parameters
XFSWatch *fw- Watch handle.
XFSWatchEvent *out_events- Output array to receive events.
int32_t max_events- Maximum number of events to write to out_events.
Returns
Number of events written, or a negative value on error.
x_fs_path_normalize
Normalize a path in-place (e.g., separators, ".", ".." where possible).
X_FILESYSTEM_API XFSPath * x_fs_path_normalize(XFSPath *input);Parameters
XFSPath *input- Path to normalize.
Returns
Pointer to the normalized path (same as input).
x_fs_path_stem_cstr
Get the filename stem (basename without extension) from a path string.
X_FILESYSTEM_API XSlice x_fs_path_stem_cstr(const char *input);Parameters
const char *input- Path as a C string.
Returns
Slice pointing into input containing the stem.
x_fs_path_stem_as_slice
X_FILESYSTEM_API XSlice x_fs_path_stem_as_slice(const XFSPath *input);x_fs_path_stem
X_FILESYSTEM_API size_t x_fs_path_stem(
const XFSPath *input,
XFSPath *out
);x_fs_path_basename_cstr
Get the basename (final component) from a path string.
X_FILESYSTEM_API XSlice x_fs_path_basename_cstr(const char *input);Parameters
const char *input- Path as a C string.
Returns
Slice pointing into input containing the basename.
x_fs_path_basename_as_slice
X_FILESYSTEM_API XSlice x_fs_path_basename_as_slice(const XFSPath *input);x_fs_path_basename
X_FILESYSTEM_API size_t x_fs_path_basename(
const XFSPath *input,
XFSPath *out
);x_fs_path_dirname_cstr
Get the directory name (everything before the final component) from a path string.
X_FILESYSTEM_API XSlice x_fs_path_dirname_cstr(const char *input);Parameters
const char *input- Path as a C string.
Returns
Slice pointing into input containing the directory portion.
x_fs_path_dirname_as_slice
X_FILESYSTEM_API XSlice x_fs_path_dirname_as_slice(const XFSPath *input);x_fs_path_dirname
X_FILESYSTEM_API size_t x_fs_path_dirname(
const XFSPath *input,
XFSPath *out
);x_fs_path_
Build a path from one or more C string components (variadic), writing to out.
X_FILESYSTEM_API bool x_fs_path_(
XFSPath *out,
...
);Parameters
XFSPath *out- Output path to receive the resulting path.
Returns
True on success, false on failure.
x_fs_path_join_
X_FILESYSTEM_API size_t x_fs_path_join_(
XFSPath *path,
...
);x_fs_path_join_slice_
X_FILESYSTEM_API size_t x_fs_path_join_slice_(
XFSPath *path,
...
);x_fs_path_as_slice
X_FILESYSTEM_API XSlice x_fs_path_as_slice(const XFSPath *path);x_fs_path_exists
Check whether a path exists on disk.
X_FILESYSTEM_API bool x_fs_path_exists(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if it exists, false otherwise.
x_fs_path_exists_cstr
Check whether a C-string path exists on disk.
X_FILESYSTEM_API bool x_fs_path_exists_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if it exists, false otherwise.
x_fs_path_exists_quick
Check whether a path exists on disk using a faster, less thorough method.
X_FILESYSTEM_API bool x_fs_path_exists_quick(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if it exists, false otherwise.
x_fs_path_exists_quick_cstr
Check whether a C-string path exists on disk using a faster, less thorough method.
X_FILESYSTEM_API bool x_fs_path_exists_quick_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if it exists, false otherwise.
x_fs_path_is_absolute
Check whether a path is absolute.
X_FILESYSTEM_API bool x_fs_path_is_absolute(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if absolute, false otherwise.
x_fs_path_is_absolute_cstr
Check whether a C-string path is absolute.
X_FILESYSTEM_API bool x_fs_path_is_absolute_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if absolute, false otherwise.
x_fs_path_is_absolute_native
Check whether a path is absolute using native platform rules.
X_FILESYSTEM_API bool x_fs_path_is_absolute_native(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if absolute, false otherwise.
x_fs_path_is_absolute_native_cstr
Check whether a C-string path is absolute using native platform rules.
X_FILESYSTEM_API bool x_fs_path_is_absolute_native_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if absolute, false otherwise.
x_fs_path_is_directory
Check whether a path points to an existing directory.
X_FILESYSTEM_API bool x_fs_path_is_directory(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if it is a directory, false otherwise.
x_fs_path_is_directory_cstr
Check whether a C-string path points to an existing directory.
X_FILESYSTEM_API bool x_fs_path_is_directory_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if it is a directory, false otherwise.
x_fs_path_is_file
Check whether a path points to an existing file.
X_FILESYSTEM_API bool x_fs_path_is_file(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if it is a file, false otherwise.
x_fs_path_is_file_cstr
Check whether a C-string path points to an existing file.
X_FILESYSTEM_API bool x_fs_path_is_file_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if it is a file, false otherwise.
x_fs_path_is_relative
Check whether a path is relative.
X_FILESYSTEM_API bool x_fs_path_is_relative(const XFSPath *path);Parameters
const XFSPath *path- Path to check.
Returns
True if relative, false otherwise.
x_fs_path_is_relative_cstr
Check whether a C-string path is relative.
X_FILESYSTEM_API bool x_fs_path_is_relative_cstr(const char *path);Parameters
const char *path- Path to check.
Returns
True if relative, false otherwise.
x_fs_path_cstr
Get a NUL-terminated C string view of an XFSPath.
X_FILESYSTEM_API const char * x_fs_path_cstr(const XFSPath *p);Parameters
const XFSPath *p- Path object.
Returns
Pointer to the internal NUL-terminated string.
x_fs_path_append
Append a single component to a path.
X_FILESYSTEM_API size_t x_fs_path_append(
XFSPath *p,
const char *comp
);Parameters
XFSPath *p- Path to append to.
const char *comp- Component to append.
Returns
New length of the path after appending.
x_fs_path_change_extension
Replace or set the extension of a path.
X_FILESYSTEM_API size_t x_fs_path_change_extension(
XFSPath *path,
const char *new_ext
);Parameters
XFSPath *path- Path to modify.
const char *new_ext- New extension (with or without leading dot, depending on implementation).
Returns
New length of the path after the change.
x_fs_path_compare
Compare two paths, ignoring separator type.
X_FILESYSTEM_API size_t x_fs_path_compare(
const XFSPath *a,
const XFSPath *b
);Parameters
Returns
0 if equal, <0 if a < b, >0 if a > b.
x_fs_path_compare_cstr
Compare a path against a C string path, ignoring separator type.
X_FILESYSTEM_API int32_t x_fs_path_compare_cstr(
const XFSPath *a,
const char *cstr
);Parameters
const XFSPath *a- Path.
const char *cstr- C string path.
Returns
0 if equal, <0 if a < cstr, >0 if a > cstr.
x_fs_path_eq
Check whether a path equals a small string.
X_FILESYSTEM_API bool x_fs_path_eq(
const XFSPath *a,
const XSmallstr *b
);Parameters
Returns
True if equal, false otherwise.
x_fs_path_eq_cstr
Check whether a path equals a C string path.
X_FILESYSTEM_API bool x_fs_path_eq_cstr(
const XFSPath *a,
const char *b
);Parameters
const XFSPath *a- Path.
const char *b- C string path.
Returns
True if equal, false otherwise.
x_fs_path_extension_cstr
Get the extension from a path string.
X_FILESYSTEM_API XSlice x_fs_path_extension_cstr(const char *input);Parameters
const char *input- Path as a C string.
Returns
Slice pointing into input containing the extension (may be empty).
x_fs_path_extension_as_slice
X_FILESYSTEM_API XSlice x_fs_path_extension_as_slice(const XFSPath *input);x_fs_path_extension
X_FILESYSTEM_API size_t x_fs_path_extension(
const XFSPath *input,
XFSPath *out
);x_fs_path_from_slice
Convert a slice into an XFSPath.
X_FILESYSTEM_API size_t x_fs_path_from_slice(
XSlice sv,
XFSPath *out
);Parameters
Returns
Length written to out.
x_fs_path_relative_to_cstr
Compute a relative path from one C-string path to another.
X_FILESYSTEM_API size_t x_fs_path_relative_to_cstr(
const char *from_path,
const char *to_path,
XFSPath *out_path
);Parameters
const char *from_path- Base path.
const char *to_path- Target path.
XFSPath *out_path- Output path receiving the relative path.
Returns
Length of the written relative path, or 0 on failure.
x_fs_path_common_prefix
Compute the common prefix of two paths.
X_FILESYSTEM_API bool x_fs_path_common_prefix(
const char *from_path,
const char *to_path,
XFSPath *out_path
);Parameters
const char *from_path- First path.
const char *to_path- Second path.
XFSPath *out_path- Output path receiving the common prefix.
Returns
True if a common prefix was written (may be empty depending on implementation), false on failure.
x_fs_path_set
Set a path from a C string.
X_FILESYSTEM_API size_t x_fs_path_set(
XFSPath *p,
const char *cstr
);Parameters
XFSPath *p- Path to set.
const char *cstr- Source C string.
Returns
Length written to p.
x_fs_path_set_slice
Set a path from a stdx slice.
X_FILESYSTEM_API size_t x_fs_path_set_slice(
XFSPath *p,
XSlice slice
);Parameters
Returns
Length written to p.
x_fs_path_split
Split a path string into components.
X_FILESYSTEM_API bool x_fs_path_split(
const char *input,
XFSPath *out_components,
size_t max_components,
size_t *out_count
);Parameters
const char *input- Path as a C string.
XFSPath *out_components- Output array of components.
size_t max_components- Maximum number of components to write.
size_t *out_count- Output count of components written.
Returns
True on success, false on failure.
x_fs_path_from_executable
Get the executable path (or executable directory, depending on implementation).
X_FILESYSTEM_API size_t x_fs_path_from_executable(XFSPath *out);Parameters
XFSPath *out- Output path to receive the executable path.
Returns
Length written to out, or 0 on failure.
x_fs_file_stat
Retrieve metadata about a file or directory.
X_FILESYSTEM_API bool x_fs_file_stat(
const char *path,
FSFileStat *out_stat
);Parameters
const char *path- File or directory path.
FSFileStat *out_stat- Output struct receiving the metadata.
Returns
True on success, false on failure.
x_fs_file_modification_time
Retrieve the last modification time of a file or directory.
X_FILESYSTEM_API bool x_fs_file_modification_time(
const char *path,
time_t *out_time
);Parameters
const char *path- File or directory path.
time_t *out_time- Output time receiving the modification time.
Returns
True on success, false on failure.
x_fs_file_creation_time
Retrieve the creation time of a file or directory.
X_FILESYSTEM_API bool x_fs_file_creation_time(
const char *path,
time_t *out_time
);Parameters
const char *path- File or directory path.
time_t *out_time- Output time receiving the creation time.
Returns
True on success, false on failure.
x_fs_file_permissions
Retrieve permissions metadata for a file or directory.
X_FILESYSTEM_API bool x_fs_file_permissions(
const char *path,
uint32_t *out_permissions
);Parameters
const char *path- File or directory path.
uint32_t *out_permissions- Output value receiving the permissions (platform-dependent).
Returns
True on success, false on failure.
x_fs_file_set_permissions
Set permissions metadata for a file or directory.
X_FILESYSTEM_API bool x_fs_file_set_permissions(
const char *path,
uint32_t permissions
);Parameters
const char *path- File or directory path.
uint32_t permissions- Permissions value to set (platform-dependent).
Returns
True on success, false on failure.
x_fs_is_file
Check whether a path points to an existing regular file.
X_FILESYSTEM_API bool x_fs_is_file(const char *path);Parameters
const char *path- Path to check.
Returns
True if it is a file, false otherwise.
x_fs_is_directory
Check whether a path points to an existing directory.
X_FILESYSTEM_API bool x_fs_is_directory(const char *path);Parameters
const char *path- Path to check.
Returns
True if it is a directory, false otherwise.
x_fs_is_symlink
Check whether a path is a symbolic link.
X_FILESYSTEM_API bool x_fs_is_symlink(const char *path);Parameters
const char *path- Path to check.
Returns
True if it is a symlink, false otherwise.
x_fs_read_symlink
Read the target of a symbolic link.
X_FILESYSTEM_API bool x_fs_read_symlink(
const char *path,
XFSPath *out_path
);Parameters
const char *path- Symbolic link path.
XFSPath *out_path- Output path receiving the resolved link target.
Returns
True on success, false on failure.
x_fs_make_temp_file
Create a temporary file with the given prefix.
X_FILESYSTEM_API bool x_fs_make_temp_file(
const char *prefix,
XFSPath *out_path
);Parameters
const char *prefix- Prefix to use for the temporary file name.
XFSPath *out_path- Output path receiving the created temp file path.
Returns
True on success, false on failure.
x_fs_make_temp_directory
Create a temporary directory with the given prefix.
X_FILESYSTEM_API bool x_fs_make_temp_directory(
const char *prefix,
XFSPath *out_path
);Parameters
const char *prefix- Prefix to use for the temporary directory name.
XFSPath *out_path- Output path receiving the created temp directory path.
Returns
True on success, false on failure.
x_fs_time_from_epoch
Convert a time value from epoch to XFSTime.
X_FILESYSTEM_API XFSTime x_fs_time_from_epoch(time_t t);Parameters
time_t t- Time in seconds since Unix epoch.
Returns
XFSTime representation of the given epoch time.
x_fs_path_relative_to
Compute a relative path from one path to another.
X_FILESYSTEM_API size_t x_fs_path_relative_to(
const XFSPath *from_path,
const XFSPath *to_path,
XFSPath *out_path
);Parameters
Returns
Length of the resulting path on success, 0 on failure.
MAX_PATH
#define MAX_PATH PATH_MAXX_FS_MAX_PATH
#define X_FS_MAX_PATH MAX_PATHX_FILESYSTEM_ALLOC
Internal macro for allocating memory. To override how this header allocates memory, define this macro with a different implementation before including this header.
#define X_FILESYSTEM_ALLOC(sz) malloc(sz)Parameters
sz- The size of memory to alloc.
X_FILESYSTEM_CALLOC
Internal macro for allocating zeroed memory. To override how this header allocates zeroed memory, define this macro with a different implementation before including this header.
#define X_FILESYSTEM_CALLOC(n, sz) calloc((n), (sz))Parameters
sz- The size of memory to alloc.
X_FILESYSTEM_FREE
Internal macro for freeing memory. To override how this header frees memory, define this macro with a different implementation before including this header.
#define X_FILESYSTEM_FREE(p) free(p)Parameters
p- The address of memory region to free.
dirent
struct dirent *entry;stat
struct stat fileStat;x_fs_path_join_one_slice
X_FILESYSTEM_API int32_t x_fs_path_join_one_slice(
XFSPath *out,
const XSlice segment
);x_fs_path_join_one
X_FILESYSTEM_API int32_t x_fs_path_join_one(
XFSPath *out,
const char *segment
);x_fs_path_clone
X_FILESYSTEM_API void x_fs_path_clone(
XFSPath *out,
const XFSPath *path
);x_fs_path_init
X_FILESYSTEM_API void x_fs_path_init(XFSPath *p);