stdio `set`, `close` and `take` methods

[the8472]

Proposal

Problem statement

Currently it's not possible to replace, close or take exclusive ownership of stdio handles without using platform-specific crates such as libc, rustix or windows-sys.

Motivating examples or use cases

A program that

• gets passed a regular file as stdin wants to have owned, exclusive access to it, as a File type, and eventually wants to close it
• wants to replace its error output with a log file rather than relying on the parent process to setup the correct redirection
• wants to close stdin/err/out handles
• needs finer control over the locking and buffering of its inputs and outputs

Generally stdio handles are considered shared resources. Being able to make them exclusive instead early during program startup can be important for robustness and correctness.

Solution sketch

The following only lists Stdout but would equally apply to the Stderr, Stdin and the *Lock types.

impl Stdout {
    /// Returns a clone of the original fd/handle and replaces stdio
    /// with a null fd or closes it, as appropriate for the platform.
    fn take_file(&self) -> io::Result<File>

    /// close or replace with null fds, as appropriate
    fn close(&self) -> io::Result<()>

    /// portable flavor of as set_handle/set_fd
    fn set_file(&self, f: File) -> io::Result<()>
    
    /// first clone the old one, then do set_file
    fn replace_file(&self, replace_with: File) -> io::Result<File>
}

// unix
impl StdioExt for Stdout {
    // take the lock, flush, dupfd, unlock
    fn set_fd(&self, fd: OwnedFd) -> io::Result<()>

    // open /dev/null, clone the old one, dup
    fn take_fd(&self) -> io::Result<OwnedFd>
 
    // clone + set
    fn replace_fd(&self, replace_with: OwnedFd) -> io::Result<OwnedFd>
}

// windows
impl StdioExt for Stdout {
    // take the lock, flush, SetStdHandle, unlock
    fn set_handle(&self, handle: OwnedHandle) -> io::Result<()>
    fn take_handle(&self) -> io::Result<OwnedHandle>
    fn replace_handle(&self, replace_with: OwnedHandle) -> io::Result<OwnedHandle>
}

take_file, replace_file and close are convenience APIs that can be built on top of as_fd().try_clone_to_owned() + set()

Open questions

• in which cases we should error in take_file()?
  • On windows, should we return an error when its a console object rather than a regular file (or pipe)?
  • Should we error or return /dev/null or NUL handle when has been closed before?
• Return a new type, e.g. StdioFile instead of File?

Alternatives

• people can keep rolling their own with unsafe APIs and #[cfg] directives
• or use crates

Links and related work

• stdio_override

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[SUPERCILEX]

take_file should probably be take_fd Nevermind, windows calls them handles so I see why a file is returned now.

[joshtriplett]

@the8472 Thanks for writing this!

[shepmaster]

Motivating examples or use cases

Would this feature also allow third-party test frameworks to capture std{out,err} like the built-in test framework?

[the8472]

What the builtin framework uses are a per-thread overrides for Write trait impls. That hack is entirely in userspace and doesn't affect the OS handles.
This ACP is intended to set the process-global io handles, as used by the operating system.

[sunfishcode]

What should println do if stdout is taken or closed?

[the8472]

/// Returns a clone of the original fd/handle and replaces stdio
/// with a null fd or closes it, as appropriate for the platform.

So println will then do the same as if the process had been started with that setup.

[Amanieu]

We discussed this in the libs-api meeting and we're happy to accept this. In the meeting we proposed some extensions to the API so that the full take/replace/set functionality is available for File, OwnedFd and OwnedHandle.