ghostty-rs/docs/rewrite/notes/ghostty-termio-IO1.md

ghostty-termio notes (agent IO1)

Linux only. Crate lints: unsafe_code = "deny" (workspace clippy table copied into the crate's [lints.clippy]); #[allow(unsafe_code)] only on tiny items with // SAFETY: (fork, execvpe, _exit, close, sigaction, borrow_raw).

File -> module

• pty.zig -> pty.rs (Pty, Winsize, Mode, child_pre_exec(master, slave))
• Command.zig (+ apprt/gtk/{pre_exec,post_fork}.zig cgroup logic, cgroup.zig fmtScope) -> command.rs
• termio/shell_integration.zig -> shell_integration.rs
• terminfo/{main,Source,ghostty}.zig -> terminfo/{mod,source,ghostty}.rs (terminfo::ghostty is a const Source; encode, encode_to_string, xtgettcap_map). Output verified byte-identical with the Zig encode (golden file tests/data/xterm-ghostty.terminfo, generated with zig run).
• Shell scripts copied verbatim to resources/shell-integration/ (workspace root).

Not ported (deferred; need ghostty-terminal / renderer)

Exec.zig, Termio.zig, Thread.zig, stream_handler.zig, mailbox.zig, message.zig, backend.zig, Options.zig (all reference terminal/renderer/apprt types).

Design / deviations

• Deps ghostty-config and ghostty-terminal REMOVED from Cargo.toml (note in file). Deps: ghostty-os, rustix (pty, termios, process, fs, stdio), nix (signal), libc, log, thiserror.
• Command does its own fork + libc::execvpe (not std::process::Command) so the child setup is exactly Ghostty's: dup2 stdio (CLOEXEC cleared), best-effort chdir (failure ignored), restore rlimit (restore_rlimit: Option<Rlimit> replaces global_state.rlimits), os_pre_exec then rt_pre_exec hooks (Fn() -> Option<u8>, Some(code) => _exit(code); panics => exit 1), then execvpe. All allocation happens before fork. Exec failure: child prints the same "Requested executable not found" message (other errors: errno=N instead of the Zig error name) to stderr and _exit(1); there is no ExecFailedInChild error because the child can never return into caller code. exit_immediately(code) is provided for hooks that want to exit (use instead of std::process::exit).
• Signal mask: Zig never reset the mask explicitly in Command either; only Pty::child_pre_exec resets 13 signal dispositions to SIG_DFL (same list as Zig), then setsid + TIOCSCTTY and closes slave+master. Close-all-fds is not done (Zig doesn't either; master is CLOEXEC).
• stdio fields are Option<OwnedFd> (callers pass try_clone()d fds); wait(block) returns Result<Exit, Errno>; non-blocking wait loops until a status is available (as Zig, with a yield_now). setData/getData dropped (closures capture state). Empty args => argv = [path] (what the Zig doc comment promises; Zig code itself passed an empty argv).
• Inherited env is snapshotted with vars_os() before fork (Zig passes environ).
• Pty: slave: Option<OwnedFd>; both fds close on drop (Zig never auto-closed the slave). Master opened CLOEXEC, slave not (like glibc openpty + explicit CLOEXEC). IUTF8 set.
• cgroup: linux_cgroup_pre_exec(&RtPreExecInfo) (child side, waits <=250ms) and linux_cgroup_post_fork(cmd, &RtPostForkInfo, create_scope) where create_scope is a closure standing in for the GIO D-Bus cgroup.createScope. fmt_scope(pid). Local LinuxCgroup/GtkSingleInstance/Rt*Info types: TODO(integration) from ghostty-config.
• shell_integration: local Command (Shell/Direct) with ArgIteratorGeneral quoting rules, ShellIntegrationFeatures (same defaults) - TODO(integration) replace with config types. EnvMap = HashMap<String,String>. setup(resource_dir, &Command, &mut EnvMap, Option<Shell>) -> Result<Option<ShellIntegration>, Error> (Error only from homedir::home). Darwin /bin/bash special case dropped.

Tests (52 total: 47 unit + 5 integration, all passing)

Zig tests ported (35): pty 1; Command 10 (createNullDelimitedEnvMap as prepare(), os/rt pre exec 1+2, rt post fork, redirect stdout, custom env, custom cwd, execve failure); shell_integration 21 (force shell, failure, detectShell, setup features, bash x8, xdg x3, nushell x3, zsh x3); terminfo 3 (xtgettcap map, Source encode, ghostty encode). Skipped: Windows/NullPty/Windows env block helpers, refAllDecls tests. Extras: pty cloexec/IUTF8/mode, Exit decoding, signal exit, nonblocking wait, invalid cwd ignored, fd leak check, cgroup mode matrices, arg splitter, bundled-resources check, terminfo golden vs Zig, tic -x compile of the generated source (skipped if tic absent), tests/pty_command.rs: real /bin/sh -c 'echo hi; stty size' on a 31x97 pty (output hi\r\n31 97\r\n), controlling-tty check, resize check.

Known gaps / TODO(integration)

• Config-derived types above; restore_rlimit from global state; D-Bus scope creation.
• Pty::child_pre_exec is meant to be called from Exec's os_pre_exec (see tests/pty_command.rs for the wiring). Flatpak passwd path in ghostty-os needs Pty (ghostty-os TODO) - now available.
• Hooks run after fork in a possibly multithreaded process; linux_cgroup_pre_exec allocates and sleeps (same as Zig) - fine on glibc.