add std::os::unix::process::CommandExt::fd by Qelxiros · Pull Request #145687 · rust-lang/rust

Qelxiros · 2025-08-20T22:52:51Z

ACP: rust-lang/libs-team#623
Tracking issue: #144989

try-job: aarch64-apple
try-job: arm-android
try-job: test-various

rustbot · 2025-08-20T22:52:56Z

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

tgross35

Has this code been run? The implementation just duplicates the fd without interacting with self.

Please make sure that all new API, even unstable, always gets document0ation and examples, as well as tests if the functionality can't be covered in a simple example. This is tricky API, make sure to cover the FD_CLOEXEC behavior in tests and include something to the effect of https://rust-lang.zulipchat.com/#narrow/channel/327149-t-libs-api.2Fapi-changes/topic/Extra.20FDs.20in.20CommandExt/near/439547420 in docs.

The tests at https://github.com/google/command-fds/tree/main can probably serve as reference.

View changes since this review

dominik-korsa · 2025-09-02T23:12:57Z

+impl CommandExt for Command {
+    fn fd(&mut self, new_fd: RawFd, old_fd: impl Into<OwnedFd>) -> &mut Self {
+        let old = old_fd.into().as_raw_fd();
+        unsafe {
+            self.as_inner_mut().pre_exec(Box::new(move || {
+                cvt_r(|| libc::dup2(old, new_fd))?;
+                let flags = cvt(libc::fcntl(new_fd, F_GETFD))?;
+                cvt(libc::fcntl(new_fd, F_SETFD, flags & !FD_CLOEXEC))?;
+                cvt_r(|| libc::close(old))?;
+                Ok(())
+            }))
+        }
+
+        self
+    }
+}


Using pre_exec for this can reduce the performance of starting the child process.
See my Zulip thread on this:
#t-libs-api/api-changes > Extra FDs in CommandExt @ 💬
also mentioned in this comment in the tracking issue:
#144989 (comment)

Using pre_exec switches the spawn implementation from posix_spawn to fork + execve syscalls. Forking is slower than posix_spawn, because it needs to copy the programs memory (in practice copy on write optimizations are used, but they are still somewhat costly - see my benchmarks also linked in the Zulip message). posix_spawn supports setting the passed FDs, so this feature should be used if possible.

Do you happen to have a sketch of what a better interface would look like?

No, but the issue I've described here is not a problem with the signature of fd. The extension should not use the public pre_exec method, the implementation needs to be modified instead.

I believe this file is of interest:

rust/library/std/src/sys/process/unix/unix.rs

Lines 72 to 74 in 71289c3

if let Some(ret) = self.posix_spawn(&theirs, envp.as_ref())? {

return Ok((ret, ours));

}

Note that there are multiple structs called Command because of how the target-specific functionality is implemented.

Command.spawn first tries to run the posix_spawn method, but its implementations return None if an attribute which the limited posix_spawn syscall cannot handle is set - see the implementations of the posix_spawn method.

Please keep this behavior in mind when adding new Command attributes and creating tests - cases when spawn uses the posix_spawn syscall and when it does not should both be tested. I'm not sure if there is a way to check which spawn variant was chosen in the tests, it is an implementation detail after all.

The extension should not use the public pre_exec method, the implementation needs to be modified instead.

See how other methods in the CommandExt trait are implemented in the library/std/src/os/fd/process.rs file that you modified - they all call the actual implementation using .as.inner_mut()

It would be reasonably straightforward to add a Vec<(OwnedFd, RawFd)> to Command that could be used either with something based on posix_spawn_file_actions_adddup2 or with the exec fallback (also avoiding 1 closure per fd). But aside from being slow, is there any correctness problem with the current implementation?

As long as there isn't anything explicitly wrong, I think it would be reasonable to get the current implementation over the line first so we have some tests. Any chance you would be interested in submitting a followup changing the implementation, since you have been looking into this a lot?

I'm not sure if there is a way to check which spawn variant was chosen in the tests, it is an implementation detail after all.

Adding a last_spawn_was_posix_spawn field to Command for debugging would be fine. That will be accessible from tests once they're moved to within std/src.

But aside from being slow, is there any correctness problem with the current implementation?

No, I'm not claiming this implementation is incorrect - I also haven't reviewed it thoroughly though.

Any chance you would be interested in submitting a followup changing the implementation, since you have been looking into this a lot?

If I have the time, sure.

tgross35 · 2025-09-03T08:30:01Z

Please make sure that all new API, even unstable, always gets document0ation and examples, as well as tests if the functionality can't be covered in a simple example. This is tricky API, make sure to cover the FD_CLOEXEC behavior in tests and include something to the effect of https://rust-lang.zulipchat.com/#narrow/channel/327149-t-libs-api.2Fapi-changes/topic/Extra.20FDs.20in.20CommandExt/near/439547420 in docs.

The tests at https://github.com/google/command-fds/tree/main can probably serve as reference.

Please make sure to note this; a single test unfortunately doesn't cover the nuances that can show up here. https://github.com/google/command-fds/blob/38670577b393c5b6f4e17b4854128cf6120a3ca1/src/lib.rs#L206 has a few test cases, I think it would be completely reasonable to port each of these to a version that matches our API.

Edit: realizing that repo is Apache-2.0 so we can't take anything directly. But tests from it that we should include are:

Multiple parent fds mapped to the same child fd
Two fds, swapped between parent and child
Stdin is mapped

It would also be good to test that:

A nonexistant fd errors on startup
Save the original raw fd. Ensure it remains open until the command is run, then gets closed after spawn (just fcntl(old_fd, F_GETFD) to check if it's still open)

Qelxiros · 2025-09-03T14:06:42Z

fd_test_swap is broken; I'm not confident that swapping fds like that is possible without a dedicated function since they seem to clobber each other. fd_test_close_time is also broken, at least on my machine. I'm not sure why that is, but I'd appreciate any guidance you may have.

tgross35 · 2025-09-04T21:14:18Z

fd_test_swap is broken; I'm not confident that swapping fds like that is possible without a dedicated function since they seem to clobber each other.

That's expected with the current implementation when both fds need to be alive at the same time; this is what we should check for. The goal is to make sure we don't quietly change this behavior by accident.

fd_test_close_time is also broken, at least on my machine. I'm not sure why that is, but I'd appreciate any guidance you may have.

This one is unfortunately trickier. Linux aggressively reuses fds so it's getting mapped to something else after close, so I guess checking flags isn't enough. Instead, checking that the dev+ino are unequal should work:

use std::{fs, io};
use std::os::fd::AsRawFd;
use std::os::unix::fs::MetadataExt;

#[test]
fn whatever() {
    let (_pipe_reader, pipe_writer) = io::pipe().unwrap();

    let fd = pipe_writer.as_raw_fd();
    let fd_path = format!("/dev/fd/{fd}");

    // let mut cmd = Command::new("cat") ...

    // Get the identifier of the fd (metadata follows symlinks)
    let fd_id = md_file_id(&fs::metadata(&fd_path).expect("fd should be open"));

    // stand in for cmd.spawn().unwrap();
    drop(pipe_writer);

    // After the child is spawned, our fd should be closed
    match fs::metadata(&fd_path) {
        // Ok; fd exists but points to a different file
        Ok(md) => assert_ne!(md_file_id(&md), fd_id),
        // Ok; fd does not exist
        Err(_) => ()
    }

    // ...
}

/// Use dev + ino to uniquely identify a file
fn md_file_id(md: &fs::Metadata) -> (u64, u64) {
    (md.dev(), md.ino())
}

Qelxiros · 2025-09-07T19:13:06Z

Even when checking device/inode values, fd_test_close_time fails on my machine. I think that guarantees that the file descriptor is staying open longer than it should, but I have no idea why. I'm a little out of my depth here, but I'll try to look into it. Let me know if you think of anything else.

joboet · 2026-03-06T16:34:04Z

        }

+        for &(ref old_fd, new_fd) in self.get_fds() {
+            cvt_r(|| libc::dup2(old_fd.as_raw_fd(), new_fd))?;


This is problematic and probably unsound (as it violates I/O safety) if new_fd is accidentally equal to the file descriptor number that is used by the pipe or socket used to return errors. That would lead to spawn inaccurately reporting a success, even if an error occurs (since this half of the pipe will be closed).

Is there a way to check for that? If not, it seems impossible to avoid.

@joboet friendly nudge :)

You could use dup2 (ideally std's try_clone wrapper) to clone the pipe/socket to a different descriptor and then close the original, effectively moving the descriptor.

Maybe I don't understand the issue. If new_fd might collide with the pipe/socket, then it might still collide after I move the pipe/socket, right?

@joboet can you restate the concern? I don't think I'm quite seeing what you're getting at.

Prior to forking, we create a socket pair or pipe used to communicate with the child. If those happen to get assigned e.g. fd 4 and the user called cmd.fd(4, ...), it's going to clobber the pipe.

I think Jonas is saying this can be mitigated by doing something like pass preserve_fd: &mut OwnedFd (from the relevant side of the socket/pipe) to do_exec and, prior to each dup2 call for user-specified FDs, check if the destination FD is the same as preserve_fd. If so then try_clone preserve_fd and replace it with the new one, and in the calling function recreate the socket/pipe from it.

You can actually mem::swap preserve_fd then mem::forget the result to save an extra close call, since dup2 is specified to close an open destination fd if it already exists.

Great catch Jonas.

I see, yeah, that sounds like it's basically the same issue I'm referencing here - #145687 (comment) - i.e., we're not really satisfying I/O Safety here. I don't thinkt he current API allows for that though, even if we mitigate it for a small set of known FDs.

Was able to write a test that reliably fails because of this but passes with posix-spawn. @Qelxiros could you cherry pick tgross35@986dba3?

mmastrac · 2026-04-02T20:13:32Z

+                    new_fd,
+                ))?;
+                cvt_nz(libc::posix_spawn_file_actions_addclose(
+                    file_actions.0.as_mut_ptr(),


If old_fd == new_fd (which is useful for clearing FD_CLOEXEC), I think the adddup2 should run, but addclose should be skipped.

seems reasonable

JohnCSimon · 2026-09-06T02:08:07Z

@Qelxiros

Ping from triage: can you post your status on this PR and address the merge conflicts?
if the PR is ready for review reply with @rustbot ready

rustbot · 2026-09-17T23:17:09Z

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.

Qelxiros · 2026-09-17T23:21:24Z

@rustbot ready
Note the second commit. I'm not sure it's necessary, but based on #153133 (comment), it doesn't seem crazy to have. I left it as a separate commit in case we want to remove it.

Mark-Simulacrum · 2026-09-19T18:40:10Z

        }

+        for &(ref old_fd, new_fd) in self.get_fds() {
+            cvt_r(|| libc::dup2(old_fd.as_raw_fd(), new_fd))?;


We should probably mention something about CLOEXEC not being set by us somewhere in the docs.

View changes since the review

dup3 is reasonably widely supported, should we be using that instead where available?

Nope that doesn't make sense since we haven't execed yet.

Mark-Simulacrum · 2026-09-19T18:56:10Z

        }

+        for &(ref old_fd, new_fd) in self.get_fds() {
+            cvt_r(|| libc::dup2(old_fd.as_raw_fd(), new_fd))?;


@joboet can you restate the concern? I don't think I'm quite seeing what you're getting at.

Mark-Simulacrum · 2026-09-19T19:03:33Z

+    /// If this method is called multiple times with the same `new_fd`, all but one file descriptor
+    /// will be lost.


I'm not sure what "file descriptor will be lost" means -- losing an integer is not really a thing, we should say something about closing or not mapping certain fds. I think the semantics we intend is something like:

If new_fd is passed multiple times to this method, or overlaps with inherited fds (e.g., stdin/stderr), then it is not specified which source (old_fd) will end up duplicated into new_fd.

I think what @joboet is getting at in the other thread is that this is inherently in conflict with I/O safety, which states

acting on a file descriptor without proof of ownership can lead to misbehavior and even Undefined Behavior in code that relies on ownership of its file descriptors

Here we are closing arbitrary target fds. My sense is that this API is not really usable as-is. I think the only possible API shape is for the caller to pre-allocate the target FDs for us, e.g., by passing old_fd: OwnedFd, new_fd: OwnedFd; we would then dup2 into the new_fds safely. Or am I missing something?

View changes since the review

Hm: I think this may be safe since we're duping in the child so the parent's originals remain untouched. And afaict we're not claiming exclusive ownership of the FDs except for the output.

This would be a problem if e.g. you hand the child a list of "safe" FDs that it can assume from_raw_fd on, without realizing that it contains duplicates because some non-cloexec FD happens to overlap with a value set in .fd. Perhaps it's worth a note that the child is still responsible for ensuring it only opens one of each FD?

It’s a good point that the damage/risk is mostly (only? not sure if there are kernel APIs that act on any close - iirc, there are bad file locking APIs that unlock on any close) in the child.

But it feels like safe rust code being able to close arbitrary fds in the child is at least border line violating the expected semantics from I/O safety. To some extent that is unavoidable with the APIs present in Linux, but it still seems iffy. I think ideally we would allow dup(fd) semantics with some Rust protocol for retrieving them soundly in the child as owned…

I certainly don’t disagree, sending numbers around like this is a rather low-level API.

Do you think there’s a good resolution here? Maybe the “It is recommended to provide further information to the child by some other mechanism” bit could be made stronger and put in its own section with examples. And/or an unresolved question on the tracking issue.

I think unresolved question is probably the right thing. In the short term we could make this unsafe, though I’m not sure what the exact safety condition should be (and how the caller can guarantee it), especially given that the fd table is inherently a global property. Maybe the target fd should be mandated to be an OwnedFd as I suggest above? That’s a bit wasteful but does seem like it satisfies the requirement that you’re not clobbering random fds…

Started #t-libs > Safety of sending file descriptors since the others may have thoughts on this.

tgross35 · 2026-09-19T20:51:09Z

        }

+        for &(ref old_fd, new_fd) in self.get_fds() {
+            cvt_r(|| libc::dup2(old_fd.as_raw_fd(), new_fd))?;


Prior to forking, we create a socket pair or pipe used to communicate with the child. If those happen to get assigned e.g. fd 4 and the user called cmd.fd(4, ...), it's going to clobber the pipe.

I think Jonas is saying this can be mitigated by doing something like pass preserve_fd: &mut OwnedFd (from the relevant side of the socket/pipe) to do_exec and, prior to each dup2 call for user-specified FDs, check if the destination FD is the same as preserve_fd. If so then try_clone preserve_fd and replace it with the new one, and in the calling function recreate the socket/pipe from it.

You can actually mem::swap preserve_fd then mem::forget the result to save an extra close call, since dup2 is specified to close an open destination fd if it already exists.

Great catch Jonas.

rustbot assigned tgross35 Aug 20, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Aug 20, 2025

tgross35 requested changes Aug 27, 2025

View reviewed changes

Comment thread library/std/src/os/fd/process.rs Outdated

Comment thread library/std/src/os/fd/process.rs Outdated

Comment thread library/std/src/os/fd/process.rs Outdated

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 27, 2025

Qelxiros force-pushed the fd-passing branch from 8abe160 to 2c3335f Compare August 27, 2025 21:54

Qelxiros requested a review from tgross35 August 27, 2025 21:56

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 27, 2025

This comment has been minimized.

Sign in to view

Qelxiros force-pushed the fd-passing branch from 2c3335f to 47ad5b9 Compare August 27, 2025 22:35

dominik-korsa reviewed Sep 2, 2025

View reviewed changes

tgross35 requested changes Sep 3, 2025

View reviewed changes

Comment thread library/std/src/os/fd/process.rs Outdated

Comment thread library/std/src/os/fd/process.rs Outdated

Comment thread library/std/src/os/fd/process.rs Outdated

Comment thread library/std/src/os/fd/process.rs Outdated

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 3, 2025

Qelxiros force-pushed the fd-passing branch from 47ad5b9 to 905ad3f Compare September 3, 2025 14:05

This comment has been minimized.

Sign in to view

Qelxiros force-pushed the fd-passing branch from 905ad3f to fd8c770 Compare September 3, 2025 17:50

rustbot added the O-unix Operating system: Unix-like label Sep 3, 2025

This comment has been minimized.

Sign in to view

tgross35 reviewed Sep 4, 2025

View reviewed changes

Comment thread library/std/tests/fd_passing.rs Outdated

Qelxiros force-pushed the fd-passing branch from fd8c770 to 48c14e4 Compare September 7, 2025 19:08

Qelxiros force-pushed the fd-passing branch from 48c14e4 to 7dda1a6 Compare September 7, 2025 19:13

Qelxiros force-pushed the fd-passing branch from 501a987 to 5ba632d Compare January 14, 2026 16:40

This comment has been minimized.

Sign in to view

bjorn3 mentioned this pull request Feb 27, 2026

process: add dup2 file action #153133

Closed

Qelxiros force-pushed the fd-passing branch from 5ba632d to a0e6252 Compare March 6, 2026 15:56

This comment has been minimized.

Sign in to view

Qelxiros force-pushed the fd-passing branch 2 times, most recently from ca2e300 to 240659f Compare March 6, 2026 16:08

joboet reviewed Mar 6, 2026

View reviewed changes

mmastrac reviewed Apr 2, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

Qelxiros force-pushed the fd-passing branch from 240659f to 2d409b7 Compare September 17, 2026 23:17

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 17, 2026

Mark-Simulacrum requested changes Sep 19, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 19, 2026

tgross35 reviewed Sep 19, 2026

View reviewed changes

Comment thread library/std/src/sys/process/unix/common.rs

tgross35 reviewed Sep 20, 2026

View reviewed changes

Comment thread library/std/src/os/unix/process.rs Outdated

Qelxiros and others added 4 commits September 20, 2026 21:51

add std::os::unix::process::CommandExt::fd

756b94c

skip addclose when old_fd == new_fd

b3ff6bd

std: Add a test for CommandExt::fd clobbering child status FDs

a32b7eb

formatting

bf24f0e

Qelxiros force-pushed the fd-passing branch from cda572f to bf24f0e Compare September 21, 2026 02:13

This comment has been minimized.

Sign in to view

don't clobber pipe fd

c5f935e

	if let Some(ret) = self.posix_spawn(&theirs, envp.as_ref())? {
	return Ok((ret, ours));
	}

		/// If this method is called multiple times with the same `new_fd`, all but one file descriptor
		/// will be lost.

Uh oh!

Conversation

Qelxiros commented Aug 20, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Aug 20, 2025

Uh oh!

tgross35 left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dominik-korsa Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgross35 commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Qelxiros commented Sep 3, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

tgross35 commented Sep 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Qelxiros commented Sep 7, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Qelxiros commented Aug 20, 2025 •

edited by rustbot

Loading

tgross35 left a comment •

edited by rustbot

Loading

dominik-korsa Sep 5, 2025 •

edited

Loading

tgross35 commented Sep 3, 2025 •

edited

Loading

Mark-Simulacrum Sep 19, 2026 •

edited by rustbot

Loading

Mark-Simulacrum Sep 19, 2026 •

edited by rustbot

Loading