File services

Routine summary

file_open

file_open
R0 = ASCIIZ path; R1 = 1 read / 2 replace; R2 = final length for replacement

Only PID 0/3 may open regular MKS2 files. Paths are at most 95 bytes, components at most 12. Length is 0–64256 bytes subject to space. Two handles exist; only one writer may be open. A replacement reserves a new extent and does not publish the file until successful close.

file_read

file_read
R0 = handle; R1 = RAM buffer of at least 256 bytes

Reads the next sector; zero bytes means EOF on success. The full buffer capacity is required even for a short final sector. The running checksum counts only valid file bytes. At EOF a checksum mismatch returns status 4 and zero bytes; earlier bytes may already have reached the caller.

file_write

file_write
R0 = handle; R1 = buffer; R2 = byte count

The count must be exactly min(256, remaining declared length), or zero after the length has been reached. The last sector is zero-padded outside its valid data; every write is reread and compared. There is no seek, append, arbitrary chunk-size API or implicit growth.

file_close

file_close
R0 = handle

Closes a valid handle even if commit fails. A complete, error-free writer publishes to the inactive metadata generation; an incomplete writer fails and preserves the former file. Closing a reader before EOF does not force checksum validation of unread content. A reader at EOF includes validation of the empty-file case.

file_abort

file_abort
R0 = handle

Releases an owned handle without publishing data or metadata. Use it for failed or interrupted output. Unpublished extents become allocatable when no generation or reader references them.

Ownership, buffer lifetime and publication

All operations check handle ownership; opens reject background PID 1/2. The file routines do not yield internally. A caller may yield between sectors, while retaining its pathname, handle and application-local state.

The shared TMP/COPYBUF for this build is 0x2C40–0x2D3F. Do not keep sector contents there across other calls that read metadata, paths or ROM resources. FILE_WRITE supports this scratch buffer as its source by preserving valid bytes before padding.

Both valid metadata generations and open readers protect referenced extents from allocation. Only close publishes a complete writer. A writer blocks other mutations; formatting/unmounting a volume with open handles is rejected. Preserve the original failure code while aborting other handles.

File descriptor

Two 40-byte records begin at 0x06A0 and 0x06C8. This internal layout is not an independently stable ABI.