src/doc/unstable-book/src/language-features/unix-sigpipe.md

   1 # `unix_sigpipe`
   2
   3 The tracking issue for this feature is: [#97889]
   4
   5 [#97889]: https://github.com/rust-lang/rust/issues/97889
   6
   7 ---
   8
   9 The `#[unix_sigpipe = "..."]` attribute on `fn main()` can be used to specify how libstd shall setup `SIGPIPE` on Unix platforms before invoking `fn main()`. This attribute is ignored on non-Unix targets. There are three variants:
  10 * `#[unix_sigpipe = "inherit"]`
  11 * `#[unix_sigpipe = "sig_dfl"]`
  12 * `#[unix_sigpipe = "sig_ign"]`
  13
  14 ## `#[unix_sigpipe = "inherit"]`
  15
  16 Leave `SIGPIPE` untouched before entering `fn main()`. Unless the parent process has changed the default `SIGPIPE` handler from `SIG_DFL` to something else, this will behave the same as `#[unix_sigpipe = "sig_dfl"]`.
  17
  18 ## `#[unix_sigpipe = "sig_dfl"]`
  19
  20 Set the `SIGPIPE` handler to `SIG_DFL`. This will result in your program getting killed if it tries to write to a closed pipe. This is normally what you want if your program produces textual output.
  21
  22 ### Example
  23
  24 ```rust,no_run
  25 #![feature(unix_sigpipe)]
  26 #[unix_sigpipe = "sig_dfl"]
  27 fn main() { loop { println!("hello world"); } }
  28 ```
  29
  30 ```bash
  31 % ./main | head -n 1
  32 hello world
  33 ```
  34
  35 ## `#[unix_sigpipe = "sig_ign"]`
  36
  37 Set the `SIGPIPE` handler to `SIG_IGN` before invoking `fn main()`. This will result in `ErrorKind::BrokenPipe` errors if you program tries to write to a closed pipe. This is normally what you want if you for example write socket servers, socket clients, or pipe peers.
  38
  39 This is what libstd has done by default since 2014. (However, see the note on child processes below.)
  40
  41 ### Example
  42
  43 ```rust,no_run
  44 #![feature(unix_sigpipe)]
  45 #[unix_sigpipe = "sig_ign"]
  46 fn main() { loop { println!("hello world"); } }
  47 ```
  48
  49 ```bash
  50 % ./main | head -n 1
  51 hello world
  52 thread 'main' panicked at 'failed printing to stdout: Broken pipe (os error 32)', library/std/src/io/stdio.rs:1016:9
  53 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
  54 ```
  55
  56 ### Note on child processes
  57
  58 When spawning child processes, the legacy Rust behavior if `#[unix_sigpipe]` is not specified is to
  59 reset `SIGPIPE` to `SIG_DFL`.
  60
  61 If `#[unix_sigpipe = "..."]` is specified, no matter what its value is, the signal disposition of
  62 `SIGPIPE` is no longer reset. This means that the child inherits the parent's `SIGPIPE` behavior.