docs: note env var influence on `temp_dir` and `env_clear` on Windows
On Windows, `env::temp_dir()` internally calls `GetTempPath2`/`GetTempPath`,
which checks the `TMP`, `TEMP`, and `USERPROFILE` environment variables in
order before falling back to the Windows directory. This lookup order was
previously only discoverable by following links to Microsoft documentation.
This PR documents the env var lookup order directly in `env::temp_dir` docs
and notes `GetTempPath2`'s SYSTEM-identity behavior (`C:\Windows\SystemTemp`).
Addresses rust-lang/rust#125439.
* docs: explicitly list env vars checked by temp_dir on Windows
On Windows, temp_dir() internally calls GetTempPath2/GetTempPath which
checks TMP, TEMP, USERPROFILE environment variables in order. This
information was previously only available by following links to Microsoft
docs. Making it explicit in Rust's own documentation improves
discoverability.
Addresses #125439.
* docs: note env var influence on temp_dir and env_clear on Windows
On Windows, nv::temp_dir() internally calls GetTempPath2/GetTempPath,
which checks TMP, TEMP, and USERPROFILE in order. Document this
lookup order directly in the emp_dir docs rather than requiring users
to follow the link to Microsoft documentation.
Also add a note on Command::env_clear explaining that clearing the
environment affects the child process's emp_dir(), not the parent's.
Closes#125439.
* docs: drop Windows env_clear temp_dir note
Improved security section in rustdoc for `current_exe`
A few improvements to the security section of the docs about `current_exe`
0. The explanatory link <https://vulners.com/securityvulns/SECURITYVULNS:DOC:22183> is ~~broken~~ not directly very helpful in understanding the risk.
1. It basically previously says to never trust the result, which is IMO too pessimistic to be helpful. It's worth understanding the behavior but if you have a use case to re-exec the current program, which is not uncommon, this is a reasonable way to do it.
2. The particular risk is about setuid/setgid processes that shouldn't fully trust the user that spawned them.
3. IMO the most important risk with this function is that the invoker can control argv and PATH, so I made this more explicit. (Many unixes, including Linux, don't rely on them in the implementation, but some do.)
4. The previous text about TOCTOU and races is IMO not really coherent: if an attacker can write to the location where you're going to re-exec, they can fundamentally control what program is executed. They don't need to race with your execution of current_exe, and there is no up-front check.
5. Briefly explain the pattern of CVE-2009-1894: on Linux, depending on system configuration, an attacker who can create hardlinks to the executable can potentially control `/proc/self/exe`. On modern Linux this should normally require permission to write to the executable.
I did some web research for "argv0 vulnerability" and similar terms and didn't find anything else we should be documenting here. (There are issues about argc=0 but those should be prevented by memory safety in Rust.)
I found what the link seemed to be pointing to in <https://vulners.com/cve/CVE-2009-1894>, which talks about confusing a setuid program by creating a hardlink to its exe. I think this is in very particular circumstances something people should still be concerned about: a setuid program on a machine with `fs.protected_hardlinks = 0`. I don't think this justifies warning people not to use the function at all.
cc @mgeisler
- PATHS_SEP is defined as global const since I will implement
split_paths in the future.
- Tested using OVMF using QEMU.
Signed-off-by: Ayush Singh <ayush@beagleboard.org>
If `HOME` is empty, use the fallback instead
This is a minor change in the `home_dir` api. An empty path is never (or should never be) valid so if the `HOME` environment variable is empty then let's use the fallback instead.
r? libs-api
Delegate from `std::env::ArgsOs` to the methods of the inner
platform-specific iterators, when it would be more efficient than just
using the default methods of its own impl. Most platforms use
`vec::IntoIter` as the inner type, so prioritize delegating to the
methods it provides.
`std::env::Args` is implemented atop `std::env::ArgsOs` and performs
UTF-8 validation with a panic for invalid data. This is a visible effect
which users certainly rely on, so we can't skip any arguments. Any
further iterator methods would skip some elements, so no change is
needed for that type.
Add `#[inline]` for any methods which simply wrap the inner iterator.
Although `Env` (as `Vars`), `Args`, path functions, and OS constants are
publicly exposed via `std::env`, their implementations are each
self-contained. Keep them separate in `std::sys` and make a new module,
`sys::env`, for `Env`.
Fix and undeprecate home_dir()
`home_dir()` has been deprecated for 6 years due to using `HOME` env var on Windows.
It's been a long time, and having a perpetually buggy and deprecated function in the standard library is not useful. I propose fixing and undeprecating it.
6 years seems more than long enough to warn users against relying on this function. The change in behavior is minor, and it's more of a bug fix than breakage. The old behavior is unlikely to be useful, and even if anybody actually needed to specifically use the non-standard `HOME` on Windows, they can trivially mitigate this change by reading the env var themselves.
----
Use of `USERPROFILE` is in line with the `home` crate: https://github.com/rust-lang/cargo/blob/37bc5f0232a0bb72dedd2c14149614fd8cdae649/crates/home/src/windows.rs#L12
The `home` crate uses `SHGetKnownFolderPath` instead of `GetUserProfileDirectoryW`. AFAIK it doesn't make any difference in practice, because `SHGetKnownFolderPath` merely adds support for more kinds of folders, including virtual (non-filesystem) folders identified by a GUID, but the specific case of [`FOLDERID_Profile`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_Profile) is documented as a FIXED folder (a regular filesystem path). Just in case, I've added a note to documentation that the use of `GetUserProfileDirectoryW` can change.
I've used `CURRENT_RUSTC_VERSION` in a doccomment. `replace-version-placeholder` tool seems to perform a simple string replacement, so hopefully it'll get updated.
doc: std::env::var: Returns None for names with '=' or NUL byte
The documentation incorrectly stated that std::env::var could return an error for variable names containing '=' or the NUL byte. Copy the correct documentation from var_os.
var_os was fixed in Commit 8a7a665, Pull Request #109894, which closed Issue #109893.
This documentation was incorrectly added in commit f2c0f292, which replaced a panic in var_os by returning None, but documented the change as "May error if ...".
Reference the specific error values and link to them.
The documentation incorrectly stated that std::env::var could return
an error for variable names containing '=' or the NUL byte. Copy the
correct documentation from var_os.
var_os was fixed in Commit 8a7a665, Pull Request #109894, which
closed Issue #109893.
This documentation was incorrectly added in commit f2c0f292, which
replaced a panic in var_os by returning None, but documented the
change as "May error if ...".
Reference the specific error values and link to them.
Simplify environment variable examples
I’ve found myself visiting the documentation for `std::env::vars` every few months, and every time I do, it is because I want to quickly get a snippet to print out all environment variables :-)
So I think it could be nice to simplify the examples a little to make them self-contained. It is of course a style question if one should import a module a not, but I personally don’t import modules used just once in a code snippet.
joboet