API

group bareio

Defintions for bare I/O.

Defines

y_IO_FD_INVALID

A define for an invalid file descriptor.

y_IO_PIPE_READ_IDX

The index to read from a bare pipe.

y_IO_PIPE_WRITE_IDX

The index to write to a bare pipe.

Typedefs

typedef int y_fd

A cross-platform type for file descriptors.

Functions

y_Status y_io_pipe_init(y_io_pipe *p)

Creates a unidirectional pipe using a y_io_pipe.

Parameters:

p – The bare pipe to initialize the file descriptors of.

Returns:

An error code, if any.

Pre:

p must not be NULL.

void y_io_pipe_close(y_io_pipe *p)

Closes a pipe.

Parameters:

p – The pipe to close.

struct y_io_pipe
#include <io.h>

A type for a bare pipe to be used for sending child notifications to the right thread.

group dir

Functions and data structures to manipulate directories.

Typedefs

typedef struct y_dir *y_Dir

The public type for directories.

This is a pointer to hide the implementation.

Functions

y_Status y_fs_dir_mkdir(y_Path path)

Creates the directory at path.

Parameters:

path – The path to create the directory at.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

path must not be NULL.

y_Status y_fs_dir_mkdirat(y_Path path, y_Dir parent)

Creates the directory at path, which is treated as relative to parent.

Parameters:

  • path – The path to create the directory at.

  • parent – The parent directory to interpret the path.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

path must not be NULL.

y_Status y_fs_dir_mkdirp(y_Path path)

Creates the directory at path, making sure to create any missing parent directories.

Parameters:

path – The path to create the directory at.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

path must not be NULL.

y_Status y_fs_dir_open(y_Dir *d, y_Path path)

Opens and returns the directory at path.

The opened directory must be closed by using y_fs_dir_close().

Parameters:

  • d – The y_Dir to initialize.

  • path – The path to open the directory at.

Returns:

An error code, if any.

Pre:

d must not be NULL.

Pre:

d must not be opened.

Pre:

path must not be NULL.

y_Status y_fs_dir_reopen(y_Dir d, y_Path path)

Reopens dir with path.

Parameters:

  • d – The directory to reopen.

  • path – The path to open the directory at.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

d must not be NULL.

Pre:

d must have been opened.

Pre:

path must not be NULL.

y_Status y_fs_dir_openat(y_Dir *d, y_Dir parent, y_Path path, bool mkdirs)

Opens a directory relative to a parent.

This opens all intermediate parents, going up to the root if the parent is NULL. This function resolves links and uses the real path.

Parameters:

  • d – A pointer to return the opened directory in.

  • parent – An already-opened parent, or NULL if none.

  • path – The path to the directory to open, relative to the parent.

  • mkdirs – True if directories should be created when they don’t exist, false otherwise.

Returns:

An error code, if any.

Pre:

d must not be NULL.

bool y_fs_dir_hasNext(y_Dir d)

Returns true if the directory has another entry.

Parameters:

d – The directory to query.

Returns:

True if the directory has another entry, false otherwise.

Pre:

d must not be NULL.

Pre:

d must be open.

y_Status y_fs_dir_first(y_Dir dir)

Loads the first entry in dir.

Parameters:

dir – The directory whose entry will be loaded.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

y_Status y_fs_dir_next(y_Dir dir)

Loads the next entry in dir.

Parameters:

dir – The directory whose next entry will be loaded.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

dir must have been opened.

y_Dirent y_fs_dir_entry(y_Dir d)

Returns the y_Dirent of the current entry in the directory.

Parameters:

d – The directory to query.

Returns:

The dirent of the current entry, of y_DIRENT_INVALID if none.

Pre:

d must not be NULL.

Pre:

d must be open.

void y_fs_dir_sort(y_Dir d, bool dirsFirst)

Sorts the open directory d.

Parameters:

  • d – The directory to sort.

  • dirsFirst – Whether to put directories first or not.

Pre:

d must not be NULL.

Pre:

d must have been opened.

void y_fs_dir_unsort(y_Dir d)

Unsorts d.

This does not change the order of any entries, but if the directory is reopened with another path, or used to open its parent or a subdirectory, the new one will not be sorted.

Parameters:

d – The directory to not sort.

Pre:

d must not be NULL.

Pre:

d must have been opened.

y_Status y_fs_dir_subdir(y_Dir d, y_Dirent i)

Opens the subdirectory of d at entry i.

The directory must not be closed first.

Parameters:

  • d – The directory whose subdirectory will be opened.

  • i – The index of the entry that will be opened.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

d must not be NULL.

Pre:

d must have been opened.

Pre:

d must have an entry associated with i.

y_Status y_fs_dir_parent(y_Dir d)

Opens the parent of d into d.

The directory must not be closed first.

Parameters:

d – The directory whose parent will be opened.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

d must not be NULL.

Pre:

d must have been opened.

y_Status y_fs_dir_home(y_Dir d)

Opens the home directory into d.

The directory must not be closed first.

Parameters:

d – The directory into which the home directory will be opened.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

d must not be NULL.

Pre:

d must have been opened.

y_Path y_fs_dir_path(y_Dir dir)

Returns a pointer to the path of dir.

The pointer will be invalidated if it is reopened or closed, or if its parent or a subdirectory is opened.

Parameters:

dir – The directory to query.

Returns:

The path of the directory.

Pre:

dir must not be NULL.

Pre:

dir must have been opened.

y_u32 y_fs_dir_numEntries(y_Dir dir)

Returns the number of entries in dir.

Parameters:

dir – The directory to query.

Returns:

The number of entries in dir.

Pre:

dir must not be NULL.

Pre:

dir must have been opened.

bool y_fs_dir_sorted(y_Dir dir)

Returns true if dir is sorted, false otherwise.

Parameters:

dir – The directory to query.

Returns:

true if sorted, false otherwise.

Pre:

dir must not be NULL.

Pre:

dir must have been opened.

bool y_fs_dir_dirsFirst(y_Dir dir)

Returns true if dir is sorted with directories first, false otherwise.

Parameters:

dir – The directory to query.

Returns:

true if sorted with directories first, false otherwise.

Pre:

dir must not be NULL.

Pre:

dir must have been opened.

void y_fs_dir_close(y_Dir dir)

Closes the directory dir.

Parameters:

dir – The directory to close.

Pre:

dir must not be NULL.

Pre:

dir must have been opened.

group dirent

Functions and data structures to manipulate directory entries.

Defines

A bit marking a link.

y_STAT_READ

A bit marking read permission.

y_STAT_WRITE

A bit marking write permission.

y_STAT_EXEC

A bit marking execute permission.

For directories, this means whether it can be searched or not.

y_STAT_PERM_READ

Read permission for a file.

This is used as a flag to check the permissions in y_Stat and with the dirent permission functions.

y_STAT_PERM_WRITE

Write permission for a file.

This is used as a flag to check the permissions in y_Stat and with the dirent permission functions.

y_STAT_PERM_EXEC

Execute permission for a file and search permission for directories.

This is used as a flag to check the permissions in y_Stat and with the dirent permission functions.

y_DIRENT_INVALID

A marker for invalid dirents.

Typedefs

typedef y_u32 y_Dirent

The public type for directory entries.

Entries are always within the context of an open directory.

Enums

enum y_StatType

An enum of possible file types.

Values:

enumerator y_STAT_TYPE_SPECIAL

Special file.

On POSIX, this includes character and block devices. On Windows, this includes character devices.

enumerator y_STAT_TYPE_PIPE

Pipe.

enumerator y_STAT_TYPE_REGULAR

Regular disk file.

enumerator y_STAT_TYPE_DIR

Directory.

Functions

y_Path y_fs_dirent_name(const y_Dir parent, y_Dirent dirent)

Returns a pointer to the entry’s name.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

A pointer to the name.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

y_u32 y_fs_dirent_ext(const y_Dir parent, y_Dirent dirent)

Returns an index to the entry’s extension.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

An index to the extension.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

y_usize y_fs_dirent_size(const y_Dir parent, y_Dirent dirent)

Returns the size of the entry (file size or directory data size in bytes).

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

The entry’s size, in bytes.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

bool y_fs_dirent_isDir(const y_Dir parent, y_Dirent dirent)

Returns true if the entry is a directory.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

true if directory, false otherwise.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

bool y_fs_dirent_isFile(const y_Dir parent, y_Dirent dirent)

Returns true if the entry is a file.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

true if file, false otherwise.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

y_u8 y_fs_dirent_ownerPerms(const y_Dir parent, y_Dirent dirent)

Returns the owner permissions for the entry.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

The owner permissions for the entry.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

y_u8 y_fs_dirent_groupPerms(const y_Dir parent, y_Dirent dirent)

Returns the group permissions for the entry.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

The group permissions for the entry.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

y_u8 y_fs_dirent_otherPerms(const y_Dir parent, y_Dirent dirent)

Returns the other permissions for the entry.

Parameters:

  • parent – The parent directory.

  • dirent – The index of the entry in the parent directory.

Returns:

The other permissions for the entry.

Pre:

parent must be opened.

Pre:

parent must have an entry associated with dirent.

struct y_Stat
#include <io.h>

A struct to contain information about a directory entry.

group path

Functions and data types for paths.

Defines

y_FS_PATH_MAX

The max number of y_pchar’s that a path can contain.

y_FS_FILENAME_MAX

The max number of y_pchar’s that a file (entry) name can contain.

Functions

y_Status y_fs_path_dup(y_Path *dest, y_Path src)

Duplicates the source path and stores it in the destination, which must be freed with y_fs_path_destroy().

Parameters:

  • dest – The destination path, which is assumed to be uninitialized.

  • src – The source path, which is assumed to be initialized.

Returns:

An error code, if any.

Pre:

dest must not be NULL.

y_Status y_fs_path_init_cstr(y_Path *path, const char *s)

Initializes path with the y_Path that matches the string.

The string is assumed to be UTF-8.

Parameters:

  • path – The path to initialize and set.

  • s – The string to turn into a path.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

s must not be NULL.

Pre:

s must be UTF-8.

y_Status y_fs_path_sinit_cstr(y_Path *path, const char *s)

Initializes path with the y_Path that matches the string.

The string is assumed to be UTF-8. Uses the stack allocator for the thread.

Parameters:

  • path – The path to initialize and set.

  • s – The string to turn into a path.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

s must not be NULL.

Pre:

s must be UTF-8.

y_Status y_fs_path_init_str(y_Path *path, y_str s)

Initializes path with the y_Path that matches the string.

The string is assumed to be UTF-8.

Parameters:

  • path – The path to initialize and set.

  • s – The string to turn into a path.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

s’s string must not be NULL.

Pre:

s’s string must be UTF-8.

y_Status y_fs_path_sinit_str(y_Path *path, y_str s)

Initializes path with the y_Path that matches the string.

The string is assumed to be UTF-8. Uses the stack allocator for the thread.

Parameters:

  • path – The path to initialize and set.

  • s – The string to turn into a path.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

s’s string must not be NULL.

Pre:

s’s string must be UTF-8.

y_Status y_fs_path_init_string(y_Path *path, const y_String s)

Initializes path with the y_Path that matches the string.

The string is assumed to be UTF-8.

Parameters:

  • path – The path to initialize and set.

  • s – The string to turn into a path.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

s must not be NULL.

Pre:

s must be UTF-8.

y_Status y_fs_path_sinit_string(y_Path *path, const y_String s)

Initializes path with the y_Path that matches the string.

The string is assumed to be UTF-8. Uses the stack allocator for the thread.

Parameters:

  • path – The path to initialize and set.

  • s – The string to turn into a path.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

s must not be NULL.

Pre:

s must be UTF-8.

y_Status y_fs_path_remove(const y_Path path)

Removes the item at path.

Parameters:

path – The path to the item to remove.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

path must not be NULL.

y_Error y_fs_path_stat_a(const y_pchar *path, y_Stat *st, bool resolve, bool perms)

Retrieves information about the item at path and returns it in the y_Stat struct pointed to by st.

Parameters:

  • path – The path to the item to collect data about.

  • st – A pointer to the structure to fill.

  • resolve – True if links should be resolved, false otherwise.

  • perms – True if the permissions should be gotten, false otherwise.

Returns:

y_ERROR_SUCCESS on success, an error code otherwise.

Pre:

path must not be NULL.

Pre:

st must not be NULL.

y_Error y_fs_path_stat(y_Path path, y_Stat *st, bool resolve, bool perms)

Retrieves information about the item at path and returns it in the y_Stat struct pointed to by st.

Parameters:

  • path – The path to the item to collect data about.

  • st – A pointer to the structure to fill.

  • resolve – True if links should be resolved, false otherwise.

  • perms – True if the permissions should be gotten, false otherwise.

Returns:

y_ERROR_SUCCESS on success, an error code otherwise.

Pre:

path must not be NULL.

Pre:

st must not be NULL.

bool y_fs_path_stat_exists(const y_Path path, y_Stat *st, bool resolve)

Tests if the file or directory exists, and if it does, it fills in the provided stat pointer.

Parameters:

  • path – The path to the file or directory.

  • st – The stat pointer to fill in.

  • resolve – True if links should be resolved, false otherwise.

Returns:

True if something exists at path, false otherwise.

Pre:

path must be initialized.

Pre:

st must not be NULL.

bool y_fs_stat_isFile(y_Stat *st)

Returns true if the stat information points to a regular file or a link.

Parameters:

st – The stat information.

Returns:

True if the stat information is for a regular file or a link, false otherwise.

Pre:

st must not be NULL.

Pre:

st must have been initialized by a call to y_fs_path_stat() or y_fs_path_stat_exists().

bool y_fs_stat_isDir(y_Stat *st)

Returns true if the stat information points to a directory.

Parameters:

st – The stat information.

Returns:

True if the stat information is for a directory. false otherwise.

Pre:

st must not be NULL.

Pre:

st must have been initialized by a call to y_fs_path_stat() or y_fs_path_stat_exists().

bool y_fs_stat_sameFile(y_Stat *st1, y_Stat *st2)

Returns true if both given instances file information are for the same file.

Parameters:

  • st1 – The first instance of file information.

  • st2 – The second instance of file information.

Returns:

True if the instances are for the same file, false otherwise.

Pre:

st1 must not be NULL.

Pre:

st2 must not be NULL.

y_Status y_fs_path_parent(y_Dir *d, y_Path path)

Opens the parent directory of the item at path.

The directory must be closed with y_fs_dir_close().

Parameters:

  • d – The directory to initialize.

  • path – The path to the item whose directory parent will be opened.

Returns:

An error code, if any.

Pre:

d must not be NULL.

Pre:

d must not be open.

Pre:

path must not be NULL.

y_Status y_fs_path_dirname(y_Path *dir_name, y_Path path)

Gets the directory (parent) name of path.

The path must be freed with y_fs_path_destroy().

Parameters:

  • dir_name – The path to initialize with the directory name.

  • path – The path to get the dirname for.

Returns:

An error code, if any.

Pre:

dir_name must not be NULL.

Pre:

path must be valid.

y_Status y_fs_path_basename(y_Path *base_name, y_Path path)

Gets the base (file) name of path.

The path must be freed with y_fs_path_destroy().

Parameters:

  • base_name – The path to initialize with the base name.

  • path – The path to get the basename for.

Returns:

An error code, if any.

Pre:

base_name must not be NULL.

Pre:

path must be valid.

y_Status y_fs_path_realpath(y_Path *realpath, y_Path path)

Gets the realpath of path.

Parameters:

  • realpath – The path to initialize and set.

  • path – The path to get the realpath of.

Returns:

An error code, if any.

Pre:

realpath must not be NULL.

Pre:

path must be valid.

y_Status y_fs_path_realpathAt(y_Path *realpath, y_Dir parent, y_Path path)

Gets the realpath of path.

Parameters:

  • realpath – The path to initialize and set.

  • parent – The directory that the path is relative to.

  • path – The path to get the realpath of.

Returns:

An error code, if any.

Pre:

realpath must not be NULL.

Pre:

path must be valid.

y_Status y_fs_path_srealpath(y_Path *realpath, y_Path path)

Gets the realpath of path and allocates it on the thread stackpool.

Parameters:

  • realpath – The path to initialize and set.

  • path – The path to get the realpath of.

Returns:

An error code, if any.

Pre:

realpath must not be NULL.

Pre:

path must be valid.

y_Status y_fs_path_home(y_Path *home)

Gets the path of the home directory.

The path must be freed with y_fs_path_destroy().

Parameters:

home – The path to initialize and set.

Returns:

An error code, if any.

Pre:

home must not be NULL.

y_Status y_fs_path_temp(y_Path *temp)

Gets the path of the temp directory.

The path must be freed with y_fs_path_destroy().

Parameters:

temp – The path to initialize and set.

Returns:

An error code, if any.

Pre:

temp must not be NULL.

y_Status y_fs_path_extIdx(const y_Path path, y_u32 *idx)

Returns the index within path that the file extension starts, not including the leading period.

If there is no extension, this returns strlen(path).

Parameters:

  • path – The path to query for the extension.

  • idx – A pointer to return the index of the path that the extension starts.

Returns:

An error code, if any.

Pre:

path.a must not be NULL.

Pre:

idx must not be NULL.

bool y_fs_path_isDir(const y_Path path, bool resolve)

Returns true if something exists at the given path and it is a directory.

Parameters:

  • path – The path to test.

  • resolve – True if links should be resolved, false otherwise.

Returns:

True if anything at the path exists and if it is a directory, false otherwise.

Pre:

path must be initialized.

bool y_fs_path_isFile(const y_Path path, bool resolve)

Returns true if something exists at the given path and it is a regular file.

Parameters:

  • path – The path to test.

  • resolve – True if links should be resolved, false otherwise.

Returns:

True if anything at the path exists and if it is a regular file, false otherwise.

Pre:

path must be initialized.

bool y_fs_path_exists(const y_Path path, bool resolve)

Returns true if anything exists at the given path.

Parameters:

  • path – The path to test.

  • resolve – True if links should be resolved, false otherwise.

Returns:

True if anything at the path exists, false otherwise.

Pre:

path must be initialized.

y_Status y_fs_path_copyFile(const y_Path dest, const y_Path src)

Copies the file at the path.

If it is not a file at the path, this returns an error. If there is a file, it is truncated to 0 before copying.

Parameters:

  • dest – The path to the destination file.

  • src – The path to the file to copy.

Returns:

An error code, if any.

Pre:

dest must be initialized.

Pre:

src must be initialized.

y_Status y_fs_path_copyTree(const y_Path dest, const y_Path src)

Copies the tree at the source to the destinatio.

If the source is to a regular file or a link, it copies it.

Parameters:

  • dest – The path to the destination tree.

  • src – The path to the tree to copy.

Returns:

An error code, if any.

Pre:

dest must be initialized.

Pre:

src must be initialized.

y_Status y_fs_path_concat(y_Path *res, y_Path path, y_Path name)

Concatenates path and name into one path and returns the result.

The path must be freed with y_fs_path_destroy().

Parameters:

  • res – The path to initialize and set.

  • path – The beginning part of the path.

  • name – The file name.

Returns:

An error code, if any.

Pre:

res must not be NULL.

Pre:

path must not be NULL.

Pre:

name must not be NULL.

y_Status y_fs_path_sconcat(y_Path *res, y_Path path, y_Path name)

Concatenates path and name into one path and returns the result.

Uses the stack allocator, so the path must be freed with y_stackallocator_free().

Parameters:

  • res – The path to initialize and set.

  • path – The beginning part of the path.

  • name – The file name.

Returns:

An error code, if any.

Pre:

res must not be NULL.

Pre:

path must not be NULL.

Pre:

name must not be NULL.

y_Status y_fs_path_link(y_Path new, y_Path existing)

Creates a new hard link to an existing path.

Parameters:

  • new – The path for the hard link.

  • existing – The path to the existing hard like.

Returns:

An error code, if any.

y_Status y_fs_path_readlink(y_Path *target, y_Path path)

Returns the contents of a symbolic link in a new path.

If the path is not a link, it’s an error. This always resolves links.

Parameters:

  • target – The path that will be initialized with the link contents.

  • path – The path to the symbolic link.

Returns:

An error code, if any.

Pre:

target must not be NULL.

y_Status y_fs_path_readlinkat(y_Path *target, y_Dir parent, y_Path path)

Returns the contents of a symbolic link in a new path relative to a parent directory.

If the path is not a link, it’s an error. This always resolves links.

Parameters:

  • target – The path that will be initialized with the link contents.

  • parent – A file descriptor to a parent directory. This can be equal to NULL. If it is, then the path is used as is. Otherwise, the path is resolved relative to the parent.

  • path – The path to the symbolic link.

Returns:

An error code, if any.

Pre:

target must not be NULL.

y_Status y_fs_path_symlink(y_Path path, y_Path target)

Creates a symbolic link at the given path whose contents will be the given target.

Parameters:

  • path – The path to the symbolic link to create.

  • target – The contents of the symbolic link.

Returns:

An error code, if any.

Pre:

path must be a valid path.

Pre:

target must be a valid path.

y_Status y_fs_path_symlinkat(y_Path path, y_Dir parent, y_Path target)

Creates a symbolic link at the given path, relative to the given parent directory, whose contents will be the given target.

Parameters:

  • path – The path to the symbolic link to create.

  • parent – The parent directory to interpret path relative to. This can be NULL.

  • target – The contents of the symbolic link.

Returns:

An error code, if any.

Pre:

path must be a valid path.

Pre:

target must be a valid path.

y_Status y_fs_path_rename(y_Path path, y_Path new)

Renames the path to the new path.

If these are relative paths, they are relative to the current directory.

Parameters:

  • path – The current path.

  • new – The new path.

Returns:

An error code, if any.

Pre:

path must be a valid path.

Pre:

new must be a valid path.

y_Status y_fs_path_renameat(y_Path path, y_Dir parent, y_Path new, y_Dir newparent)

Renames the path to the new path.

If these are relative paths, they are relative to the given parents, if non-NULL, or the current directory otherwise.

Parameters:

  • path – The current path.

  • parent – The parent directory to interpret the path relative to.

  • new – The new path.

  • newparent – The parent directory to interpret the new path relative to.

Returns:

An error code, if any.

Pre:

path must be a valid path.

Pre:

new must be a valid path.

y_Status y_fs_path_nchown(y_Path path, const char *owner, const char *group)

Changes the owner/group of the given path to the given owner and group.

If the owner or group are NULL, they are not changed.

Parameters:

  • path – The path to change the owner/group of.

  • owner – The username of the new owner. This can be NULL.

  • group – The group name of the new group. This can be NULL.

Returns:

An error code, if any.

Pre:

path must be a valid path.

y_Status y_fs_path_chown(y_Path path, y_uid_t *owner, y_gid_t *group)

Changes the owner/group of the given path to the given owner and group.

If the owner or group are NULL, they are not changed.

Parameters:

  • path – The path to change the owner/group of.

  • owner – The user ID of the new owner. This can be NULL.

  • group – The group ID of the new group. This can be NULL.

Returns:

An error code, if any.

Pre:

path must be a valid path.

y_Status y_fs_path_chmod(y_Path path, y_u8 uperms, y_u8 gperms, y_u8 operms)

Changes the permissions of the given path for the current platform.

Parameters:

  • path – The path to change the permissions of.

  • uperms – The permissions for the path owner.

  • gperms – The permissions for the path group.

  • operms – The permissions for everyone else.

Returns:

An error code, if any.

Pre:

path must be a valid path.

void y_fs_path_destroy(void *path)

Frees path.

Parameters:

path – The path to free.

Pre:

path should not be NULL.

struct y_Path
#include <io.h>

A common definition for paths.

Paths should not be modified.

struct y_Pathv
#include <io.h>

A list of paths.

This is for breaking apart things like the PATH environment variable.

group file

Functions and data structures to manipulate files.

Defines

y_FILE_CREATE

A flag for if the file was opened in create mode.

y_FILE_BINARY

A flag for if the file was opened in binary mode.

y_FILE_READ

A flag for if the file was opened in read mode.

y_FILE_WRITE

A flag for if the file was opened in write mode.

y_FILE_APPEND

A flag for if the file was opened in append mode.

y_FILE_TRUNC

A flag for if the file was opened in truncate mode.

y_FILE_EXCLUSIVE

A flag for if the file was opened in exclusive mode.

This cannot be used without y_FILE_CREATE. This is for implementing lock files.

Typedefs

typedef off_t y_offset

A cross-platform type for file offsets.

typedef struct y_file *y_File

Public type for the private file type.

typedef y_bytes y_FileBytes

The public definition of Yc’s file contents.

This allows the user to index it directly.

Enums

enum y_FileSeek

The type of seeks available on files.

Values:

enumerator y_FILE_SEEK_BEGIN

Seek relative to the beginning of the file.

enumerator y_FILE_SEEK_CUR

Seek relative to the current position.

enumerator y_FILE_SEEK_END

Seek relative to the end of the file.

Functions

void y_fs_filebytes_destroy(void *filebytes)

Frees the data read into a y_FileBytes.

Parameters:

filebytes – The file data to free.

y_Status y_fs_file_create(y_Path path)

Creates the file at path.

Parameters:

path – The path to create the file at.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

y_Status y_fs_file_createWithParents(y_Path path)

Creates the file at path, making sure to create any missing parent directories.

Parameters:

path – The path to create the file at.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

y_Status y_fs_file_temp(y_Path *path, y_Path dir, y_Path prefix)

Creates a temp file name, creates the file, and returns the path to the file.

Parameters:

  • path – The path to initialize and set.

  • dir – The directory to create the file in.

  • prefix – The prefix to prepend to the file name.

Returns:

An error code, if any.

Pre:

path must not be NULL.

Pre:

dir must be valid.

Pre:

prefix must be valid.

y_Status y_fs_file_open(y_File *f, y_Path path, y_u8 mode)

A cross-platform fopen.

Parameters:

  • f – A pointer to the file to initialize.

  • path – The path of the file to open.

  • mode – The mode to open the file in, using y_FILE_* values.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

path.a must not be NULL.

y_Status y_fs_file_openAt(y_File *f, y_Dir parent, y_Path path, y_u8 mode)

A cross-platform fopen that safely opens all directories above, starting at the root.

If there is a directory whose ancestors are all open, it can be passed in. This function resolves links and uses the real path.

Parameters:

  • f – A pointer to the file to initialize.

  • parent – An open handle to the parent directory of the path, or NULL if it is not open. If it is NULL, all of the ancestors of the file will be opened in a chain. If it is not NULL, then the path is treated as though it’s relative to this directory, and all of the ancestors of the file beginning at parent will be opened.

  • path – The path of the file to open.

  • mode – The mode to open the file in, using y_FILE_* values.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

path.a must not be NULL.

y_Status y_fs_file_openRealpath(y_File *f, y_Path *realpath, y_Path path, y_u8 mode)

Gets the realpath of path and open it, checking that the file at the real path was actually opened.

Warning: This function is still racy because there’s no real way around that. However, it tries to minimize the window as much as possible.

Parameters:

  • f – A pointer to the file to initialize.

  • realpath – The path to initialize and set.

  • path – The path to get the realpath of.

  • mode – The mode to open the file in, using y_FILE_* values.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

realpath must not be NULL.

Pre:

path must be valid.

y_Status y_fs_file_openAtRealpath(y_File *f, y_Path *realpath, y_Dir parent, y_Path path, y_u8 mode)

Gets the realpath of path and open it, checking that the file at the real path was actually opened.

The path is opened relative to a parent directory.

Warning: This function is still racy because there’s no real way around that. However, it tries to minimize the window as much as possible.

Parameters:

  • f – A pointer to the file to initialize.

  • realpath – The path to initialize and set.

  • parent – The parent directory to interpret path relative to.

  • path – The path to get the realpath of.

  • mode – The mode to open the file in, using y_FILE_* values.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

realpath must not be NULL.

Pre:

path must be valid.

y_Status y_fs_file_stat(y_File f, y_Stat *st)

Gets information about an open file.

Parameters:

  • f – The file.

  • st – A pointer to return the file information.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must be open.

Pre:

st must not be NULL.

y_Status y_fs_file_seek(y_File f, y_FileSeek seek, y_offset off)

Seeks to a position in a file.

Parameters:

  • f – The file to seek within.

  • seek – The seek type to perform.

  • off – The offset relative to the seek type to seek to.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

y_Status y_fs_file_truncate(y_File f, y_offset len)

Sets the length of a file.

If the file size cannot be set, such as if the file is not a file on disk, this returns an error. If the file is truncated, the data beyond the truncation is lost. If the file is extended, it is filed with bytes of zeroes.

Parameters:

  • f – The file to set the length of.

  • len – The length to set the file to.

Returns:

An error code, if any.

Pre:

f must not be NULL.

y_Status y_fs_file_size(y_File f, y_ullong *size)

Returns the size of a file.

Parameters:

  • f – The file to get the size of.

  • size – A pointer to store the size into.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

Pre:

size must not be NULL.

y_Status y_fs_file_sync(y_File f, y_uint ndirs)

Syncs a file to disk.

This ensures that the file persists. If the file is not syncable, this returns no error.

Parameters:

  • f – The file to sync.

  • ndirs – The number of directories above f to sync. If there are less directories than this parameter, this syncs all of them and stops. A value of 0 is allowed, but on some platforms, that may not properly persist the file to disk.

Returns:

An error code, if any. Anything but success means the file may not have been synced.

Pre:

f must not be NULL.

Pre:

f must have been opened.

y_Status y_fs_file_copy(y_Path dest, y_Path src)

Copies a file to a new path.

The new file is a copy, not a link. If the destination already exists, it is truncated to 0 bytes first.

Parameters:

  • dest – The path to the destination file.

  • src – The path to the source file.

Returns:

An error code, if any.

void y_fs_file_close(void *file)

Closes a file and destroys it.

Because this cannot return any error code in the event of an I/O error on flush, it is strongly suggested that y_fflush() be called first if any data has been written to the file.

Parameters:

file – The file to close and destroy.

Pre:

file must not be NULL.

y_Status y_putc(y_uchar c)

Prints a character to stdout.

Parameters:

c – The character to print.

Returns:

An error code, if any.

y_Status y_eputc(y_uchar c)

Prints a character to stderr.

Parameters:

c – The character to print.

Returns:

An error code, if any.

y_Status y_fputc(y_File f, y_uchar c)

Prints a character to a file.

Parameters:

  • f – The file to print to.

  • c – The character to print.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

y_Status y_getc(y_uchar *c)

Gets a character from stdin.

Parameters:

c – A pointer to the character to initialize.

Returns:

An error code, if any.

Pre:

c must not be NULL.

y_Status y_fgetc(y_File f, y_uchar *c)

Gets a character from a file.

Parameters:

  • f – The file.

  • c – A pointer to the character to initialize.

Returns:

An error code, if any.

Pre:

c must not be NULL.

y_Status y_puts(const char *str)

Prints a string to stdout.

Parameters:

str – The string to print.

Returns:

An error code, if any.

Pre:

str must not be NULL.

y_Status y_eputs(const char *str)

Prints a string to stderr.

Parameters:

str – The string to print.

Returns:

An error code, if any.

Pre:

str must not be NULL.

y_Status y_fputs(y_File f, const char *str)

Prints a string to a file.

Parameters:

  • f – The file to print to.

  • str – The string to print.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

Pre:

str must not be NULL.

y_Status y_gets(y_uchar *buf, y_usize n, y_usize *nread)

Gets a line from stdin.

A max of n - 1 characters are read. This is because the result is terminated with a nul character.

Parameters:

  • buf – The buffer to read into.

  • n – The size of buf.

  • nread – A pointer to store the number of read characters into if it is not NULL.

Returns:

An error code, if any.

Pre:

buf must not be NULL.

Pre:

buf must be at least n bytes.

y_Status y_fgets(y_File f, y_uchar *buf, y_usize n, y_usize *nread)

Gets a line from a file.

A max of n - 1 characters are read. This is because the result is terminated with a nul character.

Parameters:

  • f – The file to read from.

  • buf – The buffer to read into.

  • n – The size of buf.

  • nread – A pointer to store the number of read characters into if it is not NULL.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must be opened for reading.

Pre:

buf must not be NULL.

Pre:

buf must be at least n bytes.

y_Status y_printf(const char *const fmt, ...)

Prints formatted output to stdout.

The formatting is exactly according to the rules of printf(), although not all features may be implemented.

Parameters:

fmt – The format string.

Returns:

An error code, if any.

Pre:

fmt must not be NULL.

y_Status y_eprintf(const char *const fmt, ...)

Prints formatted output to stderr.

The formatting is exactly according to the rules of printf(), although not all features may be implemented.

Parameters:

fmt – The format string.

Returns:

An error code, if any.

Pre:

fmt must not be NULL.

y_Status y_fprintf(y_File f, const char *const fmt, ...)

Prints formatted output to a file.

The formatting is exactly according to the rules of printf(), although not all features may be implemented.

Parameters:

  • f – The file to print to.

  • fmt – The format string.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

Pre:

fmt must not be NULL.

y_Status y_vprintf(const char *const fmt, va_list args)

Prints formatted output to stdout using a va_list.

The formatting is exactly according to the rules of printf(), although not all features may be implemented.

Parameters:

  • fmt – The format string.

  • args – The format arguments.

Returns:

An error code, if any.

Pre:

fmt must not be NULL.

Pre:

args must be valid.

y_Status y_veprintf(const char *const fmt, va_list args)

Prints formatted output to stderr using a va_list.

The formatting is exactly according to the rules of printf(), although not all features may be implemented.

Parameters:

  • fmt – The format string.

  • args – The format arguments.

Returns:

An error code, if any.

Pre:

fmt must not be NULL.

Pre:

args must be valid.

y_Status y_vfprintf(y_File f, const char *const fmt, va_list args)

Prints formatted output to a file using a va_list.

The formatting is exactly according to the rules of printf(), although not all features may be implemented.

Parameters:

  • f – The file to print to.

  • fmt – The format string.

  • args – The format arguments.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

Pre:

fmt must not be NULL.

Pre:

args must be valid.

y_Status y_read(y_uchar *buf, y_usize n, y_usize *nread)

Reads at most n characters from stdin into buf.

The number of characters read is returned in nread if it not NULL.

Parameters:

  • buf – The buffer to read into.

  • n – The max number of characters to read.

  • nread – A pointer to return the number of characters read.

Returns:

An error code, if any.

Pre:

buf must not be NULL.

Pre:

buf must have at least n bytes of space.

y_Status y_fread(y_File f, y_uchar *buf, y_usize n, y_usize *nread)

Reads at most n characters from a file into buf.

The number of characters read is returned in nread if it not NULL.

Parameters:

  • f – The file to read from.

  • buf – The buffer to read into.

  • n – The max number of characters to read.

  • nread – A pointer to return the number of characters read.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

Pre:

buf must not be NULL.

Pre:

buf must have at least n bytes of space.

y_Status y_write(const char *buf, y_usize n, y_usize *nwritten)

Writes at most n characters from buf to stdout.

The number of characters written is returned in nwritten if it not NULL.

Parameters:

  • buf – The buffer to read into.

  • n – The number of characters to write.

  • nwritten – A pointer to return the number of characters written.

Returns:

An error code, if any.

Pre:

buf must not be NULL.

Pre:

buf must have at least n bytes of space.

y_Status y_fwrite(y_File f, const char *buf, y_usize n, y_usize *nwritten)

Writes at most n characters from buf to a file.

The number of characters written is returned in nwritten if it not NULL.

Parameters:

  • f – The file to read from.

  • buf – The buffer to read into.

  • n – The number of characters to write.

  • nwritten – A pointer to return the number of characters written.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

Pre:

buf must not be NULL.

Pre:

buf must have at least n bytes of space.

y_Status y_flush(void)

Flushes stdout.

Returns:

An error code, if any.

y_Status y_eflush(void)

Flushes stderr.

Returns:

An error code, if any.

y_Status y_fflush(y_File f)

Flushes a file.

Parameters:

f – The file to flush.

Returns:

An error code, if any.

Pre:

f must not be NULL.

Pre:

f must have been opened.

y_Status y_fs_filebytes_read(y_FileBytes *bytes, y_Path path, bool binary)

Reads the entirety of the file at path and returns a y_FileBytes (byte array) with the contents.

The param binary indicates whether the file is a binary file or not. If not, this will add a terminating null char.

The bytes must be freed with y_fs_filebytes_free().

Parameters:

  • bytes – The byte array to initialize.

  • path – The path to the file.

  • binary – true if the file is a binary file, false otherwise.

Returns:

An error code, if any.

Pre:

bytes must not be NULL.

y_Status y_fs_filebytes_fread(y_FileBytes *bytes, y_File file, y_ullong size, bool binary)

Reads the entirety of the file file and returns a y_FileBytes (byte array) with the contents.

The param binary indicates whether the file is a binary file or not. If not, this will add a terminating null char.

If size is 0, the file is assumed to be a non-seekable file.

The bytes must be freed with y_fs_filebytes_free().

Parameters:

  • bytes – The byte array to initialize.

  • file – The file to read.

  • size – The size of the file. This should be 0 for non-seekable files.

  • binary – true if the file is a binary file, false otherwise.

Returns:

An error code, if any.

Pre:

bytes must not be NULL.

Pre:

file must not be NULL.

y_Status y_fs_filebytes_sread(y_FileBytes *bytes, y_Path path, bool binary)

Reads the entirety of the file at path and returns a y_FileBytes (byte array) with the contents.

The param binary indicates whether the file is a binary file or not. If not, this will add a terminating null char.

The file must be freed with y_stackallocator_free() because this function uses the stack allocator.

Parameters:

  • bytes – The byte array to initialize.

  • path – The path to the file.

  • binary – true if the file is a binary file, false otherwise.

Returns:

An error code, if any.

Pre:

file must not be NULL.

Pre:

path must be valid.

Variables

y_File y_stdin

A handle to stdin.

y_File y_stdout

A handle to stdout.

y_File y_stderr

A handle to stderr.