diff options
Diffstat (limited to 'docs/fs.md')
| -rw-r--r-- | docs/fs.md | 40 |
1 files changed, 28 insertions, 12 deletions
@@ -79,19 +79,32 @@ Existing Plan9port/v9fs clients need a userspace bridge for QUIC. /log one line per editor event: new|del|rename|save <serial> <name>; reads park /screen rendered screen JSON; frozen per open handle /listeners the session's dial addresses -/pane/ create a directory here to open a pane; remove one to close it +/pane/new open it to make a pane; the read answers that pane's serial /pane/<n>/ name body tag ctl addr dot limit data xdata sel dirty mark scroll errors event look exec, plus pty/{ctl,status,data} on terminals /os/ the host filesystem /src/ the editor's embedded sources, only when built with -Dembed-sources=true ``` -Nothing in the tree is created by list, stat, walk or read. A pane is opened -by Tcreate in `/pane` (`mkdir`) and closed by Tremove on `/pane/<n>` (`rmdir`), -which is the only create and the only remove the tree serves. The name a -create asks for is ignored, since a pane is named by the serial the editor -gives it: the Rcreate qid names the new directory, and because `/index` is -ordered by serial its last line is the pane just made. +A pane is made by **opening** `/pane/new`, and closed by Tremove on +`/pane/<n>` (`rmdir`), which is the only remove the tree serves; Tcreate is +refused everywhere, as it is in acme. Reading the open fid answers the serial +of the pane that open made, so `n=$(cat /pane/new)` makes one and names it in +a line. Each open makes another pane, and two reads of one fid answer the same +serial: the open acted, the read only observes. Closing the fid leaves the +pane. + +This is `/net/tcp/clone`'s mechanism, not acme's `new`, and the difference is +deliberate. acme allocates during the *walk* and lets the walk land inside the +new window, so `/dev/new/body` works in one step (acme(4): "accessing any file +in `new` creates a new window"). acme can also afford to list `new`, because a +Plan 9 directory read carries the stat of every entry and nothing walks. A +kernel or FUSE mount is not so lucky: it walks and stats each name a listing +gave it, so an allocate-on-walk name would make a pane per `ls -l`. Allocating +on open instead keeps `new` listed and `ls` honest — a stat is not an open — +at the cost of acme's one-step `new/body`. Nothing in the tree is created by +list, stat, walk or read; only that one open. Every other name in `/pane` is a +serial. `/look` and `/exec` are the editor's two clicks, one per line of a write: @@ -130,6 +143,9 @@ address expression (`#0,#5`, `/pattern/`, `2+1`); `addr` selects what `data` and `xdata` read or replace, `dot` is the editor's own selection and moving it scrolls the pane into view, and `limit` bounds a search and reads empty until it is set. Truncating a range file empties it; truncating `limit` lifts it. +`addr` belongs to the pane rather than to a client and keeps what was written +until someone writes or truncates it, so writing an address and reading it +back evaluates it, which is what acme(4) promises of its own `addr`. The three flag files `dirty`, `mark` and `scroll` read `0` or `1` and take `0` or `1`: whether the buffer differs from its file, whether a write pushes @@ -164,8 +180,8 @@ enables the option by default, so the device can serve its own source. This is a control filesystem, not a complete POSIX export. Native filenames may contain up to 255 bytes. Existing regular OS files support read, write, and truncation to zero; under `/os` protocol create, remove, rename and other -metadata changes are refused, as is every create and remove in the control -tree but the pane directories. Ownership and permissions under `/os` are +metadata changes are refused, as is every create in the control tree and every +remove in it but a pane directory's. Ownership and permissions under `/os` are synthetic. Zero-length truncation accepts the accompanying `mtime` hint sent by Linux v9fs; the hint is not stored. Standalone timestamp changes remain refused. @@ -180,9 +196,9 @@ for Unix and TCP, a poll loop for QUIC, and the 9P client for mounts); `src/fs.zig` keeps host access, mounts, resolution, find and grep. `zig build fs-test` drives real sessions using the independent Python client -in `test/ninep.py`; `zig build fs-discovery-test` checks that browsing creates -nothing, that a pane create and remove work, and that `look`, `exec`, `name`, -`sel` and `log` behave. `zig build +in `test/ninep.py`; `zig build fs-discovery-test` checks that browsing +creates nothing, that the walk to `/pane/new` and a remove work, and that +`look`, `exec`, `name`, `sel` and `log` behave. `zig build 9p-test` checks the two engine configurations' budgets (the engine's own tests are cloud9's `zig build test`); `zig build fs-bench` measures filesystem transactions in the core. |