term_size-rs

term_size is a small Rust library for determining the dimensions of the terminal a program is running in. It queries the underlying platform - using an ioctl TIOCGWINSZ call on Unix-like systems and the Windows console API on Windows - to report the current width and height in character columns and rows, falling back gracefully to None when the output isn’t attached to a real terminal.

The crate exposes four functions that check different standard streams (stdout, stdin, stderr, or all three in priority order), which makes it useful for CLI tools that need to lay out columnar output, progress bars, or word-wrapped text but can’t assume any particular stream is the interactive terminal. The crate is explicitly marked unmaintained by its authors, who recommend the community-maintained terminal_size crate as a replacement, though term_size remains present in many existing dependency trees.

What You Get

• dimensions() - Checks stdout, then stdin, then stderr in order and returns the first stream’s width/height as a tuple, or None if none are a tty.
• dimensions_stdout() - Returns the terminal width and height for stdout only.
• dimensions_stdin() - Returns the terminal width and height for stdin only.
• dimensions_stderr() - Returns the terminal width and height for stderr only.
• Cross-platform support - Uses libc ioctl calls on Unix-like systems and the winapi console API on Windows, with a no-op fallback for unsupported platforms.

Common Use Cases

• CLI output formatting - Determine terminal width to wrap text, size progress bars, or lay out columnar output correctly.
• Directory listing tools - Programs like exa/ls clones use terminal width to decide how many columns of file names to display.
• Interactive prompts - Terminal UI or REPL utilities use terminal size to draw boxes, menus, or truncate output to fit.
• Piped-output detection - Falls back to None when a stream isn’t a real terminal, letting callers switch to non-interactive formatting when piping to a file or another process.

Under The Hood

Architecture lib.rs is a thin facade that re-exports four functions from a platform module; platform/mod.rs uses #[cfg(target_os = ...)] attributes to select one of three sibling implementations (unix.rs, windows.rs, unsupported.rs) at compile time, so no runtime branching or dynamic dispatch occurs. Each platform implementation exposes the identical four-function signature (dimensions, dimensions_stdout, dimensions_stdin, dimensions_stderr), keeping the public API stable regardless of target. The functions are pure, stateless, and return Option tuples rather than throwing, so nothing downstream can break beyond a None result if no stream is a tty.

Tech Stack The crate targets Rust 2018 edition with no build tooling beyond Cargo; on non-Windows targets it depends on libc 0.2.20 for raw ioctl/winsize FFI bindings, and on Windows it depends on winapi 0.3 with the wincon, processenv, and winbase feature flags for the console API. There is no async runtime, database, or web framework involved - it’s a pure systems-level utility crate with legacy Travis CI and AppVeyor configs for cross-platform testing.

Code Quality No test files exist anywhere in the repository - correctness relies entirely on manual verification and the stability of the underlying OS APIs. Error handling is explicit: each ioctl/API call’s return code is checked and converted to Option::None on failure rather than panicking. Naming is consistent and each public function carries a doc comment with a runnable example; there is a rustfmt.toml for formatting but no clippy or CI lint gate visible in the current tree.

API Design The API is intentionally tiny and boilerplate-free: four functions, no configuration structs, no builder patterns, and each mirrors the others so a caller learns one and knows all four. Zero setup is required beyond adding the crate as a dependency, and doc comments include copy-pasteable examples for every function - a low-friction design, though the crate’s own maintainers now recommend terminal_size as the actively maintained successor.