Document platform-specific behavior of current_exe, including that Linux can add " (deleted)"

[sourcefrog]

View all comments

This documents one other OS-specific behavior that might be surprising to some users. The underlying behavior is documented in for example https://man7.org/linux/man-pages/man5/proc_pid_exe.5.html.

Rust std docs can't and shouldn't try to cover every single OS quirk but this seems reasonably in line with telling people how to use this function, and with the text above about what happens when the exe has been renamed.

This came up in the context of zed-industries/zed#46367

Fixes #69343 (by documenting the behavior)

[rustbot]

r? @joboet

rustbot has assigned @joboet.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[joboet]

r? libs-api

[the8472]

The convention is to put such things under a platform-specific behavior section + link to elaboration what that means.

Then we do not consider it a new API guarantee.

View changes since this review

[sourcefrog]

The convention is to put such things under a platform-specific behavior section + link to elaboration what that means.

Then we do not consider it a new API guarantee.

This is already under a "platform-specific behavior" heading though?

https://github.com/sourcefrog/rust/blob/802cda98d90f8a9e181b90e0dd6be7c4c7a65946/library/std/src/env.rs#L698-L708

[sourcefrog]

The convention is to put such things under a platform-specific behavior section + link to elaboration what that means.

Then we do not consider it a new API guarantee.

Beyond the scope of this PR, I do think some users will want to know what the behavior is on some particular platform: does it search $PATH, does it read /proc/self/exe, etc etc. At the moment they can read the source.

The API docs make minimal commitments with text like "some platforms may" but perhaps we should upgrade this to something like "Linux will xyz but this is subject to change?"

Anyhow I still think this is a step forward.

[the8472]

This is already under a "platform-specific behavior" heading though?

Ah yes, then just add a link to the "subject to change" section.
The important point is that whatever is documented now may change it in the future, e.g. by returning an error when the path doesn't point to a real location, assuming linux provides some way to do so.

Beyond the scope of this PR, I do think some users will want to know what the behavior is on some particular platform: does it search $PATH, does it read /proc/self/exe, etc etc.

Yes, that's the stuff that can typically be put in that section.

[sourcefrog]

This is already under a "platform-specific behavior" heading though?

Ah yes, then just add a link to the "subject to change" section. The important point is that whatever is documented now may change it in the future, e.g. by returning an error when the path doesn't point to a real location, assuming linux provides some way to do so.

Beyond the scope of this PR, I do think some users will want to know what the behavior is on some particular platform: does it search $PATH, does it read /proc/self/exe, etc etc.

Yes, that's the stuff that can typically be put in that section.

Ah, thanks.

I've added that link, and since it says

Many I/O functions throughout the standard library are documented to indicate what various library or syscalls they are delegated to.

I've actually extended this to document all the currently implemented per-OS behavior by reading the current code.

[theemathas]

See also #69343

[sourcefrog]

@cuviper would you mind looking at this too while you're thinking about current_exe?

[sourcefrog]

@cuviper, @the8472, what do you think, could we merge it?

[Enselic]

I don't think it makes sense to exhaustively list how this is implemented on all platforms. That doesn't say much unless you are an expert in low-level OS APIs.

Instead, under "Platform-specific behavior", couldn't we just say something like:

If the executable is removed while it is running, the returned path might be invalid.

I think that fits in well with the current documentation structure and tone.

View changes since the review

[sourcefrog]

I don't think it makes sense to exhaustively list how this is implemented on all platforms. That doesn't say much unless you are an expert in low-level OS APIs.

Instead, under "Platform-specific behavior", couldn't we just say something like:

If the executable is removed while it is running, the returned path might be invalid.

I think that fits in well with the current documentation structure and tone.

So on the one hand, it is quite of a lot of text to cover all these obscure platforms, and it is in danger of going out of date. And you're quite right that it still doesn't directly tell you what the behavior is, it only gives you a pointer to look it up.

On the other hand, I think people could reasonably want to know how this function handles edge-but-not-niche cases like the file being deleted or renamed while running, or it being hard linked. I came to this from fixing a user-visible bug in Zed, and other threads described how there have been historical security vulnerabilities connected to those edge cases.

My thought was that if we list the underlying OS calls, then people at least have a handle to find out how it specifically behaves on various platforms. Without it, they have to dig through the source code to find out what it calls, which is of course possible, I just did it myself... but that logic taken to an extreme means no API docs are needed at all.

I thought it was reasonable to add this because of precedents like https://doc.rust-lang.org/std/fs/struct.Permissions.html#method.readonly and https://doc.rust-lang.org/std/fs/fn.symlink_metadata.html which tell you in detail what the semantics are on Windows and Unix including which particular underlying APIs that they use, for example:

This function currently corresponds to the lstat function on Unix and the GetFileInformationByHandle function on Windows.

I'm open to rolling this back to just say

On Linux, the string " (deleted)" is added if the file has been deleted. Note that this may change in future.

I don't see a lot of point in just saying the result "might be invalid", as that seems to leave the user with nothing to do but read the source.

Thanks for reading and replying!

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the std::env::current_exe documentation to clarify platform-specific behavior when the running executable is removed on Linux.

Changes:

• Document Linux behavior when the executable is deleted while running.
• Add a reference-style rustdoc link to the “platform-specific behavior” documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

View changes since this review

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.