Expand description
files: the real filesystem, confined to a directory the host chose.
The Language Card names files first among the operations that are typed
Host APIs rather than ambient authority. crate::host::Documents is a
narrower thing: a read-only view over a fixed set of .txt documents, so
a program that only reads its inputs never has to be handed a filesystem.
This module is the filesystem itself — reading, writing, listing, and
removing — and it is a separate capability precisely because it is the
wider one.
Granting files must not hand over the machine, so the real
implementation is rooted: Files::rooted takes the one directory a run
may reach, and every path is checked against it twice. The lexical check
refuses an absolute path, a .. component, and a backslash, none of which
can name a place inside the root. The second check follows symbolic links,
because a path made only of ordinary components can still leave the root
through one. Files::in_memory is the fake: the same paths are refused
for the same reasons, so a test written against it exercises the rules the
real filesystem enforces.
Paths are always relative to the root and always /-separated. . names
the root itself, which is how list(".") asks what a run can see.
read and write move a whole file. open and create move one a line
at a time instead, through the two resource kinds ADR 0018 added: a
files.Reader answers lines until there are none left, a files.Writer
takes them, and each is a position in a file, which is why neither may
cross a task boundary. Both are reached through the same files
capability and both go through the same path checks, so a handle cannot
name a place the root does not contain.