Implement stdio FD constants

[hanna-kruppe]

Tracking issue: #150836

[rustbot]

r? @ChrisDenton

rustbot has assigned @ChrisDenton.
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

[ChrisDenton]

Could this be moved to a new section in the BorrowedFd docs rather than being on STDERR?

[hanna-kruppe]

Which parts and why? I could see some of it being relevant or at least instructive for general BorrowedFd docs (e.g., discussion of BorrowedFd<'static> implications, or the std::io handle vs. underlying FD differences, since that also matters for using AsFd on the handles). But e.g. for the bullet point your comment is attached to, I don't see how it would relate to BorrowedFd docs at all.

[ChrisDenton]

The STDOUT and STDIN both forward readers to STDERR for more documentation. This part of the docs could arguably be on STDOUT or STDIN, it makes no less or more sense than having it on STDERR, In cases such as these it does often make sense to have module or type-level.

The reason I asked about BorrowedFd specifically is that these constants aren't special to std. They can be constructed manually by users, no? So the docs apply equally to those too.

[hanna-kruppe]

Oh, I see what you mean now. FWIW, there are some (weak) reasons why I chose STDERR as the "canonical" place to host the docs: in my experience stderr is the one that's needed most frequently (so documenting it directly saves the most people a click), and both stdin and stdout have unique additional concerns that don't apply to stderr but may be worth discussing (so if STDERR referenced one of the others, some of the referenced docs would not apply to STDERR at all). But if we had a module like std::os::fd::stdio, I would agree that the docs common to all three constants should live there. That's better than semi-arbitrarily picking one item to host the docs, and the alternatives of duplicating the doc comments or generating them with a macro are really unappealing.

However, putting the stdio FD docs on BorrowedFd feels weird to me, because I think that the overwhelming majority of BorrowedFd uses don't have anything to do with stdio. Conversely, while you're right that these constants aren't special, I don't think putting these docs (only) on BorrowedFd is likely to reach the users who would benefit from reading them. I think the vast majority of code that ends up handling a stdio fd falls into one of three categories:

• Get the BorrowedFd from the std::io handles (locked or not) via AsFd impls. In this case they might check the BorrowedFd docs, but I wouldn't count on it (personally I wouldn't expect to find docs about the stdio case specifically on such a broadly useful type). An explicitly cross-reference in the docs of impl AsFd for Std{in,out,err} and/or of the handle types themselves seems useful in any case.
• Use a library such as rustix or nix that wrap syscalls or libc functions to work with the safe FD types. These libraries either expose and document the stdio FDs themselves (see rustix::stdio), or currently document usage with the std::io handles via impl AsFd arguments (e.g., see the nix::unistd::dup2_stdout example)
• Don't deal with BorrowedFd at all, e.g., just use RawFd and the integer constants 0, 1, 2 with libc functions.

Many of these uses ought to be able to migrate to the constants added in this PR once they're stable (but not all, e.g. if the locked handles are involved). But IMO the most likely way this will happen is if the constants get cross-referenced by docs or discovered by searching for the terms "stdin" / "stdout" / "stderr". In either case, going to the documentation for the constant and then having to follow a "See this section of BorrowedFd docs" link for the bulk of the docs feels weird.

[hanna-kruppe]

I've also considered splitting the docs conceptually along the lines of "what to consider when dealing with stdio via FDs" (useful even if you mostly use the handle and sometimes call as_fd() on it) vs. "why would you need to use the constants" (more esoteric). The former could be useful to document on the std::io handles, but there we face the analogous problem: there's no good place to put docs common to all three handles. The module docs are already very long just surveying the key items and concepts, so adding detailed docs along those lines to the module docs seems like a bad idea.

Maybe duplicating docs is the least bad option here. I don't like the risk of docs diverging due to future improvements being applied to one copy and not another, but in std::io, there's already significant duplication between handle types and the free functions for getting the handles, as well as between different streams (e.g., the Windows portability consideration is repeated four six times between stdout(), stderr(), Stdout, Stderr, StdoutLock, and StderrLock).

[ChrisDenton]

Ok, thanks. I'm happy to accept this as is for now at least. If someone does have any ideas there's plenty of time for the docs to be adjusted.

[ChrisDenton]

Ok, thanks. I'm happy to accept this as is for now at least. If someone does have any ideas there's plenty of time for the docs to be adjusted.

[hanna-kruppe]

Added as unresolved question to the tracking issue

[ChrisDenton]

@bors r+

[rust-bors]

📌 Commit 8b5be2b has been approved by ChrisDenton

It is now in the queue for this repository.