Auto merge of #24741 - cgwalters:note-setenv-and-unsetenv-are-not-threadsafe, r=alexcrichton

See:
https://sourceware.org/bugzilla/show_bug.cgi?id=4887#c9
https://bugs.freedesktop.org/show_bug.cgi?id=65681

I just noticed this while talking to someone who was using
`os.environ['FOO'] = 'BAR'` in Python and since I'm learning Rust, I
was curious if it did anything special here (and the answer appears to
be no).

Java got this right by disallowing `setenv()` from the start.

1 files changed, 22 insertions, 0 deletions

diff --git a/src/libstd/env.rs b/src/libstd/env.rs
index 82999a47e56..126ef38b918 100644
--- a/src/libstd/env.rs
+++ b/src/libstd/env.rs
@@ -243,6 +243,17 @@ impl Error for VarError {
 /// Sets the environment variable `k` to the value `v` for the currently running
 /// process.
 ///
+/// Note that while concurrent access to environment variables is safe in Rust,
+/// some platforms only expose inherently unsafe non-threadsafe APIs for
+/// inspecting the environment. As a result 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.
+///
+/// Discussion of this unsafety on Unix may be found in:
+///
+///  - [Austin Group Bugzilla](http://austingroupbugs.net/view.php?id=188)
+///  - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2)
+///
 /// # Examples
 ///
 /// ```
@@ -260,6 +271,17 @@ pub fn set_var<K: AsRef<OsStr>, V: AsRef<OsStr>>(k: K, v: V) {
 
 /// Removes an environment variable from the environment of the currently running process.
 ///
+/// Note that while concurrent access to environment variables is safe in Rust,
+/// some platforms only expose inherently unsafe non-threadsafe APIs for
+/// inspecting the environment. As a result 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.
+///
+/// Discussion of this unsafety on Unix may be found in:
+///
+///  - [Austin Group Bugzilla](http://austingroupbugs.net/view.php?id=188)
+///  - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2)
+///
 /// # Examples
 ///
 /// ```