.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 Virtual File System (VFS) with read/write
    support. Drive 0 is the boot ramdisk; additional drives may be
    mounted from GPT partitions backed by FAT32 or ext2 (see
    syscalls(2), STORAGE section). Files are accessed via paths in
    the format "<drive>:/<path>".

.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 (VFS cap
    256, driver-backed listings such as 0:/os/ cap 128) 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/", "apps/", "man/", "www/", "users/", ...

    For directories that may contain more entries than fit in one
    call, use montauk::readdir_at(path, names, max, startIndex) and
    advance startIndex by the returned count until it returns 0.

.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, DELETING, RENAMING
.BI     int montauk::fcreate(const char* path);
.BI     int montauk::fwrite(int handle, const uint8_t* buf, uint64_t offset, uint64_t size);
.BI     int montauk::fdelete(const char* path);
.BI     int montauk::fmkdir(const char* path);
.BI     int montauk::frename(const char* oldPath, const char* newPath);

    fcreate creates a new file and returns a handle. fwrite writes
    bytes at the given offset. fdelete removes a file, fmkdir
    creates a directory, and frename renames or moves a file or
    directory (the basis for file manager move operations).

    On drive 0 (the ramdisk), changes persist only until reboot --
    the ramdisk is reloaded from the USTAR archive on each boot. On
    disk-backed drives (FAT32/ext2 partitions mounted with
    montauk::fs_mount), changes are written through to storage; use
    montauk::fs_sync() to flush caches before power-off.

.SH NOTES
    Drive 0 is loaded at boot from a USTAR tar archive into RAM.
    Other drives are mounted on demand from GPT partitions on
    SATA/NVMe/USB block devices; see syscalls(2), STORAGE and
    DEVICES sections.

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