|
CX Framework
Cross-platform C utility framework
|
Data Structures | |
| struct | VFSFile |
| struct | VFSDirCache |
| Directory cache accounting. See vfsSetCacheLimits(). More... | |
| 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 | VFS_CACHE_MAXDIRS 4096 |
| Default number of cached directory nodes above which eviction may run. | |
| #define | VFS_CACHE_TTL timeS(300) |
| Default time an unused cached directory survives, in microseconds. | |
| #define | vfsfileWriteString(self, str, byteswritten) File_writeString(File(self), str, byteswritten) |
| #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. | |
| typedef struct VFSDirCache | VFSDirCache |
| Directory cache accounting. See vfsSetCacheLimits(). | |
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 | vfsSetCacheLimits (VFS *vfs, uint32 maxdirs, int64 ttl) |
| void | vfsPruneCache (VFS *vfs) |
| 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 | vfsRead (VFSFile *file, void *buf, size_t sz, size_t *bytesread) |
| bool | vfsWrite (VFSFile *file, const 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) |
The VFS provides a unified, layered filesystem abstraction that can combine multiple data sources into a single namespace. This enables powerful features:
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:
Common Use Cases:
See vfsobj.h for vfsCreate(). See vfsprovider.h for implementing custom providers.
| #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.
| flags | Combination of VFS configuration flags (VFS_ReadOnly, VFS_CaseSensitive, etc.) |
Example:
| #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:
The VFS case sensitivity is configured to match the OS default:
This is a convenience function equivalent to creating an empty VFS and mounting the OS filesystem at the appropriate paths.
Example:
| #define vfsfileWriteString | ( | self, | |
| str, | |||
| byteswritten | |||
| ) | File_writeString(File(self), str, byteswritten) |
bool vfsfileWriteString(VFSFile* self, strref str, size_t* byteswritten);
Writes the contents of a string to the file
The string is written as-is, with no line ending added.
| str | String to write |
| byteswritten | Receives the number of bytes written, or NULL |
| #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.
| 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 |
Example:
| #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.
| 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 |
| #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.
| 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 |
Example:
VFS Object.
Opaque structure representing a virtual filesystem instance. Create with vfsCreate() and destroy with vfsDestroy().
| 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 the VFS file cache. Saves memory and always asks the providers, at the cost of slower repeated access. The directory tree itself is still remembered; use vfsSetCacheLimits() to bound that. |
| 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 |
| void vfsAbsolutePath | ( | VFS * | vfs, |
| string * | out, | ||
| strref | path | ||
| ) |
| 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.
| vfs | VFS instance |
| from | Source file path |
| to | Destination file path (will be created or overwritten) |
| 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'.
| vfs | VFS instance |
| path | Full directory path to create |
| bool vfsCreateDir | ( | VFS * | vfs, |
| strref | path | ||
| ) |
| void vfsCurDir | ( | VFS * | vfs, |
| string * | out | ||
| ) |
| bool vfsDelete | ( | VFS * | vfs, |
| strref | path | ||
| ) |
| 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.
| pvfs | Pointer to VFS handle to destroy |
|
inline |
|
inline |
| 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.).
|
inline |
Checks if a path exists and is a directory
| vfs | VFS instance |
| path | Path to check |
Definition at line 236 of file vfs.h.
References FS_Directory, and vfsStat().
|
inline |
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.
| vfs | VFS instance |
| path | File path to open (can be relative or absolute) |
| flags | Combination of FS_Read, FS_Write, FS_Create, etc. |
| void vfsPruneCache | ( | VFS * | vfs | ) |
Drops cached directories that have not been used recently
Runs the same pass the VFS runs on its own once the cache grows past the limit set with vfsSetCacheLimits(), regardless of the current size. Call this to release memory at a moment of your choosing.
| vfs | VFS instance |
|
inline |
Reads data from a VFS file
Reads up to sz bytes from the current position. See fsRead() for detailed semantics.
| file | Open VFS file handle |
| buf | Buffer to receive data |
| sz | Maximum bytes to read |
| bytesread | Receives actual bytes read |
Definition at line 409 of file vfs.h.
References fileRead.
| bool vfsRemoveDir | ( | VFS * | vfs, |
| strref | path | ||
| ) |
| 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.
| vfs | VFS instance |
| from | Current file path |
| to | New file path |
| void vfsSearchFinish | ( | FSSearchIter * | iter | ) |
Completes VFS directory search and releases resources
Must be called after vfsSearchInit() to clean up. Safe to call multiple times.
| iter | Search iterator to finish |
| 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.
| 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) |
| bool vfsSearchNext | ( | FSSearchIter * | iter | ) |
Advances to the next directory entry in VFS search
| iter | Active search iterator |
|
inline |
|
inline |
| void vfsSetCacheLimits | ( | VFS * | vfs, |
| uint32 | maxdirs, | ||
| int64 | ttl | ||
| ) |
Sets how large the directory cache may grow before unused entries are dropped
The VFS remembers every directory it has been asked about, including ones no provider has, so that repeated lookups do not go back to the providers. Nothing is dropped until the number of remembered directories passes maxdirs; past that, directories that no lookup has touched for ttl are discarded, along with the files remembered inside them.
Dropping a cached directory never loses data – the next lookup asks the providers again.
| vfs | VFS instance |
| maxdirs | Directory count above which eviction may run (0 for the default) |
| ttl | How long an untouched directory survives, in microseconds (0 for the default) |
Example:
| 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.
| vfs | VFS instance |
| cur | New current directory (can be relative or absolute) |
| 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.
| vfs | VFS instance |
| path | Path to modify |
| modified | New modification time (CX time format) |
| accessed | New access time (CX time format) |
| 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.
| vfs | VFS instance |
| path | Path to query (can be relative or absolute) |
| stat | Optional pointer to receive detailed metadata |
Referenced by vfsExist(), vfsIsDir(), and vfsIsFile().
|
inline |
| bool vfsUnmount | ( | VFS * | vfs, |
| strref | path | ||
| ) |
Unmounts all providers at a specific path
Removes all mounted providers from the specified mount point, and from every mount point below it – unmounting "/a" also unmounts "/a/b". Any files or directories provided by those providers become inaccessible.
| vfs | VFS instance |
| path | Mount path to unmount (must be absolute) |
|
inline |
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.
| file | Open VFS file handle |
| buf | Data to write |
| sz | Number of bytes to write |
| byteswritten | Optional pointer to receive bytes written |
Definition at line 429 of file vfs.h.
References fileWrite.
|
inline |
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).
| file | Open VFS file handle |
| str | String to write |
| byteswritten | Optional pointer to receive bytes written |
Definition at line 449 of file vfs.h.
References fileWriteString.