docs: clarify path search behavior in std::process::Command::new#153469
Open
Albab-Hasan wants to merge 1 commit intorust-lang:mainfrom
Open
docs: clarify path search behavior in std::process::Command::new#153469Albab-Hasan wants to merge 1 commit intorust-lang:mainfrom
Albab-Hasan wants to merge 1 commit intorust-lang:mainfrom
Conversation
rustbot
added
S-waiting-on-review
Collaborator
|
r? @joboet rustbot has assigned @joboet. Use Why was this reviewer chosen?The reviewer was selected based on:
|
This comment has been minimized.
This comment has been minimized.
the existing docs mentioned that PATH is searched "in an OS-defined way"
and that it could be controlled by setting PATH on the Command, but never
explained *which* PATH is actually used. this is the part that surprises
people.
on unix, the key thing to understand is that when you modify the child's
environment (via env(), env_remove(), or env_clear()), the PATH search
uses whatever PATH ends up in the child's environment — not the parent's.
so if you call env_clear() and forget to set PATH, you don't get the
parent's PATH as a fallback; you get the OS default (typically
/bin:/usr/bin), which often won't find what you need.
the three cases are now documented explicitly:
- unmodified env: child inherits parent's PATH, that gets searched
- PATH explicitly set via env(): the new value is searched
- PATH removed (env_clear or env_remove): falls back to OS default,
not the parent's PATH
on windows, rust resolves the executable before spawning rather than
letting CreateProcessW do it. the search order is: child's PATH (if
explicitly set) first, then system-defined directories, then the parent's
PATH. the existing note about the windows limitation is preserved.
a few honest limitations in this doc:
- the unix fallback path behavior ("typically /bin:/usr/bin") is verified
for linux/glibc; behavior on macOS, BSD, and musl is similar in practice
but not exhaustively confirmed here
- the windows search order is summarized as "system-defined directories"
which actually includes the application directory as a distinct step —
that detail is omitted for brevity
- posix_spawnp's PATH source (calling process environ vs envp argument) is
ambiguous in the POSIX spec; the behavior here is inferred from the guard
in unix.rs that bypasses posix_spawn when PATH has been modified
Albab-Hasan
force-pushed
the
doc/command-path-search-behavior
branch
from
f2c6cb2 to
4d5ce27
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
the existing docs mentioned that
PATHis searched in an "os defined way" and that it could be controlled by setting PATH on the command but never explained whichPATHis actually used.on unix the key thing to understand is that when you modify the childs environment (via
env(),env_remove(), orenv_clear()), thePATHsearch uses whateverPATHends up in the child's environment not the parents. so if you callenv_clear()and forget to setPATH, you don't get the parentsPATHas a fallback; you get the OS default (typically/bin:/usr/bin) which often won't find what you need.the three cases are now documented:
PATH, that gets searchedPATHexplicitly setvia env(): the new value is searchedPATHremoved (env_clearorenv_remove): falls back to OS default, not the parentsPATHon windows rust resolves the executable before spawning rather than letting
CreateProcessWdo it. the search order is: childsPATH(if explicitly set) first then system-defined directories then the parentsPATH. the existing note about issue #37519 is preserved.limitations in this doc:
/bin:/usr/bin") is verified for linux/glibc. behavior on macOS, BSD, and musl is similar in practice but not fully confirmed here.posix_spawnpPATHsource (calling process environ vs envp argument) is ambiguous in thePOSIXspec; the behavior here is inferred from the guard inunix.rsthat bypassesposix_spawnwhenPATHhas been modified.closes #137286 (hopefully)