ctrlc

ctrlc is a small Rust crate that wraps platform-specific signal handling behind a single set_handler function, letting applications register a closure to run when the user presses Ctrl-C. It abstracts over Unix signal APIs (via nix), Apple’s dispatch2, and Windows console control handlers (via windows-sys) so the same code works unmodified across platforms.

With the termination feature enabled, it also intercepts SIGTERM and SIGHUP on Unix, making it a common building block for CLI tools and long-running services that need graceful shutdown behavior.

What You Get

• A single cross-platform set_handler API that abstracts Unix signals, Windows console events, and Apple dispatch2
• Optional termination feature to also catch SIGTERM and SIGHUP on Unix for graceful shutdown
• A minimal, dependency-light design using platform-native signal APIs rather than a heavyweight abstraction layer
• Channel-friendly design (works naturally with std::sync::mpsc or any closure-based notification pattern)
• Dual MIT/Apache-2.0 licensing for unrestricted use in any Rust project

Common Use Cases

• Gracefully shutting down a long-running CLI tool or daemon when the user presses Ctrl-C
• Flushing buffers, closing file handles, or committing in-progress work before exit in a server process
• Coordinating a clean stop signal across worker threads in a multi-threaded Rust application
• Building interactive CLI tools that need to intercept interrupts without terminating immediately

Under The Hood

Architecture — The crate’s public surface is a thin, 148-line src/lib.rs exposing set_handler, which delegates to src/platform/mod.rs (20 lines) — a compile-time platform dispatch to either src/platform/unix/mod.rs (142 lines, uses the nix crate’s signal APIs and, on Apple targets, dispatch2) or src/platform/windows/mod.rs (81 lines, uses windows-sys’s console control handler APIs). Errors are centralized in src/error.rs (54 lines) as a small Error enum covering multiple-registration and platform-specific failure cases.

Tech Stack — Pure Rust, edition 2021, targeting Rust 1.69+. Platform-conditional dependencies keep the footprint minimal: nix (signal feature only) on Unix, dispatch2 on Apple targets, windows-sys (Win32 Foundation/Threading/Security/Console features) on Windows. No async runtime dependency — the handler runs synchronously via OS-level signal delivery.

Code Quality — Tests are organized under tests/main/ with a dedicated regression test (issue_97.rs) referencing a specific historical bug, and both test binaries run without the default harness (harness = false) to control signal-handling test isolation, a sign of the maintainer being deliberate about the risks of testing signal-sensitive code. The crate carries an explicit “passively-maintained” badge and 11 tagged releases going back to 2015, with releases still landing in 2025-2026, indicating long-term stability rather than abandonment.

API Design — The public API is intentionally minimal: one function (set_handler) taking a closure, mirroring how developers already use std::thread::spawn or channel callbacks, so integration requires no new concepts. The optional termination Cargo feature flag lets consumers opt into broader signal coverage (SIGTERM/SIGHUP) without changing the call site, keeping the default behavior narrow and predictable.