File system

The file system APIs allow for arbitrary file system access on the host system. These APIs do not yet apply any restrictions or sandboxing on modification or manipulation of any files accessible by the current host OS user.

---

#include <playbit/file.h>

PBFile

typedef struct PBFile {
    PBSysHandle handle;
} PBFile;

PBFile represents a file or directory on a file system

PBFileOpenFlags

typedef enum PBFileOpenFlags {
    PBFileOpen_READ = PBSysFileOpenFlag_READ,     // give file PBSysRight_READ
    PBFileOpen_WRITE = PBSysFileOpenFlag_WRITE,   // give file PBSysRight_WRITE
    PBFileOpen_APPEND = PBSysFileOpenFlag_APPEND, // open in append mode
    PBFileOpen_CREATE = PBSysFileOpenFlag_CREATE, // create file if it does not exist

    // PBFileOpen_MODE_ bits are used when creating files
    PBFileOpen_MODE_MASK = PBSysFileOpenFlag_MODE_MASK,
    PBFileOpen_MODE_USER_R = PBSysFileOpenFlag_MODE_USER_R, // user (owner) has read permission
    PBFileOpen_MODE_USER_W = PBSysFileOpenFlag_MODE_USER_W, // user has write permission
    PBFileOpen_MODE_USER_X = PBSysFileOpenFlag_MODE_USER_X, // user has execute permission
    PBFileOpen_MODE_USER_RWX = PBSysFileOpenFlag_MODE_USER_RWX,
    PBFileOpen_MODE_GROUP_R = PBSysFileOpenFlag_MODE_GROUP_R, // group has read permission
    PBFileOpen_MODE_GROUP_W = PBSysFileOpenFlag_MODE_GROUP_W, // group has write permission
    PBFileOpen_MODE_GROUP_X = PBSysFileOpenFlag_MODE_GROUP_X, // group has execute permission
    PBFileOpen_MODE_GROUP_RWX = PBSysFileOpenFlag_MODE_GROUP_RWX,
    PBFileOpen_MODE_OTHER_R = PBSysFileOpenFlag_MODE_OTHER_R, // others have read permission
    PBFileOpen_MODE_OTHER_W = PBSysFileOpenFlag_MODE_OTHER_W, // others have write permission
    PBFileOpen_MODE_OTHER_X = PBSysFileOpenFlag_MODE_OTHER_X, // others have execute permission
    PBFileOpen_MODE_OTHER_RWX = PBSysFileOpenFlag_MODE_OTHER_RWX,

    // aliases
    PBFileOpen_R = PBFileOpen_READ,
    PBFileOpen_W = PBFileOpen_WRITE,
    PBFileOpen_RW = PBFileOpen_READ | PBFileOpen_WRITE,
} PBFileOpenFlags;

PBFileOpenFlags changes behavior of PBFileOpen

PBFileSystemRoot

PBFile PBFileSystemRoot();

PBFileSystemRoot returns the default/initial file system provided to the current thread when it was started.

PBFileOpen

PBSysErr PBFileOpen(PBFile*    file,
                    PBFile     at,
                    PBStrSlice path,
                    u32        flags);

PBFileOpen opens a file at path relative to parent directory at, or to file at if path is empty.

• flags: Bits of PBFileOpenFlags
• Returns: PBFile.handle<0 as PBSysErr on failure.

PBFileOpenOrPanic

PBFile PBFileOpenOrPanic(PBFile     at,
                         PBStrSlice path,
                         u32        flags);

PBFileOpenOrPanic works like PBFileOpen but panics on error

PBFileClose

void PBFileClose(PBFile* file);

PBFileClose closes file->handle and sets it to PBSysHandle_INVALID

PBFileRead

i64 PBFileRead(PBFile file,
               u8*    buf,
               usize  bufCap);

PBFileRead reads from file into buf.

• Returns: number of bytes read into buf, or PBSysErr as a negative value

PBFileReadv

i64 PBFileReadv(PBFile          file,
                const PBSysBuf* bufs,
                u32             bufCount);

PBFileReadv reads from file into bufs.

• Returns: number of bytes read into bufs, or PBSysErr as a negative value

PBFileReadAll

PBSysErr PBFileReadAll(PBFile file,
                       PBBuf* buf,
                       PBMem  ma);

PBFileReadAll reads an entire file into a buffer allocated in ma

PBFileWrite

i64 PBFileWrite(PBFile    file,
                const u8* buf,
                usize     bufLen);

PBFileWrite writes to file from buf.

• Returns: number of bytes written from buf, or PBSysErr as a negative value

PBFileWritev

i64 PBFileWritev(PBFile          file,
                 const PBSysBuf* bufs,
                 u32             bufCount);

PBFileWritev writes to file from bufs.

• Returns: number of bytes written from bufs, or PBSysErr as a negative value

---

#include <playbit/dir_iterator.h>

PBDirIterator

typedef struct PBDirIterator {
    PBMem              ma;
    PBSysHandle        handle;
    PBSysFileListEntry info; // information about the current entry
    union {
        PBStrSlice name; // name of the current entry
        PBBuf      nameBuf;
    };
} PBDirIterator;

PBDirIterator represents a directory iterator

PBDirIteratorOpen

PBSysErr PBDirIteratorOpen(PBDirIterator* dirIterator,
                           PBFile         dir,
                           PBStrSlice     subdirPath,
                           PBMem          ma);

PBDirIteratorOpen opens a directory iterator at dir/subdirPath, or dir if subdirPath.len == 0

PBDirIteratorOpenOrPanic

PBDirIterator PBDirIteratorOpenOrPanic(PBFile     dir,
                                       PBStrSlice subdirPath,
                                       PBMem      ma);

PBDirIteratorOpenOrPanic works like PBDirIteratorOpen but panics on error

PBDirIteratorNext

bool PBDirIteratorNext(PBDirIterator* dirIterator);

PBDirIteratorNextName advances the iterator and retrieves the name of the next entry. The name is appended to buf, allocating memory with ma. The order of iteration is undefined and depends on the underlying filesystem and operating system.

Example of listing names of all files in the directory "foo/bar" at the file system root:

PBFile        root = PBFileSystemRoot();
PBDirIterator it = PBDirIteratorOpenOrPanic(root, PBStrSliceOf("foo/bar"), kMemGPA);
while (PBDirIteratorNext(&it))
    print("%.*s", (int)it.name.len, (const char*)it.name.v);
PBDirIteratorClose(&it);

• Returns: true if a name was appended to buf, false if there are no more entries or if a filesystem error occurred.

PBDirIteratorClose

void PBDirIteratorClose(PBDirIterator* dirIterator);

PBDirIteratorClose closes dirIterator->handle and sets it to PBSysHandle_INVALID