103 lines
3.7 KiB
Plaintext
103 lines
3.7 KiB
Plaintext
.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)
|