# Harlock termios NIF
`termios.c` is the only piece of C in Harlock. It exists because the
BEAM cannot interact with the controlling terminal through `:os.cmd`,
`Port.open({:spawn, ...})`, or — surprisingly — spawn-based
`:file.read("/dev/tty")`. This README is the design rationale; future
maintainers debugging tty-leak issues or porting to a new platform
should read it first.
## Why a NIF at all
Three separate problems with `:os.cmd` and Port-based approaches:
1. **Controlling-tty loss.** `:os.cmd` and `Port.open({:spawn_executable,
...})` route through ERTS's `erl_child_setup`, which `setsid()`s
child processes so killing them doesn't take down the BEAM. But
`setsid()` detaches the child from the controlling terminal, so
opening `/dev/tty` in the subshell returns ENXIO ("Device not
configured"). Every `stty ... </dev/tty` call from inside BEAM
silently fails.
2. **Spawn-based reads don't deliver bytes.** Verified empirically on
macOS / OTP 28: `:file.open("/dev/tty", [:read, :raw, :binary])` from
a spawned Erlang process opens successfully but `:file.read` never
returns, even when the terminal is in raw mode and no other reader
is active. Reads from the script's main process work. Cause
undetermined — possibly something in ERTS's async-thread plumbing
that's sensitive to which Erlang process initiated the call.
Workaround would be "do all tty reads in the main script process,"
which is incompatible with running under a supervisor.
3. **`Port.open({:fd, 0, 1}, ...)` on stdin** works only without
`-noinput` and only by stealing fd 0 from BEAM's built-in
`prim_tty:tty` driver. Brittle, racy against `user_drv`, and breaks
if stdin is redirected.
A NIF doing `tcgetattr` / `tcsetattr` / `ioctl(TIOCGWINSZ)` / `read(2)`
directly bypasses all of these. The fd is opened from inside the BEAM
process, so it retains the controlling terminal; the syscalls run in
the calling thread, so they reach the kernel reliably regardless of
which Erlang process invoked them.
## Public API
| NIF | Purpose |
| ---------------------------- | ------------------------------------------------ |
| `open/0` | open `/dev/tty` (O_RDWR \| O_NOCTTY \| O_NONBLOCK), returns resource |
| `close/1` | `SELECT_STOP` + close (via stop callback) |
| `get/1` / `set/2` | `tcgetattr` / `tcsetattr` — termios snapshot+restore |
| `set_raw/1` | `cfmakeraw` + VMIN=1, VTIME=0 |
| `winsize/1` | `ioctl(TIOCGWINSZ)` |
| `arm_select/1` | `enif_select_read` — get `{:tty_ready, ref}` on data |
| `read_nonblock/2` | `read(2)` with EAGAIN → `:wouldblock`, 0 → `:eof` |
All NIFs run on dirty I/O schedulers except `arm_select`, which must
run on a normal scheduler so `enif_select_read` correctly identifies
the caller as the notification target.
## Resource lifecycle
```
Termios.open()
→ fd = open("/dev/tty", O_RDWR|O_NOCTTY|O_NONBLOCK)
→ resource holds {fd, owner_pid}
→ owner_pid set to enif_self() at open time
Termios.arm_select(ref)
→ enif_select_read(fd, resource, msg)
→ BEAM holds a ref to the resource; resource stays alive until select
is stopped
(data available)
→ BEAM delivers msg = {:tty_ready, ref} to owner_pid
Termios.read_nonblock(ref, n)
→ read(2) into a binary
→ owner check: only the process that called open/0 may read
Termios.close(ref)
→ enif_select(SELECT_STOP)
→ resource.fd = -1 immediately (no more reads)
→ BEAM eventually invokes the stop callback on a scheduler thread
→ stop callback calls close(2) on the original fd
→ after stop completes, resource refcount drops, destructor runs
```
The destructor is idempotent: if `close/1` was called explicitly,
`resource.fd` is already `-1` and the destructor is a no-op. If the
resource is GC'd without an explicit close (e.g., process crashed),
the destructor itself calls `SELECT_STOP`, and BEAM defers the actual
free until the stop callback completes.
**Never `close(fd)` directly outside the stop callback.** Doing so
while the fd is still registered with `enif_select` is a use-after-free
in the BEAM IO poller and produces crashes that look entirely
unrelated.
## Why `enif_select_read` and not blocking `read(2)` in a dirty NIF
A blocking `read(2)` in a dirty I/O NIF technically works but it:
- Pins a dirty I/O scheduler thread for the lifetime of the read.
Multiple apps would exhaust the pool.
- Can't be interrupted cleanly for shutdown. `tcsetattr` from another
thread doesn't unblock `read` on all platforms.
- Ties shutdown sequencing to OS thread scheduling, which is
platform-specific and unreliable.
`enif_select_read` registers the fd with the BEAM poller (kqueue on
macOS, epoll on Linux). The thread doing the wait is shared across all
fds the BEAM knows about. When data arrives, BEAM sends a message to
the registered process; the Erlang code does a non-blocking `read(2)`
and re-arms. This is the same path BEAM's built-in drivers use.
## Owner-pid check
Each NIF that touches the fd verifies the calling process is the one
that opened it:
```c
ErlNifPid caller;
enif_self(env, &caller);
if (enif_compare_pids(&caller, &tty->owner) != 0) {
return {:error, :not_owner};
}
```
This isn't security — it's a footgun guard. Two Erlang processes
trying to drive one tty fd would race for messages and produce
silently-corrupted input streams. The check makes the misuse
fail-fast.
## Caveats and known limitations
- **Single-reader constraint.** Only one Harlock app per BEAM can
usefully own `/dev/tty`. `Harlock.run/3` doesn't enforce this yet —
v0.3 should detect and refuse.
- **Non-tty environments.** `Termios.open/0` returns
`{:error, :no_tty}` when `/dev/tty` is unavailable (CI, piped stdin).
Keeper surfaces this to stderr and halts the supervisor cleanly.
- **EOF handling.** A `read(2)` returning 0 means the terminal was
closed (ssh disconnect, tmux kill-window). The Reader surfaces this
as `{:harlock_event, {:harlock_tty_lost, :eof}}` to the runtime and
terminates; the supervisor's `rest_for_one` then takes down the
rest of the tree and Keeper's `terminate/2` restores termios before
the BEAM exits.
## Building
The Makefile is driven by `elixir_make`. CFLAGS include the ERTS
headers; on macOS, LDFLAGS add `-undefined dynamic_lookup
-flat_namespace` for the shared-library symbol resolution that the
BEAM expects.
The whole file is ~250 LOC of standard POSIX. No third-party
dependencies, no `#ifdef` gymnastics — `tcgetattr` / `tcsetattr` /
`ioctl(TIOCGWINSZ)` / `read(2)` are stable since the 1980s and behave
the same on macOS, Linux, and BSD.
## Verifying hostile conditions
The automated test suite covers the non-tty path (`Termios.open/0`
returns `{:error, :no_tty}` cleanly). Everything else requires a real
terminal and gets verified manually. Walk through these any time you
touch the NIF, the Reader, or the Keeper:
1. **Clean quit.** Run `./scripts/run.sh contacts`. Press Tab to verify
focus cycling. Press `q` (or Ctrl+C). Confirm: the terminal returns
to a usable shell prompt with echo working — no need to `stty sane`
manually.
2. **Crash mid-session.** While the demo is running, in another shell
tab: `pkill -9 beam.smp` (targeting the demo's PID, not other
BEAMs). The terminal will be left in raw mode because no graceful
shutdown ran. Confirm: `stty sane` from that terminal restores
it — i.e., the kernel-level state is still well-formed and not
corrupted.
3. **Terminal close (EOF).** Run the demo, then close the terminal
window directly (Cmd+W). The `read(2)` returns 0; Reader sends
`{:harlock_tty_lost, :eof}` and stops; supervisor tears down the
tree. No orphaned BEAM processes — verify with `pgrep beam.smp`.
4. **Resize.** Run the demo, drag the window edge to change size.
SIGWINCH fires, Keeper queries TIOCGWINSZ via the NIF, sends
`{:harlock_resize, rows, cols}` to the runtime, and the next frame
redraws at the new size.
If any of these fail, the failure is the bug. Don't ship workarounds
in the demo — fix it in the framework.
