tty

Terminals and pseudo-terminals for Crystal.

tty runs programs on a pseudo-terminal, scripts them, hands them to the user's terminal, and controls terminal modes, window sizes, sessions, and serial lines. The high-level API reads like Crystal's own Process and IO; underneath it sits a raw-syscall core with no libc wrappers, so every ioctl and flag is reachable when you need it.

require "tty"

output, status = TTY::PTY.run("ls", ["--color=auto"])

Contents

• Installation
• A quick tour
• Running programs
• Talking to a program
• Waiting, signals, and exit status
• Controlling a terminal
• Working with a PTY directly
• Descriptors and readiness
• Sessions and serial lines
• Conventions
• Concurrency
• Platform support
• API reference
• Development

Installation

Add the shard to shard.yml:

dependencies:
  tty:
    github: shpeckman/tty

Run shards install, then require "tty".

Requirements:

• Crystal 1.10 or newer
• x86-64
• Linux for the full feature set; macOS for the portable subset (see Platform support)

A quick tour

Capture what a program prints when it believes it is talking to a terminal:

output, status = TTY::PTY.run("git", ["log", "--oneline", "-5"])
status.success?

Script an interactive program. The block form cleans up when the block ends:

answer = TTY::PTY.spawn("python3") do |python|
  python.expect(">>> ", timeout: 2.seconds)
  python.send_line("print(40 + 2)")
  python.expect(/(\d+)\r\n/)[1]
end

Give a program to the user, exactly as if they had started it from their shell:

status = TTY::PTY.spawn("vim", ["notes.txt"]).interact

Read a password without echoing it:

password = TTY.with_terminal(STDIN, echo: false) { STDIN.gets }

Running programs

Capture: PTY.run

PTY.run starts the command on a fresh PTY, reads everything it writes until it exits, waits for it, and returns {output, status}.

output, status = TTY::PTY.run("make", ["test"])
puts output
exit status.exit_code

The child sees a real terminal, so programs that only colorize or align columns on a TTY do so. Output newline translation is switched off on the PTY, so lines end in \n instead of the terminal's usual \r\n.

Scoped: PTY.spawn with a block

With a block, PTY.spawn yields the running PTY::Process and returns the block's value. When the block ends, normally or through an exception, the PTY is closed, the child is reaped, and every descriptor is released.

status = TTY::PTY.spawn("sh", ["-c", "read name; echo hello $name"]) do |process|
  process.send_line("crystal")
  process.gets
  process.wait
end

Closing the PTY hangs up the terminal, so a child that is still running receives SIGHUP. Call process.wait inside the block when the child should finish on its own terms; it also gives you the exit status.

Unscoped: PTY.spawn without a block

Without a block you own the process: wait for it and close it yourself.

process = TTY::PTY.spawn("tail", ["-f", "/var/log/syslog"])
5.times { puts process.gets }
process.terminate
process.wait
process.close

Options

PTY.spawn and PTY.run take the same named options. They can also be bundled in a TTY::SpawnOptions value and passed as the third argument.

TTY::PTY.spawn("make", env: {"CC" => "clang", "MAKEFLAGS" => nil}, working_dir: "/src")

options = TTY::SpawnOptions.new(winsize: TTY::Winsize.new(40_u16, 120_u16), clear_env: true)
TTY::PTY.spawn("top", [] of String, options)

An unknown option name is a compile error.

Environment. Without clear_env, the child inherits the parent's environment, and TERM defaults to xterm-256color when the parent has none, so full-screen programs work out of the box. env entries are applied on top. With clear_env: true the child gets only the env entries. The executable is found through the child's PATH, falling back to the parent's.

Shell command lines. With shell: true, command runs through /bin/sh -c and args become the shell's positional parameters. When there are args and the command line does not mention "$@", "$@" is appended so they reach the command.

TTY::PTY.run("ls -l | wc -l", shell: true)
TTY::PTY.run("grep -c", ["TODO", "src/main.cr"], shell: true)

SpawnOptions#environment and SpawnOptions#argv(command, args) show exactly what the child will receive.

When exec fails

If the program cannot be started, PTY.spawn and PTY.run raise TTY::PTY::ExecError, which carries the errno and every path that was tried. The failure is reported through a close-on-exec pipe, so it is never confused with a program that exits with status 127.

begin
  TTY::PTY.spawn("no-such-program")
rescue ex : TTY::PTY::ExecError
  ex.errno_name
  ex.attempts
end

The DSL form

TTY.spawn builds the same call from a block of declarations, checked at compile time:

process = TTY.spawn("sh", ["-c", "ls"]) do
  env path: "/usr/bin:/bin", term: "xterm-256color"
  winsize rows: 24, cols: 80
  working_dir "/tmp"
  close_fds true
  clear_env false
  shell false
end

Named env keys are upcased (env path: ... sets PATH). Pass a hash literal for exact-case names: env({"foo" => "bar"}).

Talking to a program

A process is an IO

TTY::PTY::Process inherits from IO. Everything you know from IO works on it directly:

process = TTY::PTY.spawn("cat")
process.puts "hello"
process.gets
process.each_line { |line| puts line }

Writes are unbuffered, so input reaches the child immediately; there is nothing to flush. Lines read from a terminal end in \r\n, which gets strips.

Reads and writes go through the event loop: a pending read suspends only the calling fiber, and other fibers keep running. When the child exits, reads report end of stream.

Expect

expect reads until a Regex or a literal String matches, consumes everything up to the end of the match, and returns the Regex::MatchData. Whatever arrived after the match stays buffered for the next read.

process.expect(/password: /i, timeout: 5.seconds)
process.send_line(secret)

match = process.expect(/logged in as (\w+)/)
match[1]
match.pre_match

• On timeout it raises IO::TimeoutError; if the program exits first it raises IO::EOFError. Either way, the bytes received so far remain readable.
• Matching works on raw terminal output, including bytes that are not valid UTF-8.
• send_line(line) writes the line followed by \r, the byte a terminal sends for Enter.

Hand-over: interact

interact connects the program to a pair of streams, STDIN and STDOUT by default, and relays bytes in both directions until the program's output ends. It then waits for the program and returns its status.

status = TTY::PTY.spawn("bash").interact

When the input is a terminal, it is put into raw mode for the duration, its window size is copied to the PTY immediately and again on every resize, and its settings are restored afterwards. Descriptor flags on the input are restored in every case. interact resets SIGWINCH to its default handling when it returns.

Waiting, signals, and exit status

process = TTY::PTY.spawn("sleep", ["30"])

if process.wait(100.milliseconds).nil?
  process.signal(Signal::TERM)
end

status = process.wait
status.signal_exit?
status.exit_signal
process.close

• wait blocks until the child exits and caches the result; later calls return the cached status, as does status.
• wait(timeout) returns nil on timeout. On Linux it sleeps on a pidfd, so it returns as soon as the child exits.
• signal takes a Signal or a signal number; terminate and kill send SIGTERM and SIGKILL.

Exit statuses answer to the same names as Crystal's Process::Status (exit_code, normal_exit?, signal_exit?, exit_signal, success?), alongside the traditional exited?, exit_status, signaled?, term_signal, stopped?, and core_dumped?.

Stop and continue events (Linux)

wait_event reports every state change, including stops and continues, through waitid:

process.signal(Signal::STOP)
process.wait_event.stopped?
process.signal(Signal::CONT)
process.wait_event.continued?

wait_event and wait can be mixed freely: whichever observes termination first records it, and the other returns the recorded result.

Pidfds (Linux)

pidfd opens a pollable reference to the child, and poll_exit(timeout) waits on it. Spawned children get a pidfd automatically when the kernel supports it, and signals are then delivered through it, which rules out signalling a recycled pid.

Controlling a terminal

Scoped modes

TTY.raw(STDIN) { STDIN.read_char }
TTY.cbreak(STDIN) { STDIN.read_char }

TTY.with_terminal combines a mode with individual switches and descriptor flags:

TTY.with_terminal(STDIN, cbreak: true, signals: false, nonblocking: true) do
  # ...
end

Its options are raw, cbreak, nonblocking, echo, canonical, and signals, each true or false; raw and cbreak are mutually exclusive. All three helpers restore exactly what they changed, even when the block raises, and return the block's value.

Termios values

TTY::Termios is a plain struct holding a terminal's attributes. Read it with TTY.termios(fd) and write it with #set(fd) or PTY#termios=.

termios = TTY.termios(STDIN)
termios.echo?
termios.canonical = false
termios.set(STDIN)

echo, canonical, and signals are named switches for the most common local flags. raw and cbreak return modified copies; make_raw and make_cbreak change the value in place.

original = pty.termios
pty.termios = original.raw
pty.termios = original

To read, change, and apply in one call, use TTY.modify_termios or PTY#modify_termios. The block receives the current attributes and returns the ones to apply:

TTY.modify_termios(STDIN) do |termios|
  termios.echo = false
  termios
end

pty.modify_termios(&.raw)

Because termios is a value type, a block that only assigns would change a copy and do nothing; such a block is rejected at compile time.

Every flag is still available through input, output, control, and local (typed flag enums), control characters through termios[TTY::ControlChar::Min], the line speed through baud, and VMIN/VTIME through read_timeout. puts termios prints an stty-style summary. On Linux, TTY::Termios2 sets arbitrary baud rates.

Declarative configuration

TTY.configure applies a list of changes on top of the current settings. Flag names are checked at compile time, and a typo fails the build with the list of valid names.

TTY.configure(STDIN) do
  cbreak
  local -Echo, -IExten
  input +ICrNl
  cc min: 1, time: 0
  baud B9600
  action :drain
end

Window size

TTY.winsize(STDIN).cols
TTY::Winsize.current(STDIN)
pty.winsize = TTY::Winsize.new(24_u16, 80_u16)

Winsize.current returns nil when the descriptor is not a terminal. TTY.on_resize(fd) { |size| ... } runs a block on every resize, and Winsize.propagate(from, to) keeps one terminal the same size as another, immediately and on every resize.

Working with a PTY directly

TTY::PTY.open allocates a master/slave pair without starting a program.

pty = TTY::PTY.open
pty.slave_name
pty.write_master("input for the slave side\n")
pty.read_slave(Bytes.new(64))
pty.close

• master_fd, slave_fd: the raw descriptors; master_io and slave_io wrap them as IO::FileDescriptor.
• read_master, write_master, read_slave, and write_slave are direct blocking I/O.
• io returns the fiber-aware PTY::IO over the master, the same object a PTY::Process reads through. It is created on first use, switches the master to nonblocking mode, and is reused afterwards. Do not mix it with the direct master calls.
• After the slave side is gone, master reads report end of stream instead of raising EIO; set eof_on_error = false to get the error.
• close is idempotent and closes every wrapper that was handed out.

Packet mode

In packet mode each master read returns either data or a control packet describing flushes and flow-control changes.

pty.packet_mode = true
buffer = Bytes.new(128)
packet = pty.read_packet(buffer)
packet.data? ? String.new(buffer[0, packet.size]) : packet.events

wait_priority(timeout) waits for a control packet.

Descriptors and readiness

Waiting on descriptors

TTY.wait_readable(STDIN, 500.milliseconds)
TTY.wait_writable(fd, 0)

watches = [
  TTY::PollFd.watch(first, TTY::IOEvent::Readable),
  TTY::PollFd.watch(second, TTY::IOEvent::Readable),
]
TTY.poll(watches, 1.second)
watches.select(&.readable?)

The single-descriptor waits also return true on hang-up or error, so a closed peer never blocks forever.

Descriptor utilities

TTY::FD covers status and descriptor flags (nonblocking?, set_nonblocking, cloexec?, set_cloexec), pipe, dup3, duplicate_cloexec, and on Linux close_range.

Sessions and serial lines

TTY::Session manages sessions and job control: start (setsid), make_controlling, detach, id, foreground_pgrp, set_foreground_pgrp, process_group, set_process_group, signal_process_group, line disciplines, and exclusive mode.

For serial devices, the top-level TTY module provides queue inspection (pending_input, pending_output), flush, drain, break control, software flow control, modem lines (modem_status, set_modem_lines, clear_modem_lines, wait_modem), interrupt counters (serial_icount), and byte injection (inject).

Conventions

The public API accepts the same three kinds of arguments everywhere:

wait(timeout) and wait_event(timeout) on a process require a non-negative timeout. The conversions are public as TTY.fd_of, TTY.timeout_ms, and TTY.signal_number.

Errors:

• TTY::Syscall::Error for failed system calls, with errno, errno_name, operation, and, where they apply, fd, path, and request
• TTY::PTY::ExecError when a program cannot be started
• TTY::PTY::Error for misuse of a PTY, such as I/O after close
• The standard IO::TimeoutError, IO::EOFError, and IO::Error from the IO layer
• TTY::Error, the base class of the shard's own errors

Concurrency

• Event loop. PTY::IO and the PTY::Process IO methods, including expect and send_line, go through the Crystal event loop and suspend only the calling fiber. The direct calls (TTY::Syscall, PTY#read_master, blocking wait) block the whole thread in the default single-threaded runtime.
• Bounded waits. Timed waits (wait(timeout), wait_event(timeout), wait_readable) are safe to use from fibers. PTY.run, the block form of PTY.spawn, and interact end with a blocking wait after the program's output has ended or its terminal has been hung up.
• Ownership. A PTY or PTY::Process is not internally synchronized; let one fiber own it at a time.
• Closing descriptors. Close the IO, not the raw fd. Closing a descriptor the event loop knows about with Syscall.close leaves a stale registration that affects the next descriptor reusing that number. Closing a PTY or its IO wakes any fiber blocked on it with IO::Error.
• Child reaping. Crystal's runtime reaps children on SIGCHLD. wait and wait_event recover the status the runtime recorded, so the exact exit status is never lost unless the child is reaped outside both this shard and the runtime.
• Resize handlers. on_resize and Winsize.propagate install a process-wide SIGWINCH handler that replaces any previous one, and the descriptor they watch must stay open.
• Between fork and exec. The spawn path performs no allocation and no stdlib calls in the child. Keep it that way if you change it.

Platform support

Everything works on Linux. On macOS the portable core works: spawning, IO, expect, interact, termios, window size, sessions, and readiness.

Linux-only APIs are compile-time errors on macOS: a call to one fails the build with a message such as TTY.flow_control is Linux-only, and code that never calls them compiles normally. This covers termios2 custom baud rates, close_range, wait_event, pidfds, packet-mode and lock queries, flow control, modem-line set/clear/wait, and serial counters.

API reference

Every fd parameter is a TTY::Descriptor, every timeout a TTY::Timeout, and every signal a TTY::SignalValue unless stated otherwise.

TTY::PTY (class methods)

TTY::PTY (instance)

TTY::PTY::Process < IO

TTY::PTY::IO < IO

TTY::SpawnOptions

Statuses and events

TTY::ChildEventKind is None, Exited, Killed, Dumped, Trapped, Stopped, or Continued.

Terminal modes

TTY::Termios

TTY::Termios2 (Linux-only) mirrors get, set, the flag accessors, line, and control characters, and adds from(termios), custom_baud=, custom_baud?, input_speed, and output_speed.

TTY::SetAction is Now, Drain, or Flush; TTY::FlushQueue is Input, Output, or Both.

TTY::Winsize

Readiness and polling

TTY::IOEvent flags are Readable, Priority, Writable, Error, HangUp, and Invalid.

TTY::FD

Sessions and serial lines

TTY::Syscall

The raw layer the rest of the shard is built on. It takes plain Int32 descriptors, millisecond timeouts, and signal numbers, and raises Syscall::Error for negative returns.

Constants such as WNOHANG, WNOWAIT, EINTR, EIO, EAGAIN, SIGTERM, and O_CLOEXEC use the host platform's values.

Development

crystal spec
crystal run examples/pty_process.cr
crystal run --release bench/pty_throughput.cr

• spec/ holds the test suite, which needs Crystal 1.19 or newer. The library itself supports 1.10.
• examples/ holds one small runnable program per feature area.
• bench/ holds benchmarks for raw syscalls, PTY throughput, and the macro layer.

The exclusive-mode spec expects EBUSY when a second process opens a locked terminal. The kernel does not enforce exclusive mode for root, so that spec fails when the suite runs as root.

License

MIT