# `./fio-stl/004 files.h` 28 public symbols. ### Macros #### `FIO_FILENAME_PATH_CAPA` ```c #define FIO_FILENAME_PATH_CAPA (PATH_MAX | 4096) ``` _Symbol type:_ `macro` #### `FIO_FD_FIND_EOF` ```c #define FIO_FD_FIND_EOF ((size_t)-1) ``` End of file value for `fio_fd_find_next` _Symbol type:_ `macro` #### `FIO_FD_FIND_BLOCK` ```c #define FIO_FD_FIND_BLOCK 4096 ``` Size on the stack used by `fio_fd_find_next` for each read cycle. _Symbol type:_ `macro` #### `FIO_FOLDER_SEPARATOR` ```c #define FIO_FOLDER_SEPARATOR '\\' ``` _Symbol type:_ `macro` ### Types #### `fio_filename_remove_args_s` ```c typedef struct { /** The path of the file / folder to remove. */ const char *path; /** Set to allow the removal of an (empty) folder. */ uint8_t folder; /** Set to remove a folder and all of its content (implies `folder`). */ uint8_t recursive; } fio_filename_remove_args_s ``` Arguments for `fio_filename_remove`. _Symbol type:_ `type` #### `fio_filename_make_path_args_s` ```c typedef struct { /** The folder path to create (nested folders allowed). */ const char *path; /** The creation mode (POSIX only); zero (0) defaults to 0755. */ uint32_t mode; } fio_filename_make_path_args_s ``` Arguments for `fio_filename_make_path`. _Symbol type:_ `type` #### `fio_filename_s` ```c typedef struct { fio_buf_info_s folder; fio_buf_info_s basename; fio_buf_info_s ext; } fio_filename_s ``` A result type for the filename parsing helper. _Symbol type:_ `type` ### Functions #### `fio_filename_open` ```c int fio_filename_open(const char *filename, int flags) ``` Opens `filename`, returning the same as values as `open` on POSIX systems. If `path` starts with a `"~/"` than it will be relative to the user's home folder (on Windows, testing for `"~\"`). Uses a fixed size stack buffer (zero allocations); over-long paths fail with `errno == ENAMETOOLONG` (see `FIO_FILENAME_PATH_CAPA`). _Symbol type:_ `function` #### `fio_filename_is_unsafe` ```c int fio_filename_is_unsafe(const char *path) ``` Returns 1 if `path` does folds backwards (OS separator dependent). _Symbol type:_ `function` #### `fio_filename_is_unsafe_url` ```c int fio_filename_is_unsafe_url(const char *path) ``` Returns 1 if `path` does folds backwards (has "/../" or "//"). _Symbol type:_ `function` #### `fio_filename_tmp` ```c int fio_filename_tmp(void) ``` Creates a temporary file, returning its file descriptor. _Symbol type:_ `function` #### `fio_filename_remove` ```c int fio_filename_remove(fio_filename_remove_args_s args) ``` Removes the file / link or folder at `path`. * By default (no flags), removes a file / link (like `unlink`). * With `folder` set, removes an empty folder (like `rmdir`). * With `recursive` set (implies `folder`), removes a folder and all of its content (like `rm -r`). If `path` isn't a folder, the `recursive` flag is ignored and `path` is removed as a file / link. Links are removed, never followed into. Uses a fixed size stack buffer (zero allocations); over-long paths fail with `errno == ENAMETOOLONG` (see `FIO_FILENAME_PATH_CAPA`). Returns 0 on success and -1 on error. Recursive removal stops on the first error (some content may remain). _Symbol type:_ `function` #### `fio_filename_remove` ```c #define fio_filename_remove(...) \ fio_filename_remove((fio_filename_remove_args_s){__VA_ARGS__}) ``` _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_filename_make_path` ```c int fio_filename_make_path(fio_filename_make_path_args_s args) ``` Creates the folder at `path`, including any missing parent folders (similar to `mkdir -p`). An existing folder is NOT an error. A non-folder component along the way IS an error (`errno == ENOTDIR`). Uses a fixed size stack buffer (zero allocations); over-long paths fail with `errno == ENAMETOOLONG` (see `FIO_FILENAME_PATH_CAPA`). Returns 0 on success and -1 on error. _Symbol type:_ `function` #### `fio_filename_make_path` ```c #define fio_filename_make_path(...) \ fio_filename_make_path((fio_filename_make_path_args_s){__VA_ARGS__}) ``` _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_filename_overwrite` ```c inline int fio_filename_overwrite(const char *filename, const void *buf, size_t len) ``` Overwrites `filename` with the data in the buffer. If `path` starts with a `"~/"` than it will be relative to the user's home folder (on Windows, testing for `"~\"`). Returns -1 on error or 0 on success. On error, the state of the file is undefined (may be doesn't exit / nothing written / partially written). _Symbol type:_ `function` #### `fio_filename_size` ```c inline size_t fio_filename_size(const char *filename) ``` Returns the file size (or 0 on both error / empty file). _Symbol type:_ `function` #### `fio_fd_size` ```c inline size_t fio_fd_size(int fd) ``` Returns the file size (or 0 on both error / empty file). _Symbol type:_ `function` #### `fio_filename_type` ```c inline size_t fio_filename_type(const char *filename) ``` Returns the file type (or 0 on both error). See: https://www.man7.org/linux/man-pages/man7/inode.7.html _Symbol type:_ `function` #### `fio_filename_stat` ```c inline int fio_filename_stat(const char *filename, struct stat *stat_buf) ``` Populates `stat_buf` with the file's metadata. Returns 0 on success. _Symbol type:_ `function` #### `fio_fd_type` ```c inline size_t fio_fd_type(int fd) ``` Returns the file type (or 0 on both error). See: https://www.man7.org/linux/man-pages/man7/inode.7.html _Symbol type:_ `function` #### `fio_filename_is_folder` ```c #define fio_filename_is_folder(filename) \ (fio_filename_type((filename)) == S_IFDIR) ``` Tests if `filename` references a folder. Returns -1 on error. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_fd_write` ```c inline ssize_t fio_fd_write(int fd, const void *buf, size_t len) ``` Writes data to a file handle, returning the number of bytes written. Returns -1 on error. Since some systems have a limit on the number of bytes that can be written at a time, this function fragments the system calls into smaller `write` blocks, allowing large data to be written. If the file descriptor is non-blocking, test errno for EAGAIN / EWOULDBLOCK. _Symbol type:_ `function` #### `fio_fd_read` ```c inline size_t fio_fd_read(int fd, void *buf, size_t len, off_t start_at) ``` Reads up to `len` bytes from `fd`, returning the number of bytes read. Returns 0 if no bytes were read or on error. Since some systems have a limit on the number of bytes that can be read at a time, this function fragments the system calls into smaller `read` blocks, allowing large data to be read. If the file descriptor is non-blocking, test errno for EAGAIN / EWOULDBLOCK. _Symbol type:_ `function` #### `fio_filename_parse` ```c fio_filename_s fio_filename_parse(const char *filename) ``` Parses a file name to folder, base name and extension (zero-copy). _Symbol type:_ `function` #### `fio_filename_parse2` ```c fio_filename_s fio_filename_parse2(const char *filename, size_t len) ``` Parses a file name to folder, base name and extension (zero-copy). _Symbol type:_ `function` #### `fio_fd_find_next` ```c size_t fio_fd_find_next(int fd, char token, size_t start_at) ``` Returns offset for the next `token` in `fd`, or -1 if reached EOF. This will use `FIO_FD_FIND_BLOCK` bytes on the stack to read the file in a loop. Pros: limits memory use and (re)allocations, easier overflow protection. Cons: may be slower, as data will most likely be copied again from the file. _Symbol type:_ `function` #### `fio_file_dup` ```c #define fio_file_dup(fd) _dup(fd) ``` Duplicates the file handle (int) _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` -----------------------------------------------------