.TH FILE 2
.SH NAME
    open, read, getsize, close, readdir - file I/O system calls

.SH SYNOPSIS
.BI     int montauk::open(const char* path);
.BI     int montauk::read(int handle, uint8_t* buf, uint64_t offset, uint64_t size);
.BI     uint64_t montauk::getsize(int handle);
.BI     void montauk::close(int handle);
.BI     int montauk::readdir(const char* path, const char** names, int max);

.SH DESCRIPTION
    MontaukOS 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.

.SS 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 = montauk::open("0:/os/hello.elf");

.SS 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 = montauk::read(h, buf, 0, 512);

.SS getsize
    Returns the total size in bytes of the file.

        uint64_t sz = montauk::getsize(h);

.SS close
    Closes the file handle and frees kernel resources.

        montauk::close(h);

.SS 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 = montauk::readdir("0:/", entries, 64);
        // entries: "os/", "games/", "man/", "www/", "home/"

.SH READING PATTERN
    The standard pattern for reading a file:

        int h = montauk::open("0:/man/intro.1");
        uint64_t size = montauk::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 = montauk::read(h, buf, off, chunk);
            if (n <= 0) break;
            buf[n] = '\0';
            montauk::print((const char*)buf);
            off += n;
        }
        montauk::close(h);

.SH WRITING FILES
    Files can be created and written on the ramdisk:

.BI     int montauk::fcreate(const char* path);
.BI     int montauk::fwrite(int handle, const uint8_t* buf, uint64_t offset, uint64_t size);

    fcreate creates a new file and returns a handle. fwrite writes
    bytes at the given offset. Changes persist only until reboot --
    the ramdisk is reloaded from the USTAR archive on each boot.

.SH NOTES
    All files live on the ramdisk which is loaded at boot from a
    USTAR tar archive.

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