ttyproxy

Documentation

Overview

Package ttyproxy is the in-process TTY proxy that wraps `podman run` so ^Z suspends the PROXY (not the container), SIGWINCH resizes propagate, and window-close/SIGTERM tear the jail down cleanly. All signal teardown stays in one process.

Frozen behavior (from docs/design/ctrl-z-and-the-tty-proxy.md):

• non-TTY stdin -> transparent plain spawn (no pty).
• ^Z (0x1A) suspends the PROXY via TARGETED SIGTSTP to self (NEVER a pgroup-wide signal — that would stop podman, a jail-visible change); the byte never reaches the child; bytes after ^Z in the same read are queued and flushed on resume.
• NO Setsid (setsid broke `podman -it`); NEVER signal.Notify(SIGTSTP) (default disposition required to actually stop).
• SIGCONT -> re-raw the host TTY. SIGWINCH -> TIOCSWINSZ to the pty.
• SIGHUP/SIGTERM -> restore cooked termios, run onTerminate, exit 128+n.
• stdin EOF -> stop reading stdin, keep pumping the master until child exit (the decided semantics).

Index

• func RunWithProxy(cmd []string, onStarted func(*os.Process), onTerminate func()) (int, error)

Functions

func RunWithProxy

func RunWithProxy(cmd []string, onStarted func(*os.Process), onTerminate func()) (int, error)

RunWithProxy spawns cmd under a TTY proxy and returns its exit code.

• onStarted (if non-nil) runs on a goroutine after spawn (post-launch housekeeping, e.g. release a lock) without blocking the pump loop.
• onTerminate (if non-nil) is host-side teardown run when the proxy is KILLED (SIGHUP window-close / SIGTERM) rather than exiting on its own.

Non-TTY stdin falls back to a plain spawn (no pty), matching Python.