From a86df1727bf07aabea494d90c3ea4e94e6e75cfa Mon Sep 17 00:00:00 2001 From: Martin Nordholts Date: Thu, 1 Sep 2022 06:43:03 +0200 Subject: [PATCH] unix_sigpipe: Make `sigpipe` param docs long-form --- std/src/rt.rs | 21 +++++++++++++++++++-- std/src/sys/unix/mod.rs | 3 +-- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/std/src/rt.rs b/std/src/rt.rs index b3f6f8295..98f6cc7aa 100644 --- a/std/src/rt.rs +++ b/std/src/rt.rs @@ -72,8 +72,25 @@ macro_rules! rtunwrap { // Runs before `main`. // SAFETY: must be called only once during runtime initialization. // NOTE: this is not guaranteed to run, for example when Rust code is called externally. -// The extra parameter `sigpipe` allows rustc to generate code that instructs std whether -// or not to ignore `SIGPIPE`. +// +// # The `sigpipe` parameter +// +// Since 2014, the Rust runtime on Unix has set the `SIGPIPE` handler to +// `SIG_IGN`. Applications have good reasons to want a different behavior +// though, so there is a `#[unix_sigpipe = "..."]` attribute on `fn main()` that +// can be used to select how `SIGPIPE` shall be setup (if changed at all) before +// `fn main()` is called. See +// for more info. +// +// The `sigpipe` parameter to this function gets its value via the code that +// rustc generates to invoke `fn lang_start()`. The reason we have `sigpipe` for +// all platforms and not only Unix, is because std is not allowed to have `cfg` +// directives as this high level. See the module docs in +// `src/tools/tidy/src/pal.rs` for more info. On all other platforms, `sigpipe` +// has a value, but its value is ignored. +// +// Even though it is an `u8`, it only ever has 3 values. These are documented in +// `compiler/rustc_session/src/config/sigpipe.rs`. #[cfg_attr(test, allow(dead_code))] unsafe fn init(argc: isize, argv: *const *const u8, sigpipe: u8) { unsafe { diff --git a/std/src/sys/unix/mod.rs b/std/src/sys/unix/mod.rs index 2856dfcb3..c84e292ea 100644 --- a/std/src/sys/unix/mod.rs +++ b/std/src/sys/unix/mod.rs @@ -49,8 +49,7 @@ pub fn init(argc: isize, argv: *const *const u8, _sigpipe: u8) {} #[cfg(not(target_os = "espidf"))] // SAFETY: must be called only once during runtime initialization. // NOTE: this is not guaranteed to run, for example when Rust code is called externally. -// The extra parameter `sigpipe` allows rustc to generate code that instructs std whether -// or not to ignore `SIGPIPE`. +// See `fn init()` in `library/std/src/rt.rs` for docs on `sigpipe`. pub unsafe fn init(argc: isize, argv: *const *const u8, sigpipe: u8) { // The standard streams might be closed on application startup. To prevent // std::io::{stdin, stdout,stderr} objects from using other unrelated file