Add Command::get_resolved_envs

This addition allows an end-user to inspect the environment variables that are visible to the process when it boots. 

Discussed in:

- #149070
- rust-lang/libs-team#194

Author: schneems

library/std/src/process.rs

@@ -161,7 +161,7 @@
 mod tests;
 
 use crate::convert::Infallible;
-use crate::ffi::OsStr;
+use crate::ffi::{OsStr, OsString};
 use crate::io::prelude::*;
 use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut};
 use crate::num::NonZero;
@@ -1157,7 +1157,8 @@ impl Command {
     /// [`Command::env_remove`] can be retrieved with this method.
     ///
     /// Note that this output does not include environment variables inherited from the parent
-    /// process.
+    /// process. To see the full list of environment variables, including those inherited from the
+    /// parent process, use [`Command::get_resolved_envs`].
     ///
     /// Each element is a tuple key/value pair `(&OsStr, Option<&OsStr>)`. A [`None`] value
     /// indicates its key was explicitly removed via [`Command::env_remove`]. The associated key for
@@ -1186,6 +1187,42 @@ impl Command {
         CommandEnvs { iter: self.inner.get_envs() }
     }
 
+    /// Returns an iterator of the environment variables that will be set when the process is spawned.
+    ///
+    /// This returns the environment as it would be if the command were executed at the time of calling
+    /// this method. The returned environment includes:
+    /// - All inherited environment variables from the parent process (unless [`Command::env_clear`] was called)
+    /// - All environment variables explicitly set via [`Command::env`] or [`Command::envs`]
+    /// - Excluding any environment variables removed via [`Command::env_remove`]
+    ///
+    /// Note that the returned environment is a snapshot at the time this method is called and will not
+    /// reflect any subsequent changes to the `Command` or the parent process's environment. Additionally,
+    /// it will not reflect changes made in a `pre_exec` hook (on Unix platforms).
+    ///
+    /// Each element is a tuple `(OsString, OsString)` representing an environment variable key and value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(command_get_resolved_envs)]
+    /// use std::process::Command;
+    /// use std::ffi::{OsString, OsStr};
+    /// use std::env;
+    /// use std::collections::HashMap;
+    ///
+    /// let mut cmd = Command::new("ls");
+    /// cmd.env("TZ", "UTC");
+    /// unsafe { env::set_var("EDITOR", "vim"); }
+    ///
+    /// let resolved: HashMap<OsString, OsString> = cmd.get_resolved_envs().collect();
+    /// assert_eq!(resolved.get(OsStr::new("TZ")), Some(&OsString::from("UTC")));
+    /// assert_eq!(resolved.get(OsStr::new("EDITOR")), Some(&OsString::from("vim")));
+    /// ```
+    #[unstable(feature = "command_get_resolved_envs", issue = "149070")]
+    pub fn get_resolved_envs(&self) -> impl Iterator<Item = (OsString, OsString)> {
+        self.inner.get_resolved_envs()
+    }
+
     /// Returns the working directory for the child process.
     ///
     /// This returns [`None`] if the working directory will not be changed.

library/std/src/process/tests.rs

@@ -667,3 +667,83 @@ fn terminate_exited_process() {
     assert!(p.kill().is_ok());
     assert!(p.kill().is_ok());
 }
+
+#[test]
+fn test_get_resolved_envs() {
+    use crate::env;
+    use crate::ffi::OsString;
+
+    // Test 1: Basic environment with inheritance
+    let mut cmd = Command::new("echo");
+    cmd.env("TEST_VAR", "test_value");
+
+    let resolved: Vec<(OsString, OsString)> = cmd.get_resolved_envs().collect();
+
+    // Should contain our test var
+    assert!(
+        resolved.iter().any(|(k, v)| k == "TEST_VAR" && v == "test_value"),
+        "TEST_VAR should be present in resolved environment"
+    );
+
+    // Should also contain inherited vars (like PATH on most platforms)
+    let current_env_count = env::vars_os().count();
+    // We added one more, so should have at least as many
+    assert!(
+        resolved.len() >= current_env_count,
+        "Resolved environment should include inherited variables"
+    );
+
+    // Test 2: env_clear should only include explicitly set vars
+    let mut cmd2 = Command::new("echo");
+    cmd2.env_clear();
+    cmd2.env("ONLY_VAR", "only_value");
+
+    let resolved2: Vec<(OsString, OsString)> = cmd2.get_resolved_envs().collect();
+
+    assert_eq!(resolved2.len(), 1, "After env_clear, only explicitly set vars should be present");
+    assert_eq!(resolved2[0], (OsString::from("ONLY_VAR"), OsString::from("only_value")));
+
+    // Test 3: env_remove should exclude a variable
+    let mut cmd3 = Command::new("echo");
+    // Set a known variable and then remove it
+    cmd3.env("TO_REMOVE", "value");
+    cmd3.env_remove("TO_REMOVE");
+
+    let resolved3: Vec<(OsString, OsString)> = cmd3.get_resolved_envs().collect();
+
+    // Should not contain TO_REMOVE
+    assert!(
+        !resolved3.iter().any(|(k, _)| k == "TO_REMOVE"),
+        "Removed variables should not appear in resolved environment"
+    );
+
+    // Test 4: Overriding inherited variables
+    let original_value = env::var_os("PATH");
+    if original_value.is_some() {
+        let mut cmd4 = Command::new("echo");
+        cmd4.env("PATH", "custom_path");
+
+        let resolved4: Vec<(OsString, OsString)> = cmd4.get_resolved_envs().collect();
+
+        let path_entry = resolved4.iter().find(|(k, _)| k == "PATH");
+        assert!(path_entry.is_some(), "PATH should be in resolved environment");
+        assert_eq!(
+            path_entry.unwrap().1,
+            OsString::from("custom_path"),
+            "PATH should have the overridden value"
+        );
+    }
+
+    // Test 5: Multiple operations combined
+    let mut cmd5 = Command::new("echo");
+    cmd5.env("VAR1", "value1");
+    cmd5.env("VAR2", "value2");
+    cmd5.env("VAR3", "value3");
+    cmd5.env_remove("VAR2");
+
+    let resolved5: Vec<(OsString, OsString)> = cmd5.get_resolved_envs().collect();
+
+    assert!(resolved5.iter().any(|(k, v)| k == "VAR1" && v == "value1"));
+    assert!(!resolved5.iter().any(|(k, _)| k == "VAR2"));
+    assert!(resolved5.iter().any(|(k, v)| k == "VAR3" && v == "value3"));
+}

library/std/src/sys/process/env.rs

@@ -113,3 +113,35 @@ impl<'a> ExactSizeIterator for CommandEnvs<'a> {
         self.iter.is_empty()
     }
 }
+
+/// An iterator over the fully resolved environment variables.
+///
+/// This struct is returned by `Command::get_resolved_envs`.
+#[derive(Debug)]
+pub struct ResolvedEnvs {
+    inner: crate::collections::btree_map::IntoIter<EnvKey, OsString>,
+}
+
+impl ResolvedEnvs {
+    pub(crate) fn new(map: BTreeMap<EnvKey, OsString>) -> Self {
+        Self { inner: map.into_iter() }
+    }
+}
+
+impl Iterator for ResolvedEnvs {
+    type Item = (OsString, OsString);
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.inner.next().map(|(key, value)| (key.into(), value))
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.inner.size_hint()
+    }
+}
+
+impl ExactSizeIterator for ResolvedEnvs {
+    fn len(&self) -> usize {
+        self.inner.len()
+    }
+}

library/std/src/sys/process/motor.rs

@@ -98,6 +98,10 @@ impl Command {
         self.env.iter()
     }
 
+    pub fn get_resolved_envs(&self) -> super::env::ResolvedEnvs {
+        super::env::ResolvedEnvs::new(self.env.capture())
+    }
+
     pub fn get_current_dir(&self) -> Option<&Path> {
         self.cwd.as_ref().map(Path::new)
     }

library/std/src/sys/process/uefi.rs

@@ -83,6 +83,10 @@ impl Command {
         self.env.iter()
     }
 
+    pub fn get_resolved_envs(&self) -> super::env::ResolvedEnvs {
+        super::env::ResolvedEnvs::new(self.env.capture())
+    }
+
     pub fn get_current_dir(&self) -> Option<&Path> {
         None
     }

library/std/src/sys/process/unix/common.rs

@@ -263,6 +263,10 @@ impl Command {
         self.env.iter()
     }
 
+    pub fn get_resolved_envs(&self) -> crate::sys::process::env::ResolvedEnvs {
+        crate::sys::process::env::ResolvedEnvs::new(self.env.capture())
+    }
+
     pub fn get_current_dir(&self) -> Option<&Path> {
         self.cwd.as_ref().map(|cs| Path::new(OsStr::from_bytes(cs.as_bytes())))
     }

library/std/src/sys/process/unsupported.rs

@@ -86,6 +86,10 @@ impl Command {
         self.env.iter()
     }
 
+    pub fn get_resolved_envs(&self) -> super::env::ResolvedEnvs {
+        super::env::ResolvedEnvs::new(self.env.capture())
+    }
+
     pub fn get_current_dir(&self) -> Option<&Path> {
         self.cwd.as_ref().map(|cs| Path::new(cs))
     }

library/std/src/sys/process/windows.rs

@@ -250,6 +250,10 @@ impl Command {
         self.env.iter()
     }
 
+    pub fn get_resolved_envs(&self) -> super::env::ResolvedEnvs {
+        super::env::ResolvedEnvs::new(self.env.capture())
+    }
+
     pub fn get_current_dir(&self) -> Option<&Path> {
         self.cwd.as_ref().map(Path::new)
     }