#./fio-stl/004 files.h

28 public symbols.

#Macros

#FIO_FILENAME_PATH_CAPA

#define FIO_FILENAME_PATH_CAPA (PATH_MAX | 4096)

Symbol type: macro

#FIO_FD_FIND_EOF

#define FIO_FD_FIND_EOF ((size_t)-1)

End of file value for fio_fd_find_next

Symbol type: macro

#FIO_FD_FIND_BLOCK

#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

#define FIO_FOLDER_SEPARATOR '\\'

Symbol type: macro

#Types

#fio_filename_remove_args_s

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

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

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

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

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

int fio_filename_is_unsafe_url(const char *path)

Returns 1 if path does folds backwards (has "/../" or "//").

Symbol type: function

#fio_filename_tmp

int fio_filename_tmp(void)

Creates a temporary file, returning its file descriptor.

Symbol type: function

#fio_filename_remove

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

#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

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

#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

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

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

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

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

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

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

#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

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

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

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

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

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

#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