docs.rs failed to build broken-pipe-kills-0.3.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

broken-pipe-kills

Kills your program instead of panicking with

thread 'main' (1964987) panicked at library/std/src/io/stdio.rs:1165:9:
failed printing to stdout: Broken pipe (os error 32)

due unhandled “Broken pipe” errors.

Usage

Add

[dependencies]
broken-pipe-kills = "0.2.0"

to your Cargo.toml and

use broken_pipe_kills;

to main.rs to let rustc know it must be linked despite not being explicitly used.

This crate requires nightly Rust.

Explanation And Examples

The Problem

By default, the Rust standard library code sets SIGPIPE to SIG_IGN before your fn main() runs. This converts SIGPIPE signals to EPIPE errors, which in turn is converted to std::io::ErrorKind::BrokenPipe.

When combined with println!() that panics upon errors, your program will crash when you e.g. pipe to head:

fn main() {
    loop {
        println!("hello world");
    }
}

$ ./main | head
hello world
thread 'main' (1964987) panicked at library/std/src/io/stdio.rs:1165:9:
failed printing to stdout: Broken pipe (os error 32)

The Solution

By using broken-pipe-kills (which overrides the Externally Implementable Item #[std::io::on_broken_pipe]), SIGPIPE is set to SIG_DFL instead, which means your program is nicely killed and don't crash when e.g. piped to head:

use broken_pipe_kills;

fn main() {
    loop {
        println!("hello world");
    }
}

$ ./main | head
hello world

Audit the Code

This crate is tiny and easily audited with the following command [^1]:

curl -H "User-Agent: $USER at $HOST" \
     -L https://crates.io/api/v1/crates/broken-pipe-kills/0.3.0/download |
tar --extract --gzip --to-stdout |
less