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

r? libs-api

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

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.

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.

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.

See also #69343

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