CBuild wiki

FS.h

File system access abstraction layer.

License: GPL-3.0-or-later.

cbuild_pathlist_t

typedef struct cbuild_pathlist_t {
char** data;
size_t size;
size_t capacity;
} cbuild_pathlist_t;

Dynamic array of paths

cbuild_pathlist_get

#define cbuild_pathlist_get(list, idx)

Get element from list of paths using its index.

char** Pointer to an element or NULL if index out of bounds.

cbuild_pathlist_clear

CBUILDDEF void cbuild_pathlist_clear(cbuild_pathlist_t* list);

Free pathlist.

This function should really be used instead of simple free(list->data) because pathlist allocated memory in two levels.

cbuild_filetype_t

typedef enum {
CBUILD_FTYPE_MISSING   = -1,
CBUILD_FTYPE_REGULAR   = 0,
CBUILD_FTYPE_DIRECTORY = 1,
CBUILD_FTYPE_SYMLINK   = 2,
CBUILD_FTYPE_OTHER     = 3,
} cbuild_filetype_t;

Type of file. Mostly cross-platform because no special Unix files are included.

cbuild_fd_close

CBUILDDEF bool cbuild_fd_close(cbuild_fd_t fd);

Close file descriptor.

cbuild_fd_open_read

CBUILDDEF cbuild_fd_t cbuild_fd_open_read(const char* path);

Open file for reading.

cbuild_fd_open_write

CBUILDDEF cbuild_fd_t cbuild_fd_open_write(const char* path);

Open file for writing.

cbuild_fd_open_pipe

CBUILDDEF bool cbuild_fd_open_pipe(cbuild_fd_t* read, cbuild_fd_t* write);

Create and open new pipe. File descriptors for both ends are provided.

cbuild_fd_read

CBUILDDEF ssize_t cbuild_fd_read(cbuild_fd_t fd, void* buf, size_t nbytes);

POSIX read wrapper.

  • cbuild_fd_t fd File descriptor.
  • void* buf Buffer in which data will be read.
  • size_t nbytes Number of bytes to read.

ssize_t Number of bytes read or -1 on error.

cbuild_fd_read_file

CBUILDDEF ssize_t cbuild_fd_read_file(cbuild_fd_t fd, void* buf, size_t nbytes,
const char* path);

POSIX read “wrapper”. This function uses pathconst char* only for error-reporting.

  • cbuild_fd_t fd File descriptor.
  • void* buf Buffer in which data will be read.
  • size_t nbytes Number of bytes to read.
  • const char* path File name used in error reporting.

ssize_t Number of bytes read or -1 on error.

cbuild_fd_write

CBUILDDEF ssize_t cbuild_fd_write(cbuild_fd_t fd, const void* buf, size_t nbytes);

POSIX write wrapper.

  • cbuild_fd_t fd File descriptor.
  • const void* buf Buffer from which data will be written.
  • size_t nbytes Number of bytes to write.

ssize_t Number of bytes written or -1 on error.

cbuild_fd_write_file

CBUILDDEF ssize_t cbuild_fd_write_file(cbuild_fd_t fd, const void* buf,
size_t nbytes, const char* path);

POSIX write “wrapper”. This function uses pathconst char* only for error-reporting.

  • cbuild_fd_t fd File descriptor.
  • const void* buf Buffer from which data will be written.
  • size_t nbytes Number of bytes to write.
  • const char* path File name used in error reporting.

ssize_t Number of bytes written or -1 on error.

cbuild_file_len

CBUILDDEF ssize_t cbuild_file_len(const char* path);

Get length of file in bytes.

ssize_t Length of file in bytes or -1 on error.

cbuild_file_read

CBUILDDEF bool cbuild_file_read(const char* path, cbuild_sb_t* data);

Read file into string builder.

cbuild_file_write

CBUILDDEF bool cbuild_file_write(const char* path, cbuild_sb_t* data);

Overwrite file with string builder content.

cbuild_file_copy

CBUILDDEF bool cbuild_file_copy(const char* src, const char* dst);

Copy file.

This copies file by reading from srcconst char* and writing to dstconst char*. “Chunked” copy is used to limit memory usage.

cbuild_file_move

CBUILDDEF bool cbuild_file_move(const char* src, const char* dst);

Move file.

Uses optimal method for moving file, but in worst case falls back to cbuild_file_copy(src, dst); cbuild_file_remove(src).

cbuild_file_rename

#define cbuild_file_rename(src, dst)

Rename file. Alias to cbuild_file_move.

Uses optimal method for moving file, but in worst case falls back to cbuild_file_copy(src, dst); cbuild_file_remove(src).

  • const char* src
  • const char* dst

bool

cbuild_file_check

CBUILDDEF bool cbuild_file_check(const char* path);

Check if file exists.

cbuild_file_remove

CBUILDDEF bool cbuild_file_remove(const char* path);

Delete file.

cbuild_dir_copy

CBUILDDEF bool cbuild_dir_copy(const char* src, const char* dst);

Recursively copy a directory.

cbuild_dir_move

CBUILDDEF bool cbuild_dir_move(const char* src, const char* dst);

Move a directory.

Uses optimal method for moving directory, but in worst case falls back to cbuild_dir_copy(src, dst); cbuild_dir_remove(src).

cbuild_dir_rename

#define cbuild_dir_rename(src, dst)

Rename a directory. Alias to cbuild_dir_move.

Uses optimal method for moving directory, but in worst case falls back to cbuild_dir_copy(src, dst); cbuild_dir_remove(src).

  • const char* src
  • const char* dst

bool

cbuild_dir_remove

CBUILDDEF bool cbuild_dir_remove(const char* path);

Delete directory.

cbuild_dir_check

CBUILDDEF bool cbuild_dir_check(const char* path);

Check if directory exists.

cbuild_dir_list

CBUILDDEF bool cbuild_dir_list(const char* path, cbuild_pathlist_t* elements);

List all files in directory.

  • const char* path Path to a directory.
  • cbuild_pathlist_t* elements List of elements in directory.

cbuild_dir_current

CBUILDDEF char* cbuild_dir_current(void);

Get current working directory.

char* Current working directory values. Allocated __CBUILD_MALLOC.

cbuild_dir_set_current

CBUILDDEF bool cbuild_dir_set_current(const char* path);

Set current working directory.

cbuild_dir_create

CBUILDDEF bool cbuild_dir_create(const char* path);

Create new directory.

cbuild_dir_walk_result_t

enum cbuild_dir_walk_result_t {
CBUILD_DIR_WALK_CONTINUE = 0,
CBUILD_DIR_WALK_NO_ENTER,
CBUILD_DIR_WALK_STOP = -1,
};

Result for cbuild_dir_walk_func_t.

  • CBUILD_DIR_WALK_CONTINUE Default value. Just continue.
  • CBUILD_DIR_WALK_NO_ENTER Do not enter into a directory.
  • CBUILD_DIR_WALK_STOP Stop entirely (but does not return an error).

cbuild_dir_walk_func_args_t

typedef struct cbuild_dir_walk_func_args_t {
const char* path;
cbuild_filetype_t type;
size_t level;
enum cbuild_dir_walk_result_t* result;
void* context;
} cbuild_dir_walk_func_args_t;

Arguments for cbuild_dir_walk_func_t.

This structure can be divided into multiple sections:

  • Current entry:
    • const char* path Path to the file system object object (relative and including directory passed to cbuild_dir_walk.
    • cbuild_filetype_t type Type of current file-system object.
  • Iteration state:
    • size_t level How deep iteration goes (0 means base directory).
  • Context:
    • void* context Some arguments passed by user.
    • enum cbuild_dir_walk_result_t* result Return value.

cbuild_dir_walk_func_t

typedef bool (*cbuild_dir_walk_func_t)(cbuild_dir_walk_func_args_t args);

Function used as callback by directory walker.

bool false means error.

cbuild_dir_walk_opts_t

struct cbuild_dir_walk_opts_t {
void* context;
bool visit_dir_last;
};

Arguments to a directory walker.

  • void* context Some arguments that will be passed to callback.
  • bool visit_dir_last Inverts order. Now all child files are visited first and parent directory is visited last.

cbuild_dir_walk_opt

CBUILDDEF bool cbuild_dir_walk_opt(const char* path, cbuild_dir_walk_func_t func,
struct cbuild_dir_walk_opts_t opts);

Walk over dir. Takes path, callback and some optional options. Semi-internal function.

cbuild_dir_walk

#define cbuild_dir_walk(path, callback, ...)

Walk over dir.

cbuild_dir_open

CBUILDDEF cbuild_dir_t cbuild_dir_open(const char* path);

Open directory.

cbuild_dir_next

CBUILDDEF int cbuild_dir_next(cbuild_dir_t dir, const char** element);

Get next element from directory.

  • cbuild_dir_t dir Directory handle.

  • const char** element Return value for filename.

  • 0 No error and directory iterator is still not empty.

  • 1 No error but directory iterator is empty. elementconst char** is NULL.

  • -1 Error happened.

cbuild_dir_close

CBUILDDEF bool cbuild_dir_close(cbuild_dir_t dir);

Close directory.

cbuild_path_filetype

CBUILDDEF cbuild_filetype_t cbuild_path_filetype(const char* path);

Get type of file.

cbuild_path_ext_opts_t

struct cbuild_path_ext_opts_t {
int dot; // Get n-th dot from the end, 0 is last one (same as 1)
};

Optional arguments for cbuild_path_ext.

  • int dot Get extensions after n-th dot from the end. 0 is default value (for now it is same as 1).

cbuild_path_ext_opt

CBUILDDEF char* cbuild_path_ext_opt(const char* path, struct cbuild_path_ext_opts_t opts);

Get extension of specific file. Semi-internal. File pointer by pathconst char* is not checked in any way.

char* String allocated via cbuild_temp_malloc.

cbuild_path_ext

#define cbuild_path_ext(path, ...)

Get extension of specific file. File pointer by pathconst char* is not checked in any way.

`]{.return-type} String allocated via [cbuild_temp_malloc`.

cbuild_path_name

CBUILDDEF char* cbuild_path_name(const char* path);

Get file name with extension (all after last /). For directories special case exists that strips last / if it is last character. File pointer by pathconst char* is not checked in any way.

char* String allocated via cbuild_temp_malloc.

cbuild_path_base

CBUILDDEF char* cbuild_path_base(const char* path);

Get base name (all before last /). For directories special case exists that strips last / if it is last character. File pointer by pathconst char* is not checked in any way.

char* String allocated via cbuild_temp_malloc.

cbuild_path_normalize

CBUILDDEF char* cbuild_path_normalize(const char* path);

Normalize path. All normalization is based on heuristics and does not involve such steps as eg. symlink resolving. File pointer by pathconst char* is not checked in any way.

char* String allocated via cbuild_temp_malloc.