File filesystem.h¶
Headers > cais > filesystem.h
Go to the documentation of this file
/*
* cais - Communication Abstraction & I/O Substrate
* Projectum Lunare <https://github.com/projectum-lunare/cais>
* Copyright (C) 2026 Gustavo Veiga <gustavo.veiga@outlook.com.br>
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/
#ifndef CAIS_FILESYSTEM_H
#define CAIS_FILESYSTEM_H
#include <stddef.h>
#include <cais/types.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
* =============================================================================
* Types, Constants & Enumerations
* =============================================================================
*/
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
typedef unsigned long long cais_fsize_t;
#elif defined(_MSC_VER)
typedef unsigned __int64 cais_fsize_t;
#elif defined(__GNUC__) || defined(__clang__)
__extension__ typedef unsigned long long cais_fsize_t;
#else
typedef unsigned long cais_fsize_t;
#endif
#ifndef CAIS_PATH_MAX
#define CAIS_PATH_MAX 1024
#endif
typedef enum {
CAIS_FS_TYPE_UNKNOWN = 0,
CAIS_FS_TYPE_FILE = 1,
CAIS_FS_TYPE_DIR = 2,
CAIS_FS_TYPE_SYMLINK = 3,
CAIS_FS_TYPE_DEVICE = 4,
CAIS_FS_TYPE_FIFO = 5,
CAIS_FS_TYPE_SOCKET = 6
} cais_fs_type_t;
typedef struct cais_fs_stat {
cais_fs_type_t type;
cais_fsize_t size;
long mtime;
long atime;
long ctime;
int mode;
cais_bool_t is_readonly;
} cais_fs_stat_t;
typedef struct cais_fs_dirent {
char name[256];
cais_fs_type_t type;
} cais_fs_dirent_t;
typedef struct cais_fs_dir cais_fs_dir_t;
typedef struct cais_file cais_file_t;
#define CAIS_FS_SEEK_SET 0
#define CAIS_FS_SEEK_CUR 1
#define CAIS_FS_SEEK_END 2
/*
* =============================================================================
* 1. Path Algebra & Pure Normalization (No Syscalls / Zero Disk I/O)
* =============================================================================
*/
/*
* Joins two path components using the native separator.
* Returns CAIS_OK on success, or CAIS_ERROR if out_cap is insufficient.
*/
cais_status_t cais_fs_path_join(const char *p1, const char *p2, char *out, size_t out_cap);
/*
* Normalizes a path in-place or into out:
* - Resolves '.' and '..' components
* - Collapses repeated separators
* Returns CAIS_OK on success, or CAIS_ERROR if out_cap is insufficient.
*/
cais_status_t cais_fs_path_normalize(const char *path, char *out, size_t out_cap);
/*
* Extracts the base name (final component) of path.
* Returns CAIS_OK on success, or CAIS_ERROR if out_cap is insufficient.
*/
cais_status_t cais_fs_path_basename(const char *path, char *out, size_t out_cap);
/*
* Extracts the directory name (parent component) of path.
* Returns CAIS_OK on success, or CAIS_ERROR if out_cap is insufficient.
*/
cais_status_t cais_fs_path_dirname(const char *path, char *out, size_t out_cap);
/*
* Extracts the file extension (including the leading dot, e.g. ".txt") of path.
* If no extension exists, writes an empty string.
* Returns CAIS_OK on success, or CAIS_ERROR if out_cap is insufficient.
*/
cais_status_t cais_fs_path_ext(const char *path, char *out, size_t out_cap);
/*
* Checks whether the given path is absolute.
* Returns CAIS_TRUE if absolute, CAIS_FALSE if relative or invalid.
*/
cais_bool_t cais_fs_path_is_absolute(const char *path);
/*
* Returns the primary path separator character for the current platform.
*/
char cais_fs_path_separator(void);
/*
* =============================================================================
* 2. File & Directory Inspection (Metadata & Stat)
* =============================================================================
*/
/*
* Checks whether a file, device node, or directory exists at path.
* Returns CAIS_TRUE if exists, CAIS_FALSE otherwise.
*/
cais_bool_t cais_fs_exists(const char *path);
/*
* Retrieves metadata for the filesystem entry at path, following symlinks.
* Returns CAIS_OK on success, or CAIS_ERROR on failure (writing message to err_buf).
*/
cais_status_t cais_fs_stat(const char *path, cais_fs_stat_t *st, char *err_buf, size_t err_cap);
/*
* Retrieves metadata for the filesystem entry at path without following symlinks.
* On platforms without symlink support, behaves identically to cais_fs_stat.
* Returns CAIS_OK on success, or CAIS_ERROR on failure (writing message to err_buf).
*/
cais_status_t cais_fs_lstat(const char *path, cais_fs_stat_t *st, char *err_buf, size_t err_cap);
/*
* Predicates: fast boolean checks.
* Return CAIS_TRUE if condition holds, CAIS_FALSE if false or on error.
*/
cais_bool_t cais_fs_is_file(const char *path);
cais_bool_t cais_fs_is_dir(const char *path);
cais_bool_t cais_fs_is_symlink(const char *path);
/*
* Retrieves file size directly.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_file_size(const char *path, cais_fsize_t *out_size);
/*
* =============================================================================
* 3. File System Operations & Mutation
* =============================================================================
*/
/*
* Creates a single directory at path with the given permission mode (e.g. 0755).
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_mkdir(const char *path, int mode, char *err_buf, size_t err_cap);
/*
* Recursively creates parent directories as needed (equivalent to mkdir -p).
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_mkdir_p(const char *path, int mode, char *err_buf, size_t err_cap);
/*
* Removes an empty directory at path.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_rmdir(const char *path, char *err_buf, size_t err_cap);
/*
* Unlinks / deletes a file or symbolic link at path.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_remove(const char *path, char *err_buf, size_t err_cap);
/*
* Recursively deletes a file or directory tree (equivalent to rm -rf).
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_remove_all(const char *path, char *err_buf, size_t err_cap);
/*
* Renames or moves a file or directory from oldpath to newpath.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_rename(const char *oldpath, const char *newpath, char *err_buf, size_t err_cap);
/*
* Copies a regular file from src to dst.
* If overwrite is CAIS_FALSE and dst already exists, fails with CAIS_ERROR.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_copy_file(const char *src, const char *dst, cais_bool_t overwrite, char *err_buf, size_t err_cap);
/*
* Changes the permission mode of a file or directory.
* Returns CAIS_OK on success, or CAIS_ERROR / CAIS_UNSUPPORTED on failure.
*/
cais_status_t cais_fs_chmod(const char *path, int mode, char *err_buf, size_t err_cap);
/*
* =============================================================================
* 4. Directory Iteration (Streaming Iterator)
* =============================================================================
*/
/*
* Opens a directory for streaming iteration.
* Returns an opaque cais_fs_dir_t handle, or NULL on failure.
*/
cais_fs_dir_t *cais_fs_dir_open(const char *path, char *err_buf, size_t err_cap);
/*
* Reads the next directory entry.
* Skips "." and ".." automatically.
* Returns:
* CAIS_OK : ent populated with the next entry name and type.
* CAIS_EOF : no more entries in directory.
* CAIS_ERROR: iteration failed.
*/
cais_status_t cais_fs_dir_next(cais_fs_dir_t *dir, cais_fs_dirent_t *ent);
/*
* Closes a directory handle and releases resources.
*/
void cais_fs_dir_close(cais_fs_dir_t *dir);
/*
* =============================================================================
* 5. File Content Operations (Slurp / Spit & Streaming Handles)
* =============================================================================
*/
/*
* Reads the entire contents of a file into a newly allocated buffer.
* Caller is responsible for freeing *out_buf with free().
* Null-terminates *out_buf (*out_buf[*out_len] == '\0') for text convenience.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_read_file(const char *path, void **out_buf, size_t *out_len, char *err_buf, size_t err_cap);
/*
* Writes data into path, overwriting any existing contents.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_write_file(const char *path, const void *buf, size_t len, char *err_buf, size_t err_cap);
/*
* Appends data to path, creating the file if it does not exist.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_append_file(const char *path, const void *buf, size_t len, char *err_buf, size_t err_cap);
/*
* Opens a file stream with mode string ("r", "w", "a", "r+", "w+", "a+").
* Returns an allocated cais_file_t handle, or NULL on failure.
*/
cais_file_t *cais_file_open(const char *path, const char *mode, char *err_buf, size_t err_cap);
/*
* Reads up to count bytes from file into buf.
* Populates *bytes_read with the actual number of bytes read.
* Returns CAIS_OK on success, or CAIS_EOF / CAIS_ERROR.
*/
cais_status_t cais_file_read(cais_file_t *f, void *buf, size_t count, size_t *bytes_read);
/*
* Writes up to count bytes from buf into file.
* Populates *bytes_written with the actual number of bytes written.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_file_write(cais_file_t *f, const void *buf, size_t count, size_t *bytes_written);
/*
* Sets the file position indicator.
* whence: CAIS_FS_SEEK_SET, CAIS_FS_SEEK_CUR, CAIS_FS_SEEK_END.
* If new_pos is non-NULL, writes the resulting file offset.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_file_seek(cais_file_t *f, long offset, int whence, long *new_pos);
/*
* Obtains the current file position indicator.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_file_tell(cais_file_t *f, long *pos);
/*
* Flushes buffered output to disk.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_file_flush(cais_file_t *f);
/*
* Closes the file stream and releases allocated memory.
*/
void cais_file_close(cais_file_t *f);
/*
* =============================================================================
* 6. Environment & Special Directories
* =============================================================================
*/
/*
* Gets the current working directory of the process.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_getcwd(char *buf, size_t cap, char *err_buf, size_t err_cap);
/*
* Changes the current working directory of the process.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_setcwd(const char *path, char *err_buf, size_t err_cap);
/*
* Obtains the path to the operating system's temporary directory.
* Returns CAIS_OK on success, or CAIS_ERROR on failure.
*/
cais_status_t cais_fs_temp_dir(char *buf, size_t cap, char *err_buf, size_t err_cap);
#ifdef __cplusplus
}
#endif
#endif /* CAIS_FILESYSTEM_H */