From 5f4719da21f06b58694d52d354f5fda431ff8543 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 27 Aug 2026 15:32:02 -0300 Subject: acmefs: a pane's terminal gets pty/data, pty/ctl and pty/status Step 3 of the 9P chain (docs/9p.typ 12.3, docs/registry.typ 9P-8). Nothing here is about 9P: it lands in the FUSE-served tree and any later transport inherits it. A script could write into a terminal that already existed and read its rendered scrollback. It could not START one, RESIZE one or SIGNAL one. Two of those were already effects the core emits, so `exec` and `winsize` are existing capabilities acquiring a name; only `sig` is new, and it brings the one new host method, `push_pty_signal`. pty/ctl winsize | sig INT|TERM|HUP|QUIT|KILL | exec one verb per line, validate-all then apply-all, EINVAL applies nothing -- `writeCtl`'s shape and `writeCtl`'s reason pty/status cols, rows, tty-taken as three %11d fields pty/data write is input to the process; read is the RAW output stream, gated on a reader count so a pane nobody reads costs one branch A pane that is not a terminal has no pty/ at all: the lookup is ENOENT and readdir does not list it. `PaneFile` is an enum(u4) and this takes it from 11 values to 15. ONE REMAINS. That is also why pty/ is a DIRECTORY and not three more flat names -- a subdirectory costs one value and buys its own namespace, so `ctl` and `data` did not have to be renamed. Two things the core does not know, and which are therefore not invented: a child's EXIT STATUS (a shell's death is `Event.eof`, which removes the pane, so there is no directory left to read it in) and RAW/COOKED (the core never sets a termios; the mode belongs to the program on the far side). Verified live against a daemon: pty/ appears only on the terminal pane; a `winsize 0 24` and a `sig SIGINT` are refused; a bad verb beside a good one applies neither; `echo pty-works` written to pty/data runs in the shell and its output reaches the body; and a blocking read of pty/data returns the raw stream, OSC 133 marks and all. fs-bench unchanged and still zero allocations. --- docs/acme-fs.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/acme-fs.md b/docs/acme-fs.md index 15f45c4f..25cbcc2d 100644 --- a/docs/acme-fs.md +++ b/docs/acme-fs.md @@ -3,7 +3,8 @@ `pardes --fs` serves plan9 [acme(4)](https://man.cat-v.org/plan_9/4/acme)'s control filesystem over Linux FUSE: a directory per pane, named by the pane's serial and holding `addr`, `body`, `ctl`, `data`, `errors`, `event`, `rdsel`, `tag`, `wrsel` -and `xdata`, plus `index`, `cons` and `new/` at the root (`PaneFile` and +and `xdata`, plus a `pty/` directory on a terminal pane, plus `index`, `cons` +and `new/` at the root (`PaneFile` and `TopFile` in `src/acmefs.zig`). A program that opens those files IS an editor extension — no plugin API, no embedded interpreter, no rebuild. `examples/acmefs/` has four of them: `clock.py`, `eventlog`, `life.py` and @@ -368,6 +369,59 @@ has no `log` either; it is a plan9port addition. No example needed it, and a script that wants to notice panes it did not open reads `index`, which is what acme gives it. +## What is served that acme does not have: `pty/` + +One directory, three files, and **no prior art anywhere**: acme has no terminals +and `ad` — the other editor that serves a control filesystem over 9P — has no +terminal surface at all (its tree is `{ctl, minibuffer, scratch, log, +buffers/…}`). So there is nobody's mistakes to learn from and nobody's scripts +to keep compatible, which is the argument for keeping it to three files and +stopping. + +A pty is a file interface wearing the wrong clothes: everything one wants to do +to it is an `ioctl`, and neither 9P nor FUSE has one. They become writes. + +| ioctl | here | +|---|---| +| `TIOCSWINSZ` | `winsize 80 24` → `pty/ctl` | +| `kill` | `sig INT` → `pty/ctl` | +| spawn | `exec` → `pty/ctl` | +| `TIOCGWINSZ` | read `pty/status` | +| `read`/`write` | `pty/data` | + +Two of the three verbs are effects the core already had — `push_spawn` and +`push_pty_resize` — so `exec` and `winsize` are existing capabilities acquiring +a name. `sig` is the one new host capability in the whole directory +(`push_pty_signal`, and there was no `kill` anywhere in `host_io.zig` before +it); it targets the tty's foreground process group rather than the shell's pid, +because an interactive shell ignores SIGINT while it waits for a job. + +The directory is **absent** on a pane that is not a terminal, rather than +present and refusing, so `test -d /pty` is how a script asks what kind of +pane it has. `pty/data`'s read is the only new state: the core keeps no raw pty +bytes anywhere (they go into the emulator grid, which is a rendering and cannot +be turned back into a stream), so they are queued as they arrive — gated on a +reader count exactly as `event` is, so a pane nobody is reading costs one +branch and no memory, and capped drop-oldest by the same `queue_cap`. Unlike +`event`, a read smaller than one arrival is SERVED and the remainder kept: raw +bytes have no record framing to split down the middle. + +Three things it deliberately does not have. There is no **exit status**, +because the core does not track one: a shell's death arrives as `Event.eof`, +whose whole handler is `removePane`, so by the time anyone could read a status +the directory is gone. There is no **`raw`/`cooked`**, because the termios +belongs to the program on the far side of the pty and it never reports one. And +`exec` takes **no argv**, because `Effect.spawn` carries a pane and a cwd and +has nowhere to put one — so `exec /bin/sh` is EINVAL rather than an argument +accepted and silently ignored. + +`Node.file` is a `u4`. These four variants (`pty`, `pty_ctl`, `pty_status`, +`pty_data`) take it to fifteen of sixteen used: **one value is left**, and the +next file added to a pane's directory needs a wider field and therefore a new +node-id layout. That is also why `pty/` is a directory rather than three more +names beside `body` — a subdirectory costs one value and buys a namespace, so +`ctl` and `data` did not have to be spelled twice. + ## Reading order `src/acmefs.zig` (semantics; start at its header), `src/fuse.zig` (the wire), -- cgit v1.3