Repository navigation
0.18.0 --- openkal.map: a part of a file's contents in the address space - #55
Merged
Merged
Conversation
An optional interface of three operations and one constant (clause 11 entry 40, design .agents/docs/2026-10-31-file-mapping-design.md). kal_map_file maps a part of an open file, read or written, private or shared; kal_map_sync makes a shared region's writes visible to reads of the file; kal_map_release releases it. Its own interface, because an environment can keep files and be unable to map them (clause 6.2). The region is an address and a length, as an allocation is, because a handle would oblige a table (clause 7.1). An offset is a multiple of KAL_MAP_ALIGNMENT, 64 KiB, because a file is laid out for mapping by a program that does not know where it will be mapped. No region of a file is executable. A file shortened beneath a region refuses the shortening or faults beyond its new end, and never reads zero in place of what was removed. The conformance suite examines it (feature map, in optional): bytes, the last page, a private and a shared write, the refusals, and the shortened file in a started copy. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
This was referenced Oct 30, 2026
…al_interfaces; the shortened-file copy's status is reported An implementation's provides-interfaces is derived from its objects in the order of SURFACE.txt, and an interface added in 0.18 follows those before it. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
…ds zero, whichever the environment does; never the removed bytes Measured on macOS: a private region's page beyond a shortened file's new end reads zero, where Linux faults and Windows refuses the shortening. Requiring one outcome would oblige an implementation to keep a registry of mapped files (clause 7.1), so the three are the environment's and none is reported in advance; what holds everywhere is that no access reads the removed bytes. The conformance copy fills the file with 0xA5 first, so a stale page is told from zero, and reports which step failed. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
… region may keep what it showed Measured on macOS: a private region read the removed bytes after its file was shortened, as it may for any change to its file (map.h: whether a change appears in a private region is not specified). The three outcomes and the rule that no access reads removed bytes are a shared region's; the conformance copy maps shared and reports a failed open with its error. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
… the map errand's file is made and then removed; the errand releases its region first Under wine started by binfmt the program is named by its full path, which resolves against the volume's root; the copy then ran there and could not create its file (status 106, kal_err_permission). The suite removed the file from its own directory, so a copy elsewhere also left it behind. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
An optional interface of three operations and one constant (clause 11 entry 40; design
.agents/docs/2026-10-31-file-mapping-design.md).kal_map_file(file, offset, length, how, out): read or written (KAL_MAP_WRITE), private or shared (KAL_MAP_SHARED);offseta multiple ofKAL_MAP_ALIGNMENT(64 KiB); never beyond the file's end.kal_map_sync(region, length): a shared region's writes visible to reads of the file.kal_map_release(region, length).Its own interface (clause 6.2), no handle (clause 7.1), a constant alignment (a file is laid out where it will not be mapped), no executable region (W^X stays with
openkal.exec). A file shortened beneath a region refuses or faults; never zero in place of what was removed.Conformance: section
map(featuremap, inoptional), held on Linux (gcc) and Windows (wine) locally. Implementations: openkal-linux 0.19.0, openkal-macos 0.16.0, openkal-windows 0.14.0 on the same branch name.Context: mcpp ecosystem design 2026-10-30 part 2 §23.2, §25 (mcppls-clangd#12: clangd as an ok image).
Co-authored-by: speak-agent 248744407+speak-agent@users.noreply.github.com