# file(2)

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

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

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

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

    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)

Back to Documentation Index