Native Filesystem

Data Structures
struct	FSStat
struct	FSSearchIter

Typedefs
typedef enum FSPathStatEnum	FSPathStat
typedef struct FSStat	FSStat
typedef struct FSSearch	FSSearch
typedef struct FSSearchIter	FSSearchIter

Enumerations
enum	FSPathStatEnum { FS_Nonexistent , FS_Directory , FS_File }

Functions
void	pathFromPlatform (string *out, strref platformpath)
void	pathToPlatform (string *out, strref path)
void	fsCurDir (string *out)
bool	fsSetCurDir (strref cur)
bool	pathMakeAbsolute (string *out, strref path)
void	fsExe (string *out)
void	fsExeDir (string *out)
FSPathStat	fsStat (strref path, FSStat *stat)
bool	fsExist (strref path)
bool	fsIsDir (strref path)
bool	fsIsFile (strref path)
bool	fsSetTimes (strref path, int64 modified, int64 accessed)
bool	fsCreateDir (strref path)
bool	fsCreateAll (strref path)
bool	fsRemoveDir (strref path)
bool	fsDelete (strref path)
bool	fsRename (strref from, strref to)
bool	fsSearchInit (FSSearchIter *iter, strref path, strref pattern, bool stat)
bool	fsSearchNext (FSSearchIter *iter)
void	fsSearchFinish (FSSearchIter *iter)
bool	fsSearchValid (FSSearchIter *iter)

Detailed Description

This module provides direct access to the operating system's filesystem using platform-native paths. For platform-independent path manipulation, see path.h. For a virtual filesystem abstraction, see vfs.h.

All paths are UTF-8 encoded.

Typedef Documentation

FSPathStat

typedef enum FSPathStatEnum FSPathStat

Path type enumeration

Returned by fsStat to indicate what kind of filesystem object exists at a given path (if any).

FSSearch

typedef struct FSSearch FSSearch

Opaque structure for iterating through directory contents. Use fsSearchInit/fsSearchNext/fsSearchFinish to enumerate files and subdirectories. Always call fsSearchFinish when done, even if the iteration ends early.

Definition at line 229 of file fs.h.

FSSearchIter

typedef struct FSSearchIter FSSearchIter

Directory search result

Contains information about one entry found during directory iteration. The 'name' string is valid only until the next call to fsSearchNext or fsSearchFinish.

FSStat

typedef struct FSStat FSStat

Filesystem object metadata

Contains timestamps and size information for a file or directory. All timestamps are in CX time format (microseconds since epoch).

Enumeration Type Documentation

FSPathStatEnum

enum FSPathStatEnum

Path type enumeration

Returned by fsStat to indicate what kind of filesystem object exists at a given path (if any).

Enumerator
FS_Nonexistent	Path does not exist.
FS_Directory	Path is a directory.
FS_File	Path is a regular file.

Definition at line 93 of file fs.h.

Function Documentation

fsCreateAll()

bool fsCreateAll

(

strref

path

)

Creates a directory and all necessary parent directories

Recursively creates all directories in the path that don't already exist. Similar to 'mkdir -p' on Unix. Safe to call on existing directories.

Parameters

path	Full path to create

Returns

true if all directories were created or already existed, false on error (no permission, path component is a file, etc.)

fsCreateDir()

bool fsCreateDir

(

strref

path

)

Creates a single directory

Creates a new directory at the specified path. The parent directory must already exist. To create multiple levels of directories at once, use fsCreateAll() instead.

Parameters

path	Path where the new directory should be created

Returns

true if successful or directory already exists, false on error (parent doesn't exist, no permission, path is a file, etc.)

fsCurDir()

void fsCurDir

(

string *

out

)

Gets the current working directory

Returns the OS's current working directory as a normalized CX path. This is a platform-specific concept and may vary per-thread on some systems.

Parameters

out	String to receive the current directory (prior contents destroyed)

fsDelete()

bool fsDelete

(

strref

path

)

Deletes a file

Removes a file from the filesystem. This cannot delete directories; use fsRemoveDir() for that.

Parameters

path	Path to the file to delete

Returns

true if successful, false on error (doesn't exist, is a directory, no permission, etc.)

fsExe()

void fsExe

(

string *

out

)

Gets the full path to the currently running executable

Returns the absolute path to the executable file that is currently running. Useful for locating resources relative to the executable.

Parameters

out	String to receive the executable path (prior contents destroyed)

fsExeDir()

void fsExeDir

(

string *

out

)

Gets the directory containing the currently running executable

Returns the parent directory of the current executable. Equivalent to calling pathParent on the result of fsExe().

Parameters

out	String to receive the executable directory (prior contents destroyed)

fsExist()

bool fsExist ( strref  path )

inline

Checks if a path exists in the filesystem

This is a convenience wrapper around fsStat that only checks existence without retrieving metadata or caring about the type.

Parameters

path	Path to check

Returns

true if the path exists (as any type), false otherwise

Definition at line 137 of file fs.h.

References FS_Nonexistent, and fsStat().

fsIsDir()

bool fsIsDir ( strref  path )

inline

Checks if a path exists and is a directory

Parameters

path	Path to check

Returns

true if the path exists and is a directory, false otherwise

Definition at line 146 of file fs.h.

References FS_Directory, and fsStat().

fsIsFile()

bool fsIsFile ( strref  path )

inline

Checks if a path exists and is a regular file

Parameters

path	Path to check

Returns

true if the path exists and is a regular file, false otherwise

Definition at line 155 of file fs.h.

References FS_File, and fsStat().

fsRemoveDir()

bool fsRemoveDir

(

strref

path

)

Removes an empty directory

Deletes a directory from the filesystem. The directory must be empty (contain no files or subdirectories). To delete files, use fsDelete().

Parameters

path	Path to the directory to remove

Returns

true if successful, false on error (doesn't exist, not empty, no permission, etc.)

fsRename()

bool fsRename	(	strref	from,
		strref	to
	)

Renames or moves a file or directory

Moves a file or directory from one path to another. Can be used to rename (if in the same directory) or move to a different directory. On most systems, this is atomic if both paths are on the same filesystem.

If 'to' already exists, behavior is platform-dependent:

• Windows: Fails if destination exists
• Unix: Overwrites destination if it's a file

Parameters

from	Current path of the file or directory
to	New path for the file or directory

Returns

true if successful, false on error (source doesn't exist, no permission, etc.)

fsSearchFinish()

void fsSearchFinish

(

FSSearchIter *

iter

)

Completes directory iteration and releases resources

Must be called after fsSearchInit to clean up the iterator, even if iteration was terminated early. Safe to call multiple times or on an uninitialized iterator.

Parameters

iter	Search iterator to clean up

fsSearchInit()

bool fsSearchInit	(	FSSearchIter *	iter,
		strref	path,
		strref	pattern,
		bool	stat
	)

Begins iteration over directory contents

Initializes a directory search iterator. After this call, use fsSearchNext in a loop to retrieve entries. Always call fsSearchFinish when done, even if breaking out of the loop early.

Parameters

iter	Iterator structure to initialize (will be cleared first)
path	Directory path to search
pattern	Optional wildcard pattern to filter results (NULL for all entries). Patterns support * and ? wildcards (e.g., "*.txt")
stat	If true, populate the stat field for each entry (slower)

Returns

true if the directory was opened successfully and the first entry was found, false if the directory doesn't exist, can't be read, or is empty

Example:

FSSearchIter iter;
if (fsSearchInit(&iter, _S"/some/dir", _S"*.txt", false)) {
    do {
        printf("Found: %s\n", strC(iter.name));
    } while (fsSearchNext(&iter));
}
fsSearchFinish(&iter);

fsSearchNext()

bool fsSearchNext

(

FSSearchIter *

iter

)

Advances to the next directory entry

Call this in a loop after fsSearchInit to iterate through all matching entries. The iter->name field is updated with each entry.

Parameters

iter	Active search iterator (from fsSearchInit)

Returns

true if another entry was found (iter->name is valid), false if no more entries (end of directory reached)

fsSearchValid()

bool fsSearchValid ( FSSearchIter *  iter )

inline

Checks if a search iterator is valid and has a current entry. This can be used to make fsSearch loops more convenient.

Parameters

iter	Search iterator to check

Returns

true if iter->name contains a valid entry, false otherwise

Example:

FSSearchIter iter;
fsSearchInit(&iter, _S"/some/dir", _S"*.txt", false);
while(fsSearchValid(&iter)) {
    printf("Found: %s\n", strC(iter.name));
    fsSearchNext(&iter);
}
fsSearchFinish(&iter);

Definition at line 306 of file fs.h.

fsSetCurDir()

bool fsSetCurDir

(

strref

cur

)

Sets the current working directory

Changes the OS's current working directory. This affects relative path resolution for all filesystem operations in the process.

Parameters

cur	Path to set as current directory (can be relative or absolute)

Returns

true if successful, false on error (directory doesn't exist, no permission, etc.)

fsSetTimes()

bool fsSetTimes	(	strref	path,
		int64	modified,
		int64	accessed
	)

Sets the modification and access times for a filesystem object

Updates the timestamps on a file or directory. The creation time cannot be modified. Timestamps are in CX time format (microseconds since epoch).

Parameters

path	Path to the file or directory to modify
modified	New modification time
accessed	New access time

Returns

true if successful, false on error (file doesn't exist, no permission, etc.)

fsStat()

FSPathStat fsStat	(	strref	path,
		FSStat *	stat
	)

Gets information about a filesystem object

Queries the filesystem for information about the object at the given path. This can determine if a path exists and what type of object it is, and optionally retrieve detailed metadata.

Parameters

path	Path to query (can be relative or absolute)
stat	Optional pointer to receive detailed metadata (can be NULL)

Returns

FS_Nonexistent if the path doesn't exist, FS_Directory if the path is a directory, FS_File if the path is a regular file

Example:

FSStat stat;
if (fsStat(_S"file.txt", &stat) == FS_File) {
    // file exists, stat.size contains the size
}

Referenced by fsExist(), fsIsDir(), and fsIsFile().

pathFromPlatform()

void pathFromPlatform	(	string *	out,
		strref	platformpath
	)

Converts a platform-specific path into a normalized CX path

Platform-specific path formats:

• Windows: C:\path\to\file or \\server\share\file
• Unix: /path/to/file

CX path format: namespace:/path/to/file

• Windows: Drive letters become namespaces (c:/path/to/file) UNC paths use unc namespace (unc:/server/share/file)
• Unix: No namespace, just /path/to/file

The output path is normalized (forward slashes, redundant elements removed).

Parameters

out	String to receive the converted path (prior contents destroyed)
platformpath	Platform-specific path to convert

pathMakeAbsolute()

bool pathMakeAbsolute	(	string *	out,
		strref	path
	)

Converts a relative path to an absolute path using the current directory

If the input path is already absolute, it is normalized and returned. If relative, it is resolved against the OS's current working directory.

Parameters

out	String to receive the absolute path (prior contents destroyed)
path	Relative or absolute path to convert

Returns

true if the path was made absolute (was relative), false if already absolute

pathToPlatform()

void pathToPlatform	(	string *	out,
		strref	path
	)

Converts a normalized CX path into a platform-specific path

This is the inverse of pathFromPlatform. The output uses the native path format required by OS-level file operations.

Parameters

out	String to receive the platform path (prior contents destroyed)
path	CX normalized path to convert