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. --- examples/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'examples') diff --git a/examples/README.md b/examples/README.md index 6112a696..aaaf5920 100644 --- a/examples/README.md +++ b/examples/README.md @@ -56,6 +56,8 @@ lines. new/ dir looking up ANY name here creates a pane / dir one per pane; id is the pane serial, never reused addr body ctl data errors event rdsel tag wrsel xdata + pty/ dir TERMINAL PANES ONLY; absent on a pane with a document + ctl status data ``` | file | mode | semantics | @@ -73,12 +75,26 @@ lines. | `rdsel` | r | the pane's current selection. | | `wrsel` | w | replaces the pane's current selection. | | `event` | rw | the pane's action stream, both directions. See below. | +| `pty/` | dir | present only when the pane is a terminal, so `test -d $PARDES_FS//pty` is how a script asks. Absent — not empty — on a file pane, and every file under it answers ENOENT there. | +| `pty/ctl` | w | newline separated verbs, several per write, applied all or nothing: `winsize `, `sig INT\|TERM\|HUP\|QUIT\|KILL`, `exec`. Anything else is EINVAL and applies nothing. | +| `pty/status` | r | three `%11d` fields: columns, rows, and 1 while a program (vim, a pager, a build) holds the tty rather than the shell prompt. Seekable. | +| `pty/data` | rw | the raw stream. A write is input to the program, offset ignored, short at a character boundary. A read hands back as much of the pending output as the count allows and keeps the rest — raw bytes have no records, so unlike `event` a small read is served rather than refused — and blocks while there is nothing. Output is only recorded while the file is OPEN. | `ctl` verbs: `addr=dot`, `clean`, `dirty`, `cleartag`, `del`, `delete`, `dot=addr`, `get`, `limit=addr`, `mark`, `nomark`, `name `, `noscroll`, `scroll`, `put`, `show`. An unknown verb fails the whole write with EINVAL and applies nothing, so a batch is safe to send blind. +`pty/ctl` verbs in detail. `winsize` is `TIOCSWINSZ` and nothing more: it tells +the program a size and does not move the pane, whose grid is its rectangle on +screen, so the next time you drag that pane the layout's size wins again. +`sig` goes to the tty's foreground process group — what ^C would reach — and +not to the shell, which ignores SIGINT while it waits for a job. `exec` +respawns the pane's configured shell in the pane's own directory and takes NO +argument: `exec /bin/sh` is EINVAL rather than an argument silently dropped. +`raw` and `cooked` do not exist, because the termios belongs to the program on +the far side of the pty and it never tells us. + Addresses, all in bytes: `#n` an offset, `n` a line, `0` the start, `$` the end, `.` the selection, `a,b` a range (`,` alone is the whole body), `+` and `-` with a count or a regex, `/re/` forwards, `?re?` backwards. Anything else -- cgit v1.3