Add new inherit_handles flag to CommandExt trait #115501

michaelvanstraten · 2023-09-03T10:09:06Z

This PR adds a new flag to the CommandExt trait to set whether to inherit the handles of the calling process ([ref][1]).

This is necessary when, for example, spawning a process with a pseudoconsole attached.

r? @ChrisDenton

ACP: rust-lang/libs-team#264
[1]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw

michaelvanstraten · 2023-09-03T10:12:57Z

Should this have a stabilization issue attached to it?

the8472 · 2023-09-03T12:04:34Z

First you should create an API change proposal to see if libs-api wants it.

michaelvanstraten · 2023-09-03T12:43:05Z

I recently changed the exact same interface and didn't need an ACP, is this really required here?

the8472 · 2023-09-03T12:49:43Z

No, not required

Note that an ACP is not strictly required: you can just go ahead and submit a pull request with an implementation of your proposed API, with the risk of wasted effort if the library team ends up rejecting this feature. However do note that this risk is always present even if an ACP is accepted, as the library team can end up rejecting a feature in the later parts of the stabilization process.

the8472 · 2023-09-03T13:05:44Z

Anyway, does windows have an equivalent to posix_spawn_file_actions_adddup2? I.e. a way to provide a list of descriptors that should be explicitly passed to the child process rather than relying on inheritance flags on handles?

Inheritance is questionable in multi-threaded programs because different command-spawning actions may want to pass different files to the child.

Also, how does one communicate to a child that a specific handle is available? On unix we've run into issues defining IO safety when passing ownership through the environment. Are there better ways to send handles to another process?

This is necessary when, for example, spawning a process with a pseudoconsole attached.

Alternatively, can we limit this to passing a set of well-defined handles?

ChrisDenton · 2023-09-03T13:33:22Z

This is necessary when, for example, spawning a process with a pseudoconsole attached.

It is not necessary when creating a pseudoconsole to disable handle inheritance. Doing so does however allow us to skip the mutex we currently use.

Anyway, does windows have an equivalent to posix_spawn_file_actions_adddup2? I.e. a way to provide a list of descriptors that should be explicitly passed to the child process rather than relying on inheritance flags on handles?

Yes. You need to set inherit_handles to true and then set the PROC_THREAD_ATTRIBUTE_HANDLE_LIST attribute. Rust should have been doing this from the start, imho, but not sure if we can change it now.

I recently changed the exact same interface and didn't need an ACP, is this really required here?

The reason the previous API change didn't require an ACP was because the change was already accepted under an older system (and I asked privately if this was still OK). A new API would need an ACP.

michaelvanstraten · 2023-09-03T13:58:10Z

It is not necessary when creating a pseudoconsole to disable handle inheritance. Doing so does however allow us to skip the mutex we currently use.

Do you know why all of them set bInheritHandles to false? I have look at a dozenth reference implementation so far and all do so.

michaelvanstraten · 2023-09-03T14:02:53Z

Okay I just tested it, indeed not necessary to set bInheritHandles.

Would this still be a useful extension to the CommandExt trait?

ChrisDenton · 2023-09-03T14:03:55Z

Do you know why all of them set bInheritHandles to false? I have look at a dozenth reference implementation so far and all do so.

The most likely the simplest explanation is "because the example code does". But there are good reasons to disable handle inheritance when it's not needed: inheriting unnecessary handles is pointless and also prevents kernel objects from being cleaned up. In the worst case it may also allow the child process to mess with the handles it inherits, though it would have to find them first.

Would this still be a useful extension to the CommandExt trait?

I think it would for the above reasons.

michaelvanstraten · 2023-09-03T14:06:48Z

I don't know if windows has the concept of confidential handles but preventing the child from acquiring those handles could improve security of spawning commands.

michaelvanstraten · 2023-09-03T14:12:26Z

Okay, just found the following list in the windows documentation:

Processes can inherit or duplicate handles to the following types of objects:

Access Token
Communications device
Console input
Console screen buffer
Desktop
Directory
Event
File
File mapping
Job
Mailslot
Mutex
Pipe
Process
Registry key
Semaphore
Socket
Thread
Timer

michaelvanstraten · 2023-09-03T15:44:14Z

rust-lang/libs-team#264

michaelvanstraten · 2023-09-05T10:24:47Z

@ChrisDenton should I message somebody about this in rust internals?

ChrisDenton · 2023-09-05T11:13:54Z

You don't need to do anything other than be patient 🙂. ACPs are discussed in a weekly meeting (time permitting).

michaelvanstraten · 2023-09-05T11:19:52Z

ACPs are discussed in a weekly meeting (time permitting).

Sorry, didn't know that.

bors · 2024-01-13T16:36:05Z

☔ The latest upstream changes (presumably #117285) made this pull request unmergeable. Please resolve the merge conflicts.

pixmaip · 2024-09-25T09:35:24Z

Hi everyone,
I am unearthing this discussion as this proposed API can be mandatory in some cases.

While handle inheritance can be selectively configured using the PROC_THREAD_ATTRIBUTE_HANDLE_LIST attribute, in the case of protected processes, the bInheritHandles parameter still needs to be set to FALSE in all cases, otherwise the CreateProcess call will fail.

This effectively means that Rust programs running as PPL currently cannot spawn non-protected processes using the standard library, as the spawn will always fail, as deccribed in the Microsoft documentation of CreateProcess:

Protected Process Light (PPL) processes: The generic handle inheritance is blocked when a PPL process creates a non-PPL process since PROCESS_DUP_HANDLE is not allowed from a non-PPL process to a PPL process. See Process Security and Access Rights

michaelvanstraten · 2024-09-25T10:24:12Z

I have an exam on Monday but after that I should be able to work on this.

michaelvanstraten · 2024-10-01T11:04:59Z

@pixmaip would the following suggestion aid your need?
rust-lang/libs-team#264 (comment)

pixmaip · 2024-10-01T12:03:58Z

No, the suggestion you mentioned might be good for most usecases, but when running processes as PPL, passing a list of handles to inherit cannot be done.
For the CreateProcess API to succeed, you need to have bInheritHandles set to FALSE.

This is because PPL processes are inherently prevented by the system from leaking handles to non-protected processes, so Windows does not allow it.

Note that setting bInheritHandles to FALSE will automatically prevent standard handles to work properly, meaning that stdin will not be passed through to the child process, and stdout/err will not output any data. The only possible "interaction" with the child process is through its exit status.

michaelvanstraten · 2025-09-17T20:48:05Z

That didn't actually seam to run any tests

PaulDance · 2025-09-18T17:11:52Z

I'm really not an expert in this, but maybe try using @bors try jobs=<job1,job2,...>? The docs mention special permissions though, so it might not work. That, or going through the cross-compilation and VM setup, or just waiting for my (epic) return from vacation.

PaulDance · 2025-09-29T12:04:05Z

Just tested this and it seems to provide adequate reproducibility. The equality assertion only needs to be changed from 0 to 1, as explained in the somewhat-of-a-strong-guess comment I added below. Other than that, I fixed a few minor things here and there, such as a missing semicolon, missing imports, formatting, 2021 -> 2024 edition, ... I only ran the binary obtained from a simple crate completely outside of the compiler UI tests, so there could still be some failures, but considering the relative simplicity of the test, I guess it should be fine.

The module is now:

// Tests `inherit_handles` by spawning a child process and checking the handle
// count of the child process to be 1.

//@ run-pass
//@ only-windows
//@ needs-subprocess
//@ edition: 2024

#![feature(windows_process_extensions_inherit_handles)]

use std::os::windows::io::AsRawHandle;
use std::os::windows::process::CommandExt;
use std::process::{Command, Stdio};
use std::{thread, time};

fn main() {
    if std::env::args().skip(1).any(|s| s == "--child") {
        child();
    } else {
        parent();
    }
}

fn parent() {
    let this_exe = std::env::current_exe().unwrap();

    let mut child_proc = Command::new(&this_exe)
        .arg("--child")
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .inherit_handles(false)
        .spawn()
        .unwrap();

    let mut handle_count = 0;
    unsafe {
        GetProcessHandleCount(child_proc.as_raw_handle(), &mut handle_count);
    }

    // Only a single handle to the PE file the process is spawned from is expected at this point.
    assert_eq!(handle_count, 1);

    // Cleanup.
    child_proc.kill().unwrap();
    child_proc.wait().unwrap();
}

// A process that stays running until killed.
fn child() {
    // Don't wait forever if something goes wrong.
    thread::sleep(time::Duration::from_secs(10));
}

// Windows API
mod winapi {
    use std::os::windows::raw::HANDLE;

    #[link(name = "kernel32")]
    unsafe extern "system" {
        pub fn GetProcessHandleCount(hprocess: HANDLE, pdwhandlecount: *mut u32) -> i32;
    }
}
use winapi::*;

With this, I guess the two testing strategies could be either merged together or done separately, if it still seems appropriate.

michaelvanstraten · 2025-09-29T15:46:39Z

Have you tested it with inherit handles set to true? Is that stable?

PaulDance · 2025-09-29T18:23:05Z

Ah yes, I forgot about that. When using .inherit_handles(true), then the handle count is surely greater than 1, but depends a lot on the execution context: when under a regular OpenSSH session, I see 23, but when adding PAExec in the mix, I see 7. It really seems stable, though, so I think it can be used, only with a assert!(handle_count > 1); instead. The most important to me is that when using .inherit_handles(false), then it seems to be always 1.

I also added:

        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())

on the Command, which could add a bit more confidence and stability.

michaelvanstraten · 2025-10-01T09:51:09Z

I think this should be fine for now, it's a small feature with a relatively small surface area. @PaulDance thank you.

PaulDance · 2025-10-01T11:15:17Z

@michaelvanstraten Looks good!

@ChrisDenton would it be possible to run a try build with the Windows UI tests, please?

PaulDance · 2025-10-07T09:21:01Z

@bors try jobs=x86_64-msvc-1,x86_64-msvc-2,i686-msvc-1,i686-msvc-2

rust-bors · 2025-10-07T09:21:04Z

@PaulDance: 🔑 Insufficient privileges: not in try users

michaelvanstraten · 2025-10-07T09:33:08Z

@bors try jobs=x86_64-msvc-1,x86_64-msvc-2,i686-msvc-1,i686-msvc-2

rust-bors · 2025-10-07T09:33:14Z

@michaelvanstraten: 🔑 Insufficient privileges: not in try users

michaelvanstraten · 2025-10-07T19:23:55Z

rustc-core doesn't build for me on a windows arm VM.

r? @ChrisDenton

rustbot · 2025-10-07T19:23:57Z

Requested reviewer is already assigned to this pull request.

Please choose another assignee.

PaulDance · 2025-10-07T20:58:11Z

@rustbot label S-waiting-on-review

PaulDance · 2025-10-14T10:42:41Z

r?

rustbot · 2025-10-14T10:42:43Z

Error: Parsing assign command in comment failed: ...'' | error: specify user to assign to at >| ''...

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

PaulDance · 2025-10-14T10:45:02Z

r? libs

ChrisDenton

Sorry I've not been reviewing much lately. I'm back now though.

This looks good to me I just have a couple of nits.

View changes since this review

library/std/src/os/windows/process.rs

ChrisDenton · 2025-10-21T08:42:47Z

tests/ui/process/win-inherit-handles.rs

+    }
+
+    // Only a single handle to the PE file the process is spawned from is expected at this point.
+    assert_eq!(handle_count, 1);


I'm slightly worried that the Windows loader, CRT or even the rust runtime could open handles. Could you perhaps spawn the child process twice (one where inherit_handles is true and one where it is false) and compare their handle counts? I think that would be more robust.

Oh and please do check GetProcessHandleCount doesn't error. While one would hope that it doesn't set the handle count in that case, this isn't guaranteed.

Like so:

// Tests `inherit_handles` by spawning a child process and checking its handle // count to be greater than when not setting the option. //@ run-pass //@ only-windows //@ needs-subprocess //@ edition: 2024 #![feature(windows_process_extensions_inherit_handles)] use std::os::windows::io::AsRawHandle; use std::os::windows::process::CommandExt; use std::process::{Command, Stdio}; use std::time::Duration; use std::{env, io, thread}; fn main() { if std::env::args().skip(1).any(|s| s == "--child") { child(); } else { parent(); } } fn parent() { let with_inherit_count = child_handle_count(true); let without_inherit_count = child_handle_count(false); // Only compare the two values instead of only expecting a hard 1 for // robustness, although only 1 has ever been observed here. assert!( with_inherit_count > without_inherit_count, "Child process handle count unexpectedly smaller when inheriting handles compared to when not: {} <= {}", with_inherit_count, without_inherit_count, ); } /// Spawns the current program as a child process and returns its handle count. fn child_handle_count(inherit_handles: bool) -> u32 { let mut child_proc = Command::new(&env::current_exe().unwrap()) .arg("--child") .stdin(Stdio::piped()) .stdout(Stdio::piped()) .stderr(Stdio::piped()) .inherit_handles(inherit_handles) .spawn() .unwrap(); let mut handle_count = 0; let ret = unsafe { GetProcessHandleCount(child_proc.as_raw_handle(), &raw mut handle_count) }; assert_ne!( ret, 0, "GetProcessHandleCount failed: {:?}", io::Error::last_os_error(), ); // Cleanup. child_proc.kill().unwrap(); child_proc.wait().unwrap(); handle_count } /// A process that stays running until killed. fn child() { // Don't wait forever if something goes wrong. thread::sleep(Duration::from_secs(10)); } // Windows API mod winapi { use std::os::windows::raw::HANDLE; #[link(name = "kernel32")] unsafe extern "system" { pub fn GetProcessHandleCount(hprocess: HANDLE, pdwhandlecount: *mut u32) -> i32; } } use winapi::*;

?

check GetProcessHandleCount doesn't error. While one would hope that it doesn't set the handle count in that case, this isn't guaranteed.

It is documented that the value is zero on error and non-zero on failure, so before the changes above, the errors were effectively checked for already, although without using io::Error::last_os_error for clarity when making the test fail. Now it relies on that in order to check for such errors.

The return value is documented as being zero on error. The documentation doesn't say anything about the state of pdwHandleCount.

Oh yes, you're right; sorry, I misread that. I've updated the above comment accordingly.

@ChrisDenton is right here, we should maybe use the BOOL abstraction windows_core uses.

But let me worry about that.

@PaulDance, I guess you were faster :)

Yes :)

windows-rs is not used too much here from what I could see, so a manual check keeps things dependency-less while sufficient I would say.

I'll therefore let you integrate the above full code.

I've integrated the change, rebasing now.

This patch adds a new flag to the [`CommandExt`](1) trait to set whether to inherit the handles of the calling process (2) on Windows systems. ACP: rust-lang/libs-team#264 [1]: https://doc.rust-lang.org/stable/std/os/windows/process/trait.CommandExt.html [2]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw

rustbot · 2025-10-21T16:56:53Z

This PR was rebased onto a different master 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.

rustbot assigned ChrisDenton Sep 3, 2023

rustbot added O-windows Operating system: Windows 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 Sep 3, 2023

This comment has been minimized.

Sign in to view

Dylan-DPC added S-waiting-on-ACP Status: PR has an ACP and is waiting for the ACP to complete. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 6, 2023

bors added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Jan 13, 2024

Dylan-DPC removed the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Feb 14, 2024

michaelvanstraten mentioned this pull request Aug 28, 2024

Fix IO safety in unix.rs rust-lang/jobserver-rs#101

Open

michaelvanstraten force-pushed the set_inherit_handles branch from e3ad17d to bbaa4f5 Compare October 1, 2025 09:49

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 7, 2025

rustbot assigned Mark-Simulacrum and unassigned ChrisDenton Oct 14, 2025

ChrisDenton reviewed Oct 21, 2025

View reviewed changes

ChrisDenton assigned ChrisDenton and unassigned Mark-Simulacrum Oct 21, 2025

michaelvanstraten force-pushed the set_inherit_handles branch from bbaa4f5 to c968a00 Compare October 21, 2025 16:53

This comment has been minimized.

Sign in to view

michaelvanstraten force-pushed the set_inherit_handles branch from c968a00 to 24b0c27 Compare October 21, 2025 16:56

michaelvanstraten requested a review from ChrisDenton October 22, 2025 06:39

Add new inherit_handles flag to CommandExt trait #115501

Are you sure you want to change the base?

Add new inherit_handles flag to CommandExt trait #115501

Conversation

michaelvanstraten commented Sep 3, 2023 • edited by Dylan-DPC Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

michaelvanstraten commented Sep 3, 2023

Uh oh!

the8472 commented Sep 3, 2023

Uh oh!

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

Uh oh!

Uh oh!

the8472 commented Sep 3, 2023

Uh oh!

the8472 commented Sep 3, 2023

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

michaelvanstraten commented Sep 3, 2023

Uh oh!

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

Uh oh!

Uh oh!

michaelvanstraten commented Sep 3, 2023

Uh oh!

michaelvanstraten commented Sep 3, 2023

Uh oh!

michaelvanstraten commented Sep 3, 2023

Uh oh!

michaelvanstraten commented Sep 5, 2023

Uh oh!

ChrisDenton commented Sep 5, 2023

Uh oh!

michaelvanstraten commented Sep 5, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bors commented Jan 13, 2024

Uh oh!

pixmaip commented Sep 25, 2024

Uh oh!

michaelvanstraten commented Sep 25, 2024

Uh oh!

michaelvanstraten commented Oct 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pixmaip commented Oct 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

michaelvanstraten commented Sep 17, 2025

Uh oh!

PaulDance commented Sep 18, 2025

Uh oh!

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

Uh oh!

Uh oh!

michaelvanstraten commented Sep 29, 2025

Uh oh!

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

Uh oh!

Uh oh!

michaelvanstraten commented Oct 1, 2025

Uh oh!

PaulDance commented Oct 1, 2025

Uh oh!

PaulDance commented Oct 7, 2025

Uh oh!

rust-bors bot commented Oct 7, 2025

Uh oh!

michaelvanstraten commented Oct 7, 2025

Uh oh!

rust-bors bot commented Oct 7, 2025

Uh oh!

michaelvanstraten commented Oct 7, 2025

michaelvanstraten commented Sep 3, 2023 •

edited by Dylan-DPC

Loading

michaelvanstraten commented Sep 3, 2023 •

edited

Loading

ChrisDenton commented Sep 3, 2023 •

edited

Loading

michaelvanstraten commented Sep 3, 2023 •

edited

Loading

ChrisDenton commented Sep 3, 2023 •

edited

Loading

michaelvanstraten commented Sep 5, 2023 •

edited

Loading

michaelvanstraten commented Oct 1, 2024 •

edited

Loading

pixmaip commented Oct 1, 2024 •

edited

Loading

PaulDance commented Sep 29, 2025 •

edited

Loading

PaulDance commented Sep 29, 2025 •

edited

Loading

ChrisDenton left a comment •

edited by rustbot

Loading

ChrisDenton Oct 21, 2025 •

edited

Loading

PaulDance Oct 21, 2025 •

edited

Loading

michaelvanstraten Oct 21, 2025 •

edited

Loading

PaulDance Oct 21, 2025 •

edited

Loading

michaelvanstraten Oct 21, 2025 •

edited

Loading