bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

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

Browse source
This commit is contained in:
Tobias Bucher 2023-12-13 12:49:38 +01:00
parent 8057586d3d
commit 2093d0c58e
1 changed files with 36 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

60
library/std/src/env.rs
View file

@ -313,18 +313,24 @@ impl Error for VarError {
/// Sets the environment variable `key` to the value `value` for the currently running /// Sets the environment variable `key` to the value `value` for the currently running
/// process. /// process.
/// ///
/// Note that while concurrent access to environment variables ought to be safe /// # Safety
/// in Rust, some platforms only expose inherently unsafe non-threadsafe APIs ///
/// for inspecting the environment. As a result, using `set_var` or /// Even though this function is currently not marked as `unsafe`, it needs to
/// `remove_var` in a multi-threaded Rust program can lead to undefined /// be because invoking it can cause undefined behaviour. The function will be
/// behavior, for example in combination with DNS lookups from /// marked `unsafe` in a future version of Rust. This is tracked in
/// [`std::net::ToSocketAddrs`]. This is a bug /// [rust#27970](https://github.com/rust-lang/rust/issues/27970).
/// ([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 /// This function is safe to call in a single-threaded program.
/// taken when auditing calls to unsafe external FFI functions to ensure that ///
/// any external environment accesses are properly synchronized with accesses /// In multi-threaded programs, you must ensure that are no other threads
/// in Rust. Since Rust does not expose its environment lock directly, this /// concurrently writing or *reading*(!) from the environment through functions
/// means that all accesses to the environment must go through Rust's [`var`]. /// 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: /// 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. /// Removes an environment variable from the environment of the currently running process.
/// ///
/// Note that while concurrent access to environment variables ought to be safe /// # Safety
/// in Rust, some platforms only expose inherently unsafe non-threadsafe APIs ///
/// for inspecting the environment. As a result, using `set_var` or /// Even though this function is currently not marked as `unsafe`, it needs to
/// `remove_var` in a multi-threaded Rust program can lead to undefined /// be because invoking it can cause undefined behaviour. The function will be
/// behavior, for example in combination with DNS lookups from /// marked `unsafe` in a future version of Rust. This is tracked in
/// [`std::net::ToSocketAddrs`]. This is a bug /// [rust#27970](https://github.com/rust-lang/rust/issues/27970).
/// ([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 /// This function is safe to call in a single-threaded program.
/// taken when auditing calls to unsafe external FFI functions to ensure that ///
/// any external environment accesses are properly synchronized with accesses /// In multi-threaded programs, you must ensure that are no other threads
/// in Rust. Since Rust does not expose its environment lock directly, this /// concurrently writing or *reading*(!) from the environment through functions
/// means that all accesses to the environment must go through Rust's [`var`]. /// 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: /// Discussion of this unsafety on Unix may be found in:
/// ///