Cross-platform filesystem operations with UTF-8 path handling. More...

#include "vl_arena.h"

Include dependency graph for vl_filesys.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	vl_filesys_path
	Represents a filesystem path within the filesystem context. More...

struct	vl_filesys_stat
	File status information structure. More...

struct	vl_filesys
	Filesystem context structure. More...

Macros
#define	VL_FS_ITER_INVALID NULL

Enumerations
enum	vl_filesys_result { VL_FS_SUCCESS = 0 , VL_FS_ERROR_ACCESS_DENIED , VL_FS_ERROR_PATH_INVALID , VL_FS_ERROR_NOT_FOUND , VL_FS_ERROR_IO }
	Result codes for filesystem operations. More...

Functions
VL_API void	vlFSInit (vl_filesys *sys)
	Initializes a filesystem context.

VL_API void	vlFSFree (vl_filesys *sys)
	Frees resources associated with a filesystem context.

VL_API vl_filesys *	vlFSNew (void)
	Creates a new filesystem context.

VL_API void	vlFSDelete (vl_filesys *sys)
	Deletes a filesystem context created with vlFSNew.

VL_API vl_filesys_stat *	vlFSStatNew (vl_filesys *sys)
	Creates a new file stat object.

VL_API void	vlFSStatDelete (vl_filesys_stat *stat)
	Deletes a file stat object.

VL_API vl_filesys_result	vlFSStatPath (const vl_filesys_path path, vl_filesys_stat result)
	Gets file status information for a given path.

VL_API vl_filesys_result	vlFSStatIter (vl_filesys_iter iter, vl_filesys_stat *result)
	Gets file status information for the current iterator position.

VL_API vl_filesys_path *	vlFSPathNew (vl_filesys sys, const char path)
	Creates a new filesystem path object.

VL_API void	vlFSPathDelete (vl_filesys_path *path)
	Deletes a filesystem path object.

VL_API vl_filesys_path *	vlFSPathClone (const vl_filesys_path src, vl_filesys_path dest)
	Clones a filesystem path.

VL_API vl_bool_t	vlFSPathEquals (const vl_filesys_path pathA, const vl_filesys_path pathB)
	Compares two filesystem paths for equality.

VL_API void	vlFSPathSet (vl_filesys_path path, const char pathStr)
	Sets the path string for a filesystem path object.

VL_API const vl_transient *	vlFSPathString (const vl_filesys_path *path)
	Gets the string representation of a filesystem path.

VL_API void	vlFSPathJoin (const vl_filesys_path base, vl_filesys_path dest, const char *component)
	Joins a path component to a base path.

VL_API void	vlFSPathNormalize (vl_filesys_path *path)
	Normalizes a filesystem path by resolving relative components.

VL_API void	vlFSPathParent (const vl_filesys_path path, vl_filesys_path parentOut)
	Gets the parent directory of a filesystem path.

VL_API void	vlFSPathAbsolute (vl_filesys_path *path)
	Converts a relative path to an absolute path.

VL_API vl_bool_t	vlFSPathIsAbsolute (const vl_filesys_path *path)
	Checks if a filesystem path is absolute.

VL_API vl_filesys_result	vlFSPathMkDir (const vl_filesys_path *path)
	Creates a directory at the specified path.

VL_API vl_filesys_result	vlFSPathRemove (const vl_filesys_path *path)
	Removes a file or directory at the specified path.

VL_API vl_bool_t	vlFSPathExists (const vl_filesys_path *path)
	Checks if a file or directory exists at the specified path.

VL_API vl_filesys_iter	vlFSIterNew (vl_filesys *sys)
	Creates a new directory iterator.

VL_API void	vlFSIterDelete (vl_filesys_iter iter)
	Deletes a directory iterator.

VL_API vl_filesys_result	vlFSIterDir (vl_filesys_iter iter, const vl_filesys_path path)
	Initializes an iterator for a directory.

VL_API vl_filesys_result	vlFSIterDirRecursive (vl_filesys_iter iterPtr, const vl_filesys_path path)
	Initializes an iterator for recursive directory traversal.

VL_API vl_bool_t	vlFSIterNext (vl_filesys_iter *iter)
	Advances the iterator to the next entry.

Detailed Description

Cross-platform filesystem operations with UTF-8 path handling.

██ ██ ██ █████ ███████ █████ ██████ ███ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ███████ ███████ ███████ ██ ███ ██ ██ ██ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ███████ ██ ██ ███████ ██ ██ ██████ ██ ████ ██ ██ ====—: A Data Structure and Algorithms library for C11. :—====

This module provides a comprehensive filesystem abstraction layer that works consistently across Windows and POSIX systems. All filesystem operations enforce UTF-8 encoding for paths internally, ensuring proper handling of international characters and consistent behavior regardless of the underlying platform's native path encoding.

Key Features:

Cross-platform path operations with consistent separator handling
UTF-8 path enforcement for international character support
Memory-efficient design using arena and pool allocators
Directory iteration with recursive traversal support
File status information including timestamps and metadata
Path manipulation utilities (join, normalize, absolute/relative conversion)
Safe path component parsing (basename, extension, full name)

Path Handling: All paths are stored and processed as UTF-8 strings internally, with automatic conversion to the platform's native encoding (UTF-16 on Windows, UTF-8 on POSIX) when making system calls. This ensures consistent behavior and proper support for international filenames across all supported platforms. All paths are automatically normalized when assigned to avoid headaches between file separators across platforms. This opinionated choice aims to strike a comfortable balance between ease-of-use between platforms and the ability to get meaningful work done with the API.

Memory Management: The filesystem context uses arena allocation for string storage and pool allocation for object instances, providing efficient memory usage and automatic cleanup when the context is freed.

Thread Safety: Individual filesystem contexts are not thread-safe. Each thread should use its own filesystem context or external synchronization must be provided.

See also: vl_filesys for the main filesystem context structure; vl_filesys_path for path representation and manipulation; vl_filesys_stat for file status information; vl_filesys_iter for directory iteration

Data Structure Documentation

◆ vl_filesys_path

struct vl_filesys_path

Represents a filesystem path within the filesystem context.

Collaboration diagram for vl_filesys_path:

Data Fields
vl_pool_idx	pathIndex	Pointer to the filesystem context
vl_arena_ptr	pathStringPtr	Unique pool index for this path
struct vl_filesys_ *	sys

◆ vl_filesys_stat

struct vl_filesys_stat

File status information structure.

Contains detailed information about a file or directory, including metadata such as size, timestamps, and parsed path components.

Collaboration diagram for vl_filesys_stat:

Data Fields
vl_ularge_t	accessTime	File modification timestamp
vl_arena_ptr	baseName	Path to the file (will not have a path index)
vl_ularge_t	createTime	Size of the file in bytes
vl_arena_ptr	extension	Base name = "bar"
vl_filesys_path	filePath	File last access timestamp
vl_memsize_t	fileSize	True if the file is read-only
vl_arena_ptr	fullName	Extension = "txt" (or VL_ARENA_NULL if no extension)
vl_bool_t	isDirectory	Unique pool index for this stat object
vl_bool_t	isReadOnly	True if the file is a directory
vl_ularge_t	modifyTime	File creation timestamp
vl_pool_idx	statIndex	Pointer to the filesystem context
struct vl_filesys_ *	sys

◆ vl_filesys

struct vl_filesys

Filesystem context structure.

Manages memory allocation for filesystem operations using arena and pool allocators for efficient memory management.

Collaboration diagram for vl_filesys:

Data Fields
vl_pool	iterPool	Pool allocator for path instances
vl_arena	memory
vl_pool	pathPool	Pool allocator for stat instances
vl_pool	statPool	Arena allocator for string storage

Macro Definition Documentation

◆ VL_FS_ITER_INVALID

#define VL_FS_ITER_INVALID NULL

Enumeration Type Documentation

◆ vl_filesys_result

enum vl_filesys_result

Result codes for filesystem operations.

Enumerator
VL_FS_SUCCESS
VL_FS_ERROR_ACCESS_DENIED	Operation completed successfully
VL_FS_ERROR_PATH_INVALID	Access denied to the file or directory
VL_FS_ERROR_NOT_FOUND	The provided path is invalid
VL_FS_ERROR_IO	File or directory not found Generic I/O error

Function Documentation

◆ vlFSDelete()

VL_API void vlFSDelete ( vl_filesys * sys )

Deletes a filesystem context created with vlFSNew.

Parameters

sys	Pointer to the filesystem context to delete

Here is the call graph for this function:

◆ vlFSFree()

VL_API void vlFSFree ( vl_filesys * sys )

Frees resources associated with a filesystem context.

Parameters

sys	Pointer to the filesystem context to free

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSInit()

VL_API void vlFSInit ( vl_filesys * sys )

Initializes a filesystem context.

Parameters

sys	Pointer to the filesystem context to initialize

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSIterDelete()

VL_API void vlFSIterDelete ( vl_filesys_iter iter )

Deletes a directory iterator.

Parameters

iter	Iterator handle to delete

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSIterDir()

VL_API vl_filesys_result vlFSIterDir	(	vl_filesys_iter *	iter,
		const vl_filesys_path *	path
	)

Initializes an iterator for a directory.

Parameters

[in,out]	iter	Pointer to the iterator handle
	path	Pointer to the directory path to iterate

Returns: Result code indicating success or failure

Here is the call graph for this function:

◆ vlFSIterDirRecursive()

VL_API vl_filesys_result vlFSIterDirRecursive	(	vl_filesys_iter *	iterPtr,
		const vl_filesys_path *	path
	)

Initializes an iterator for recursive directory traversal.

Parameters

[in,out]	iterPtr	Pointer to the iterator handle
	path	Pointer to the directory path to iterate recursively

Returns: Result code indicating success or failure

Here is the call graph for this function:

◆ vlFSIterNew()

VL_API vl_filesys_iter vlFSIterNew ( vl_filesys * sys )

Creates a new directory iterator.

Parameters

sys	Pointer to the filesystem context

Returns: Handle to the new iterator or VL_FS_ITER_INVALID on failure

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSIterNext()

VL_API vl_bool_t vlFSIterNext ( vl_filesys_iter * iter )

Advances the iterator to the next entry.

Parameters

[in,out] iter Pointer to the iterator handle

Returns: True if there is a next entry, false if iteration is complete

Here is the call graph for this function:

◆ vlFSNew()

VL_API vl_filesys * vlFSNew ( void )

Creates a new filesystem context.

Returns: Pointer to the newly created filesystem context

Here is the call graph for this function:

◆ vlFSPathAbsolute()

VL_API void vlFSPathAbsolute ( vl_filesys_path * path )

Converts a relative path to an absolute path.

Parameters

path	Pointer to the path object to make absolute

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathClone()

VL_API vl_filesys_path * vlFSPathClone	(	const vl_filesys_path *	src,
		vl_filesys_path *	dest
	)

Clones a filesystem path.

Parameters

	src	Source path to clone
[out]	dest	Destination path object

Returns: Pointer to the cloned path object

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathDelete()

VL_API void vlFSPathDelete ( vl_filesys_path * path )

Deletes a filesystem path object.

Parameters

path	Pointer to the path object to delete

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathEquals()

VL_API vl_bool_t vlFSPathEquals	(	const vl_filesys_path *	pathA,
		const vl_filesys_path *	pathB
	)

Compares two filesystem paths for equality.

Parameters

pathA	First path to compare
pathB	Second path to compare

Returns: True if paths are equal, false otherwise

Here is the call graph for this function:

◆ vlFSPathExists()

VL_API vl_bool_t vlFSPathExists ( const vl_filesys_path * path )

Checks if a file or directory exists at the specified path.

Parameters

path	Pointer to the path to check

Returns: True if the path exists, false otherwise

Here is the call graph for this function:

◆ vlFSPathIsAbsolute()

VL_API vl_bool_t vlFSPathIsAbsolute ( const vl_filesys_path * path )

Checks if a filesystem path is absolute.

Parameters

path	Pointer to the path object to check

Returns: True if the path is absolute, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathJoin()

VL_API void vlFSPathJoin	(	const vl_filesys_path *	base,
		vl_filesys_path *	dest,
		const char *	component
	)

Joins a path component to a base path.

Parameters

	base	Base path to join to
[out]	dest	Destination path object for the result
	component	Path component to join

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathMkDir()

VL_API vl_filesys_result vlFSPathMkDir ( const vl_filesys_path * path )

Creates a directory at the specified path.

Parameters

path	Pointer to the path where the directory should be created

Returns: Result code indicating success or failure

Here is the call graph for this function:

◆ vlFSPathNew()

VL_API vl_filesys_path * vlFSPathNew	(	vl_filesys *	sys,
		const char *	path
	)

Creates a new filesystem path object.

Parameters

sys	Pointer to the filesystem context
path	String representation of the path

Returns: Pointer to the newly created path object

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathNormalize()

VL_API void vlFSPathNormalize ( vl_filesys_path * path )

Normalizes a filesystem path by resolving relative components.

This function will normalize the given path with native file path separators.

Parameters

path	Pointer to the path object to normalize

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathParent()

VL_API void vlFSPathParent	(	const vl_filesys_path *	path,
		vl_filesys_path *	parentOut
	)

Gets the parent directory of a filesystem path.

Parameters

	path	Input path
[out]	parentOut	Pointer to store the parent path

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathRemove()

VL_API vl_filesys_result vlFSPathRemove ( const vl_filesys_path * path )

Removes a file or directory at the specified path.

Parameters

path	Pointer to the path to remove

Returns: Result code indicating success or failure

Here is the call graph for this function:

◆ vlFSPathSet()

VL_API void vlFSPathSet	(	vl_filesys_path *	path,
		const char *	pathStr
	)

Sets the path string for a filesystem path object.

Parameters

path	Pointer to the path object
pathStr	String representation of the new path

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSPathString()

VL_API const vl_transient * vlFSPathString ( const vl_filesys_path * path )

Gets the string representation of a filesystem path.

Parameters

path	Pointer to the path object

Returns: Pointer to the path string

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlFSStatDelete()

VL_API void vlFSStatDelete ( vl_filesys_stat * stat )

Deletes a file stat object.

Parameters

stat	Pointer to the stat object to delete

Here is the call graph for this function:

◆ vlFSStatIter()

VL_API vl_filesys_result vlFSStatIter	(	vl_filesys_iter	iter,
		vl_filesys_stat *	result
	)

Gets file status information for the current iterator position.

Parameters

	iter	Directory iterator handle
[out]	result	Pointer to store the stat information

Returns: Result code indicating success or failure

Here is the call graph for this function:

◆ vlFSStatNew()

VL_API vl_filesys_stat * vlFSStatNew ( vl_filesys * sys )

Creates a new file stat object.

Parameters

sys	Pointer to the filesystem context

Returns: Pointer to the newly created stat object

Here is the call graph for this function:

◆ vlFSStatPath()

VL_API vl_filesys_result vlFSStatPath	(	const vl_filesys_path *	path,
		vl_filesys_stat *	result
	)

Gets file status information for a given path.

Parameters

	path	Pointer to the path to query
[out]	result	Pointer to store the stat information

Returns: Result code indicating success or failure

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ vl_filesys_path

◆ vl_filesys_stat

◆ vl_filesys

Macro Definition Documentation

◆ VL_FS_ITER_INVALID

Enumeration Type Documentation

◆ vl_filesys_result

Function Documentation

◆ vlFSDelete()

◆ vlFSFree()

◆ vlFSInit()

◆ vlFSIterDelete()

◆ vlFSIterDir()

◆ vlFSIterDirRecursive()

◆ vlFSIterNew()

◆ vlFSIterNext()

◆ vlFSNew()

◆ vlFSPathAbsolute()

◆ vlFSPathClone()

◆ vlFSPathDelete()

◆ vlFSPathEquals()

◆ vlFSPathExists()

◆ vlFSPathIsAbsolute()

◆ vlFSPathJoin()

◆ vlFSPathMkDir()

◆ vlFSPathNew()

◆ vlFSPathNormalize()

◆ vlFSPathParent()

◆ vlFSPathRemove()

◆ vlFSPathSet()

◆ vlFSPathString()

◆ vlFSStatDelete()

◆ vlFSStatIter()

◆ vlFSStatNew()

◆ vlFSStatPath()