Data Structures
struct	VFS
	VFS Object. More...

Macros
#define	vfsMountProvider(vfs, provider, path, ...) _vfsMountProvider(vfs, objInstBase(provider), path, opt_flags(__VA_ARGS__))

#define	vfsMountFS(vfs, path, fsroot, ...) _vfsMountFS(vfs, path, fsroot, opt_flags(__VA_ARGS__))

#define	vfsMountVFS(vfs, path, vfs2, vfs2root, ...) _vfsMountVFS(vfs, path, vfs2, vfs2root, opt_flags(__VA_ARGS__))

#define	vfsCreate(flags) VFS_create(flags)

#define	vfsCreateFromFS() VFS_createFromFS()

Typedefs
typedef struct VFS	VFS
	VFS Object.

typedef struct VFSFile	VFSFile

typedef struct VFS	VFS
	VFS Object.

Enumerations
enum	VFSFlags { VFS_ReadOnly = 0x00000001 , VFS_CaseSensitive = 0x00000002 , VFS_NoCache = 0x00000004 , VFS_NewFiles = 0x00000008 , VFS_AlwaysCOW = 0x00000010 , VFS_Opaque = 0x00000020 }

Functions
void	vfsDestroy (VFS **pvfs)

bool	vfsUnmount (VFS *vfs, strref path)

void	vfsCurDir (VFS vfs, string out)

bool	vfsSetCurDir (VFS *vfs, strref cur)

void	vfsAbsolutePath (VFS vfs, string out, strref path)

FSPathStat	vfsStat (VFS vfs, strref path, FSStat stat)

bool	vfsExist (VFS *vfs, strref path)

bool	vfsIsDir (VFS *vfs, strref path)

bool	vfsIsFile (VFS *vfs, strref path)

bool	vfsSetTimes (VFS *vfs, strref path, int64 modified, int64 accessed)

bool	vfsCreateDir (VFS *vfs, strref path)

bool	vfsCreateAll (VFS *vfs, strref path)

bool	vfsRemoveDir (VFS *vfs, strref path)

bool	vfsDelete (VFS *vfs, strref path)

bool	vfsCopy (VFS *vfs, strref from, strref to)

bool	vfsRename (VFS *vfs, strref from, strref to)

bool	vfsGetFSPath (string out, VFS vfs, strref path)

bool	vfsSearchInit (FSSearchIter iter, VFS vfs, strref path, strref pattern, int typefilter, bool stat)

bool	vfsSearchNext (FSSearchIter *iter)

void	vfsSearchFinish (FSSearchIter *iter)

bool	vfsSearchValid (FSSearchIter *iter)

VFSFile *	vfsOpen (VFS *vfs, strref path, flags_t flags)

bool	vfsClose (VFSFile *file)

bool	vfsRead (VFSFile file, void buf, size_t sz, size_t *bytesread)

bool	vfsWrite (VFSFile file, void buf, size_t sz, size_t *byteswritten)

bool	vfsWriteString (VFSFile file, strref str, size_t byteswritten)

int64	vfsTell (VFSFile *file)

int64	vfsSeek (VFSFile *file, int64 off, FSSeekType seektype)

bool	vfsFlush (VFSFile *file)

Detailed Description

The VFS provides a unified, layered filesystem abstraction that can combine multiple data sources into a single namespace. This enables powerful features:

Mount real OS filesystems at any path
Stack multiple read-only layers with a writable overlay (Copy-On-Write)
Create virtual filesystems backed by archives, memory, network, etc.
Provide sandboxed filesystem access to untrusted code

VFS Architecture: A VFS is built from one or more "providers" mounted at specific paths. When a file is accessed, the VFS searches mounted providers in order:

Most recently mounted provider is checked first
If not found (or read-only), check the next layer
For writes, COW semantics can copy from lower layers

Common Use Cases:

Game asset system: Mount game files with mod overlay
Application data: OS filesystem with bundled default files as fallback
Testing: Mock filesystem without touching real disk

See vfsobj.h for vfsCreate(). See vfsprovider.h for implementing custom providers.

Macro Definition Documentation

◆ vfsCreate

#define vfsCreate ( flags ) VFS_create(flags)

VFS* vfsCreate(uint32 flags);

Creates a new empty VFS instance with no mounted providers

The returned VFS contains no data sources. Use vfsMountFS() or vfsMountProvider() to attach filesystem providers before accessing files.

Parameters

flags Combination of VFS configuration flags (VFS_ReadOnly, VFS_CaseSensitive, etc.)

Returns: New VFS instance (never NULL, call objRelease() when done)

Example:

VFS *vfs = vfsCreate(0);
vfsMountFS(vfs, _S"/", _S"c:/data");
// ... use VFS ...
objRelease(&vfs);

Definition at line 77 of file vfsobj.h.

◆ vfsCreateFromFS

#define vfsCreateFromFS ( ) VFS_createFromFS()

VFS* vfsCreateFromFS();

Creates a VFS pre-configured with OS filesystem access

Returns a VFS that mirrors the underlying OS filesystem. The exact namespace configuration is platform-dependent:

Windows: Each drive letter (c:, d:, etc.) is a separate namespace
Unix: Single root namespace at /

The VFS case sensitivity is configured to match the OS default:

Windows: Case-insensitive
Unix: Case-sensitive

This is a convenience function equivalent to creating an empty VFS and mounting the OS filesystem at the appropriate paths.

Returns: VFS instance mirroring OS filesystem, or NULL on failure

Example:

VFS *vfs = vfsCreateFromFS();
if (vfs) {
    // VFS paths now map directly to OS filesystem
    VFSFile *f = vfsOpen(vfs, _S"c:/data/file.txt", FS_Read);
}

Definition at line 106 of file vfsobj.h.

◆ vfsMountFS

#define vfsMountFS	(	vfs,
		path,
		fsroot,
		...
	)	_vfsMountFS(vfs, path, fsroot, opt_flags(__VA_ARGS__))

bool vfsMountFS(VFS *vfs, strref path, strref fsroot, [flags_t flags]);

Mounts the OS filesystem into the VFS

Provides access to the real filesystem through the VFS. The fsroot directory on the OS filesystem is mounted at the specified path in the VFS namespace.

Parameters

vfs	VFS instance
path	VFS path where filesystem should be mounted (e.g., "/")
fsroot	OS filesystem path to mount (e.g., "c:/data")
...	(flags) Optional combination of VFS mount flags

Returns: true if successfully mounted, false on error

Example:

VFS *vfs = vfsCreate(0);
vfsMountFS(vfs, _S"/", _S"c:/gamedata", VFS_ReadOnly);
// Now VFS path "/textures/foo.png" maps to "c:/gamedata/textures/foo.png"

Definition at line 116 of file vfs.h.

◆ vfsMountProvider

#define vfsMountProvider	(	vfs,
		provider,
		path,
		...
	)	_vfsMountProvider(vfs, objInstBase(provider), path, opt_flags(__VA_ARGS__))

bool vfsMountProvider(VFS *vfs, provider, strref path, [flags_t flags]);

Mounts a custom VFS provider at the specified path

Attaches a VFS provider (implementing the VFSProvider interface) to the VFS at the given mount point. The provider handles all file operations for paths under this mount point.

Providers are searched in reverse mount order (most recent first). Multiple providers can be mounted at the same path to create layers.

Parameters

vfs	VFS instance
provider	Provider instance (must implement VFSProvider interface)
path	Absolute path where provider should be mounted
...	(flags) Optional combination of VFS mount flags

Returns: true if successfully mounted, false on error

See also: VFS_NewFiles, VFS_AlwaysCOW, VFS_Opaque flags

Definition at line 91 of file vfs.h.

◆ vfsMountVFS

#define vfsMountVFS	(	vfs,
		path,
		vfs2,
		vfs2root,
		...
	)	_vfsMountVFS(vfs, path, vfs2, vfs2root, opt_flags(__VA_ARGS__))

bool vfsMountVFS(VFS *vfs, strref path, VFS *vfs2, strref vfs2root, [flags_t flags]);

Mounts one VFS inside another (loopback mode)

Allows a VFS to be mounted as a provider within another VFS. This enables creating complex filesystem hierarchies and reusing VFS configurations.

Parameters

vfs	VFS to mount into
path	Mount point in vfs
vfs2	VFS to mount (source)
vfs2root	Root path within vfs2 to expose
...	(flags) Optional combination of VFS mount flags

Returns: true if successfully mounted, false on error

Example:

VFS *main = vfsCreate(0);
VFS *sub = vfsCreate(0);
vfsMountFS(sub, _S"/", _S"c:/assets");
vfsMountVFS(main, _S"/game", sub, _S"/");
// main VFS path "/game/x" now maps to sub VFS path "/x"

Definition at line 143 of file vfs.h.

Typedef Documentation

◆ VFS

typedef struct VFS VFS

VFS Object.

Opaque structure representing a virtual filesystem instance. Create with vfsCreate() and destroy with vfsDestroy().

Definition at line 40 of file vfs.h.

◆ VFSFile

typedef struct VFSFile VFSFile

Opaque structure representing an open file in a VFS. Similar to FSFile but works through the VFS layer.

Definition at line 44 of file vfs.h.

Enumeration Type Documentation

◆ VFSFlags

enum VFSFlags

VFS configuration and mount flags

These flags control VFS behavior and provider mounting options.

Enumerator
VFS_ReadOnly	Disallow write operations on this VFS/layer. Read-only providers can serve as base layers with writable overlays on top
VFS_CaseSensitive	Case-sensitive path matching. Efficiency of this flag (as well as of the default case-insensitive mode) may vary depending on if the underlying operating system provider is natively case sensitive or not.
VFS_NoCache	Disable VFS directory/file cache. Improves memory usage but slower repeated access
VFS_NewFiles	Direct new file creation to this layer. When multiple writable layers exist, this determines where new files are created
VFS_AlwaysCOW	Force Copy-On-Write for all writes. Writing to files from lower layers creates a copy in this layer, even if lower layer is writable. Useful for mod overlays.
VFS_Opaque	Hide all lower layers completely. Files in lower layers are invisible even if not shadowed by this layer

Definition at line 439 of file vfs.h.

Function Documentation

◆ vfsAbsolutePath()

void vfsAbsolutePath	(	VFS *	vfs,
		string *	out,
		strref	path
	)

Converts a relative path to absolute within the VFS

Resolves a path against the VFS's current directory to produce an absolute path. If the path is already absolute, it is normalized.

Parameters

vfs	VFS instance
out	Receives the absolute path
path	Path to convert (relative or absolute)

◆ vfsClose()

bool vfsClose ( VFSFile * file )

Closes a VFS file handle

Flushes buffers, closes the file, and releases resources. The file pointer becomes invalid after this call.

Parameters

file	VFS file handle to close

Returns: true if successful, false on error

◆ vfsCopy()

bool vfsCopy	(	VFS *	vfs,
		strref	from,
		strref	to
	)

Copies a file within the VFS

Copies data from one VFS path to another. Source and destination can be in different providers. This is implemented as read + write.

Parameters

vfs	VFS instance
from	Source file path
to	Destination file path (will be created or overwritten)

Returns: true if successful, false on error

◆ vfsCreateAll()

bool vfsCreateAll	(	VFS *	vfs,
		strref	path
	)

Creates a directory and all parent directories

Recursively creates all missing directories in the path. Similar to 'mkdir -p'.

Parameters

vfs	VFS instance
path	Full directory path to create

Returns: true if all directories created or exist, false on error

◆ vfsCreateDir()

bool vfsCreateDir	(	VFS *	vfs,
		strref	path
	)

Creates a directory in the VFS

Creates a single directory. Parent must exist. Uses the writable provider configured with VFS_NewFiles, or the first writable provider found.

Parameters

vfs	VFS instance
path	Directory path to create

Returns: true if created or already exists, false on error

◆ vfsCurDir()

void vfsCurDir	(	VFS *	vfs,
		string *	out
	)

Gets the current directory within the VFS

Each VFS maintains its own current directory for resolving relative paths. This is independent of the OS's current directory.

Parameters

vfs	VFS instance
out	Receives the current directory path

◆ vfsDelete()

bool vfsDelete	(	VFS *	vfs,
		strref	path
	)

Deletes a file from the VFS

Removes a file through the VFS layer. The file must be in a writable provider.

Parameters

vfs	VFS instance
path	File to delete

Returns: true if successful, false on error

◆ vfsDestroy()

void vfsDestroy ( VFS ** pvfs )

Destroys a VFS and releases all resources

Unmounts all providers, releases all references, and frees the VFS. All open VFSFile handles must be closed before destroying the VFS. Sets *pvfs to NULL after destruction. Safe to call with NULL.

To release an acquired VFS object handle without destroying it, use objRelease(&vfs) instead.

Parameters

pvfs	Pointer to VFS handle to destroy

◆ vfsExist()

bool vfsExist	(	VFS *	vfs,
		strref	path
	)

inline

Checks if a path exists in the VFS

Parameters

vfs	VFS instance
path	Path to check

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

Definition at line 193 of file vfs.h.

References FS_Nonexistent, and vfsStat().

◆ vfsFlush()

bool vfsFlush ( VFSFile * file )

Flushes buffered writes to storage

Forces pending writes through the VFS layer to the underlying provider.

Parameters

file	Open VFS file handle

Returns: true if successful, false on error

◆ vfsGetFSPath()

bool vfsGetFSPath	(	string *	out,
		VFS *	vfs,
		strref	path
	)

Retrieves the real OS filesystem path (VFSFS provider only)

If the specified VFS path is backed by a VFSFS provider (OS filesystem), this returns the actual underlying OS path. This is useful for passing paths to external tools or system APIs that don't understand VFS.

This only works for paths backed by VFSFS. Returns false for other provider types (memory, archive, etc.).

Parameters

out	Receives the OS filesystem path
vfs	VFS instance
path	VFS path to resolve

Returns: true if path is backed by VFSFS and OS path retrieved, false if path uses a different provider type

◆ vfsIsDir()

bool vfsIsDir	(	VFS *	vfs,
		strref	path
	)

inline

Checks if a path exists and is a directory

Parameters

vfs	VFS instance
path	Path to check

Returns: true if path exists and is a directory, false otherwise

Definition at line 203 of file vfs.h.

References FS_Directory, and vfsStat().

◆ vfsIsFile()

bool vfsIsFile	(	VFS *	vfs,
		strref	path
	)

inline

Checks if a path exists and is a file

Parameters

vfs	VFS instance
path	Path to check

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

Definition at line 213 of file vfs.h.

References FS_File, and vfsStat().

◆ vfsOpen()

VFSFile * vfsOpen	(	VFS *	vfs,
		strref	path,
		flags_t	flags
	)

Opens a file through the VFS

Opens a file for I/O using the VFS layer. File operations are routed through the appropriate mounted provider. For writes, the VFS may implement Copy-On-Write if configured with VFS_AlwaysCOW.

Parameters

vfs	VFS instance
path	File path to open (can be relative or absolute)
flags	Combination of FS_Read, FS_Write, FS_Create, etc.

Returns: VFSFile handle on success, NULL on failure

See also: FSOpenFlags in file.h

◆ vfsRead()

bool vfsRead	(	VFSFile *	file,
		void *	buf,
		size_t	sz,
		size_t *	bytesread
	)

Reads data from a VFS file

Reads up to sz bytes from the current position. See fsRead() for detailed semantics.

Parameters

file	Open VFS file handle
buf	Buffer to receive data
sz	Maximum bytes to read
bytesread	Receives actual bytes read

Returns: true on success (even if 0 bytes at EOF), false on I/O error

◆ vfsRemoveDir()

bool vfsRemoveDir	(	VFS *	vfs,
		strref	path
	)

Removes an empty directory from the VFS

Deletes a directory that contains no files or subdirectories.

Parameters

vfs	VFS instance
path	Directory to remove

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

◆ vfsRename()

bool vfsRename	(	VFS *	vfs,
		strref	from,
		strref	to
	)

Renames or moves a file within the VFS

Moves a file from one path to another. If source and destination are in the same provider, this may be a fast rename. Otherwise, it falls back to copy + delete.

Parameters

vfs	VFS instance
from	Current file path
to	New file path

Returns: true if successful, false on error

◆ vfsSearchFinish()

void vfsSearchFinish ( FSSearchIter * iter )

Completes VFS directory search and releases resources

Must be called after vfsSearchInit() to clean up. Safe to call multiple times.

Parameters

iter	Search iterator to finish

◆ vfsSearchInit()

bool vfsSearchInit	(	FSSearchIter *	iter,
		VFS *	vfs,
		strref	path,
		strref	pattern,
		int	typefilter,
		bool	stat
	)

Begins directory iteration through the VFS

Searches the specified directory in the VFS, merging results from all mounted providers. Files in higher-priority (more recent) mounts shadow files with the same name in lower layers.

Use vfsSearchNext() in a loop to retrieve entries. Always call vfsSearchFinish() when done, even if breaking early.

Parameters

iter	Iterator structure to initialize
vfs	VFS instance
path	Directory to search
pattern	Optional wildcard pattern (NULL for all entries)
typefilter	FS_File, FS_Directory, or 0 for both
stat	If true, populate stat field for each entry (slower)

Returns: true if directory opened and first entry found, false otherwise

◆ vfsSearchNext()

bool vfsSearchNext ( FSSearchIter * iter )

Advances to the next directory entry in VFS search

Parameters

iter	Active search iterator

Returns: true if another entry found, false if no more entries

◆ vfsSearchValid()

bool vfsSearchValid ( FSSearchIter * iter )

inline

Checks if a VFS search iterator is valid

Parameters

iter	Search iterator to check

Returns: true if iterator has a valid current entry, false otherwise

Definition at line 347 of file vfs.h.

◆ vfsSeek()

int64 vfsSeek	(	VFSFile *	file,
		int64	off,
		FSSeekType	seektype
	)

Changes position in a VFS file

Seeks to a new position for subsequent I/O. See fsSeek() for details.

Parameters

file	Open VFS file handle
off	Offset in bytes
seektype	FS_Set, FS_Cur, or FS_End

Returns: New file position, -1 on error

◆ vfsSetCurDir()

bool vfsSetCurDir	(	VFS *	vfs,
		strref	cur
	)

Sets the current directory within the VFS

Changes the VFS's current directory. Relative paths in subsequent operations will be resolved against this directory.

Parameters

vfs	VFS instance
cur	New current directory (can be relative or absolute)

Returns: true if successful, false if directory doesn't exist

◆ vfsSetTimes()

bool vfsSetTimes	(	VFS *	vfs,
		strref	path,
		int64	modified,
		int64	accessed
	)

Sets modification and access times on a VFS object

Updates timestamps through the VFS layer. The path must be in a writable provider.

Parameters

vfs	VFS instance
path	Path to modify
modified	New modification time (CX time format)
accessed	New access time (CX time format)

Returns: true if successful, false on error

◆ vfsStat()

FSPathStat vfsStat	(	VFS *	vfs,
		strref	path,
		FSStat *	stat
	)

Gets information about a filesystem object in the VFS

Queries the VFS for information about a path. Searches mounted providers to find the object and retrieve its metadata.

Parameters

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

Returns: FS_Nonexistent if not found, FS_Directory or FS_File otherwise

Referenced by vfsExist(), vfsIsDir(), and vfsIsFile().

◆ vfsTell()

int64 vfsTell ( VFSFile * file )

Gets current position in a VFS file

Parameters

file	Open VFS file handle

Returns: Current byte offset from start of file, -1 on error

◆ vfsUnmount()

bool vfsUnmount	(	VFS *	vfs,
		strref	path
	)

Unmounts all providers at a specific path

Removes all mounted providers from the specified mount point. Any files or directories provided by those providers become inaccessible.

Parameters

vfs	VFS instance
path	Mount path to unmount (must be absolute)

Returns: true if successfully unmounted, false on error

◆ vfsWrite()

bool vfsWrite	(	VFSFile *	file,
		void *	buf,
		size_t	sz,
		size_t *	byteswritten
	)

Writes data to a VFS file

Writes sz bytes to the file. May trigger Copy-On-Write if the file is from a read-only layer and COW is configured.

Parameters

file	Open VFS file handle
buf	Data to write
sz	Number of bytes to write
byteswritten	Optional pointer to receive bytes written

Returns: true on success, false on I/O error

◆ vfsWriteString()

bool vfsWriteString	(	VFSFile *	file,
		strref	str,
		size_t *	byteswritten
	)

Writes a string to a VFS file

Convenience function to write string contents to a file. The string is written as-is (no line endings added).

Parameters

file	Open VFS file handle
str	String to write
byteswritten	Optional pointer to receive bytes written

Returns: true on success, false on I/O error

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ vfsCreate

◆ vfsCreateFromFS

◆ vfsMountFS

◆ vfsMountProvider

◆ vfsMountVFS

Typedef Documentation

◆ VFS

◆ VFSFile

Enumeration Type Documentation

◆ VFSFlags

Function Documentation

◆ vfsAbsolutePath()

◆ vfsClose()

◆ vfsCopy()

◆ vfsCreateAll()

◆ vfsCreateDir()

◆ vfsCurDir()

◆ vfsDelete()

◆ vfsDestroy()

◆ vfsExist()

◆ vfsFlush()

◆ vfsGetFSPath()

◆ vfsIsDir()

◆ vfsIsFile()

◆ vfsOpen()

◆ vfsRead()

◆ vfsRemoveDir()

◆ vfsRename()

◆ vfsSearchFinish()

◆ vfsSearchInit()

◆ vfsSearchNext()

◆ vfsSearchValid()

◆ vfsSeek()

◆ vfsSetCurDir()

◆ vfsSetTimes()

◆ vfsStat()

◆ vfsTell()

◆ vfsUnmount()

◆ vfsWrite()

◆ vfsWriteString()