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

PBFileMode

typedef u16 PBFileMode;

PBFile represents a file or directory on a file system

PBFileModes

enum PBFileModes PB_ENUM_TYPE(PBFileMode){
    PBFileMode_USER_R = 0400,    // user (file owner) has read permission
    PBFileMode_USER_W = 0200,    // user has write permission
    PBFileMode_USER_X = 0100,    // user has execute permission
    PBFileMode_USER_RW = 0600,   // user has read and write permissions
    PBFileMode_USER_RWX = 0700,  // user has read, write, and execute permissions
    PBFileMode_GROUP_R = 0040,   // group has read permission
    PBFileMode_GROUP_W = 0020,   // group has write permission
    PBFileMode_GROUP_X = 0010,   // group has execute permission
    PBFileMode_GROUP_RW = 0060,  // group has read and write execute permissions
    PBFileMode_GROUP_RWX = 0070, // group has read, write, and execute permissions
    PBFileMode_OTHER_R = 0004,   // others have read permission
    PBFileMode_OTHER_W = 0002,   // others have write permission
    PBFileMode_OTHER_X = 0001,   // others have execute permission
    PBFileMode_OTHER_RW = 0006,  // others have read and write execute permissions
    PBFileMode_OTHER_RWX = 0007, // others have read, write, and execute permissions
};

PBFileOpenFlags

typedef u32 PBFileOpenFlags;

PBFileOpenFlags changes behavior of PBFileOpen

PBFileOpenFlag

typedef enum PB_ENUM_TYPE(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_TRUNCATE = PBSysFileOpenFlag_TRUNCATE,   // truncate to length 0
    PBFileOpen_EXCLUSIVE = PBSysFileOpenFlag_EXCLUSIVE, // fail if file exists
    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_RW = PBSysFileOpenFlag_MODE_USER_RW,   // user has r+w permissions
    PBFileOpen_MODE_USER_RWX = PBSysFileOpenFlag_MODE_USER_RWX, // user has r+w+x permissions

    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_RW = PBSysFileOpenFlag_MODE_GROUP_RW,   // group has r+w permissions
    PBFileOpen_MODE_GROUP_RWX = PBSysFileOpenFlag_MODE_GROUP_RWX, // group has r+w+x permissions

    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_RW = PBSysFileOpenFlag_MODE_OTHER_RW,   // others have r+w permissions
    PBFileOpen_MODE_OTHER_RWX = PBSysFileOpenFlag_MODE_OTHER_RWX, // others have r+w+x permissions

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

PBFileSystemRoot

PBFile PBFileSystemRoot();

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

PBFileOpen

PBSysErr PBFileOpen(PBFile*         result,
                    PBFile          at,
                    PBStrSlice      path,
                    PBFileOpenFlags flags);

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

PBFileCreate

PBSysErr PBFileCreate(PBFile*    result,
                      PBFile     at,
                      PBStrSlice path,
                      PBFileMode mode);

PBFileCreate creates a new file, failing if one exists. It's a convenience function over PBFileOpen with PBFileOpen_WRITE | PBFileOpen_CREATE | PBFileOpen_EXCLUSIVE added to flags along with mode

• Returns: PBSysErr_EXISTS if file already exists

PBFileCreateOrTruncate

PBSysErr PBFileCreateOrTruncate(PBFile*    result,
                                PBFile     at,
                                PBStrSlice path,
                                PBFileMode mode);

PBFileCreateOrTruncate creates a new file, or truncates an existing one to length 0. It's a convenience function over PBFileOpen with PBFileOpen_WRITE | PBFileOpen_CREATE | PBFileOpen_TRUNCATE added to flags along with mode

PBFileOpenOrPanic

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

PBFileOpenOrPanic works like PBFileOpen but panics on error

PBFileCreateOrPanic

PBFile PBFileCreateOrPanic(PBFile     at,
                           PBStrSlice path,
                           PBFileMode mode);

PBFileCreateOrPanic works like PBFileCreate but panics on error

PBFileCreateOrTruncateOrPanic

PBFile PBFileCreateOrTruncateOrPanic(PBFile     at,
                                     PBStrSlice path,
                                     PBFileMode mode);

PBFileCreateOrTruncateOrPanic works like PBFileCreateOrTruncate 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

PBFileModeOfFlags

PBFileMode PBFileModeOfFlags(PBFileOpenFlags flags);

PBFileModeOfFlags extracts mode from flags

PBFileOpenFlagsOfMode

PBFileOpenFlags PBFileOpenFlagsOfMode(PBFileMode mode);

PBFileOpenFlagsOfMode creates flags with PBFileOpen_MODE_ bits set

---

#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