Reformulate `std::env::{set,remove}_env` as safety note

1 files changed, 36 insertions, 24 deletions

diff --git a/library/std/src/env.rs b/library/std/src/env.rs
index 53cbb80d3c0..30ac0512348 100644
--- a/library/std/src/env.rs
+++ b/library/std/src/env.rs
@@ -313,18 +313,24 @@ impl Error for VarError {
 /// Sets the environment variable `key` to the value `value` for the currently running
 /// process.
 ///
-/// Note that while concurrent access to environment variables ought to be safe
-/// in Rust, some platforms only expose inherently unsafe non-threadsafe APIs
-/// for inspecting the environment. As a result, using `set_var` or
-/// `remove_var` in a multi-threaded Rust program can lead to undefined
-/// behavior, for example in combination with DNS lookups from
-/// [`std::net::ToSocketAddrs`]. This is a bug
-/// ([rust#27970](https://github.com/rust-lang/rust/issues/27970)) and will be
-/// fixed in a future version of Rust. Additionally, extra care needs to be
-/// taken when auditing calls to unsafe external FFI functions to ensure that
-/// any external environment accesses are properly synchronized with accesses
-/// in Rust. Since Rust does not expose its environment lock directly, this
-/// means that all accesses to the environment must go through Rust's [`var`].
+/// # Safety
+///
+/// Even though this function is currently not marked as `unsafe`, it needs to
+/// be because invoking it can cause undefined behaviour. The function will be
+/// marked `unsafe` in a future version of Rust. This is tracked in
+/// [rust#27970](https://github.com/rust-lang/rust/issues/27970).
+///
+/// This function is safe to call in a single-threaded program.
+///
+/// In multi-threaded programs, you must ensure that are no other threads
+/// concurrently writing or *reading*(!) from the environment through functions
+/// other than the ones in this module. You are responsible for figuring out
+/// how to achieve this, but we strongly suggest not using `set_var` or
+/// `remove_var` in multi-threaded programs at all.
+///
+/// Most C libraries, including libc itself do not advertise which functions
+/// read from the environment. Even functions from the Rust standard library do
+/// that, e.g. for DNS lookups from [`std::net::ToSocketAddrs`].
 ///
 /// Discussion of this unsafety on Unix may be found in:
 ///
@@ -360,18 +366,24 @@ fn _set_var(key: &OsStr, value: &OsStr) {
 
 /// Removes an environment variable from the environment of the currently running process.
 ///
-/// Note that while concurrent access to environment variables ought to be safe
-/// in Rust, some platforms only expose inherently unsafe non-threadsafe APIs
-/// for inspecting the environment. As a result, using `set_var` or
-/// `remove_var` in a multi-threaded Rust program can lead to undefined
-/// behavior, for example in combination with DNS lookups from
-/// [`std::net::ToSocketAddrs`]. This is a bug
-/// ([rust#27970](https://github.com/rust-lang/rust/issues/27970)) and will be
-/// fixed in a future version of Rust. Additionally, extra care needs to be
-/// taken when auditing calls to unsafe external FFI functions to ensure that
-/// any external environment accesses are properly synchronized with accesses
-/// in Rust. Since Rust does not expose its environment lock directly, this
-/// means that all accesses to the environment must go through Rust's [`var`].
+/// # Safety
+///
+/// Even though this function is currently not marked as `unsafe`, it needs to
+/// be because invoking it can cause undefined behaviour. The function will be
+/// marked `unsafe` in a future version of Rust. This is tracked in
+/// [rust#27970](https://github.com/rust-lang/rust/issues/27970).
+///
+/// This function is safe to call in a single-threaded program.
+///
+/// In multi-threaded programs, you must ensure that are no other threads
+/// concurrently writing or *reading*(!) from the environment through functions
+/// other than the ones in this module. You are responsible for figuring out
+/// how to achieve this, but we strongly suggest not using `set_var` or
+/// `remove_var` in multi-threaded programs at all.
+///
+/// Most C libraries, including libc itself do not advertise which functions
+/// read from the environment. Even functions from the Rust standard library do
+/// that, e.g. for DNS lookups from [`std::net::ToSocketAddrs`].
 ///
 /// Discussion of this unsafety on Unix may be found in:
 ///