FILE(2)

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

SYNOPSIS
intmontauk::open(constchar*path); intmontauk::read(inthandle,uint8_t*buf,uint64_toffset,uint64_tsize); uint64_tmontauk::getsize(inthandle); voidmontauk::close(inthandle); intmontauk::readdir(constchar*path,constchar**names,intmax);

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>".

  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");

  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);

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

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

  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.

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] = ' ';
            montauk::print((const char*)buf);
            off += n;
        }
        montauk::close(h);

WRITING, DELETING, RENAMING
intmontauk::fcreate(constchar*path); intmontauk::fwrite(inthandle,constuint8_t*buf,uint64_toffset,uint64_tsize); intmontauk::fdelete(constchar*path); intmontauk::fmkdir(constchar*path); intmontauk::frename(constchar*oldPath,constchar*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.

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.

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