FILE(2)

NAME
    open, read, getsize, close, readdir - file I/O system calls

SYNOPSIS
intzenith::open(constchar*path); intzenith::read(inthandle,uint8_t*buf,uint64_toffset,uint64_tsize); uint64_tzenith::getsize(inthandle); voidzenith::close(inthandle); intzenith::readdir(constchar*path,constchar**names,intmax);

DESCRIPTION
    ZenithOS provides a simple read-only Virtual File System (VFS)
    backed by the boot ramdisk. Files are accessed via paths in the
    format "<drive>:/<path>", where drive 0 is the ramdisk.

  open
    Opens a file and returns a non-negative handle on success, or a
    negative value on error (file not found, no free handles).
        int h = zenith::open("0:/os/hello.elf");

  read
    Reads up to 'size' bytes starting at 'offset' into 'buf'.
    Returns the number of bytes actually read, or negative on error.
    There is no implicit file position -- the offset is explicit on
    every call.
        uint8_t buf[512];
        int n = zenith::read(h, buf, 0, 512);

  getsize
    Returns the total size in bytes of the file.
        uint64_t sz = zenith::getsize(h);

  close
    Closes the file handle and frees kernel resources.
        zenith::close(h);

  readdir
    Lists entries in a directory. Up to 'max' entry names (max 64)
    are written to the 'names' array. The kernel allocates a user-
    accessible page for the string data automatically. Directory
    entries are returned with a trailing slash.
        const char* entries[64];
        int count = zenith::readdir("0:/", entries, 64);
        // entries: "os/", "games/", "man/", "www/", "home/"

READING PATTERN
    The standard pattern for reading a file:
        int h = zenith::open("0:/man/intro.1");
        uint64_t size = zenith::getsize(h);
        uint8_t buf[512];
        uint64_t off = 0;
        while (off < size) {
            uint64_t chunk = size - off;
            if (chunk > 511) chunk = 511;
            int n = zenith::read(h, buf, off, chunk);
            if (n <= 0) break;
            buf[n] = ' ';
            zenith::print((const char*)buf);
            off += n;
        }
        zenith::close(h);

NOTES
    The filesystem is read-only. There are no write or create calls.
    All files live on the ramdisk which is loaded at boot from a
    USTAR tar archive.

SEE ALSO
    syscalls(2), spawn(2), malloc(3)