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
/// 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:
///