# Trait CommandExt

1.16.0 · Source

    pub trait CommandExt: Sealed {
        // Required methods
        fn creation_flags(&mut self, flags: u32) -> &mut Command;
        fn show_window(&mut self, cmd_show: u16) -> &mut Command;
        fn force_quotes(&mut self, enabled: bool) -> &mut Command;
        fn raw_arg<S: AsRef<OsStr>>(
            &mut self,
            text_to_append_as_is: S,
        ) -> &mut Command;
        fn async_pipes(&mut self, always_async: bool) -> &mut Command;
        fn spawn_with_attributes(
            &mut self,
            attribute_list: &ProcThreadAttributeList<'_>,
        ) -> Result<Child>;
        fn startupinfo_fullscreen(&mut self, enabled: bool) -> &mut Command;
        fn startupinfo_untrusted_source(&mut self, enabled: bool) -> &mut Command;
        fn startupinfo_force_feedback(
            &mut self,
            enabled: Option<bool>,
        ) -> &mut Command;
    }

Available on Windows only.
Expand description

Windows-specific extensions to the `process::Command` builder.

This trait is sealed: it cannot be implemented outside the standard library. This is so that future additional methods are not breaking changes.

## Required Methods§

1.16.0 · Source

#### fn creation_flags(&mut self, flags: u32) -> &mut Command

Sets the process creation flags to be passed to `CreateProcess`.

These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`.

Source

#### fn show_window(&mut self, cmd_show: u16) -> &mut Command

🔬This is a nightly-only experimental API. (`windows_process_extensions_show_window` #127544)

Sets the field `wShowWindow` of STARTUPINFO that is passed to `CreateProcess`. Allowed values are the ones listed in https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-showwindow

Source

#### fn force_quotes(&mut self, enabled: bool) -> &mut Command

🔬This is a nightly-only experimental API. (`windows_process_extensions_force_quotes` #82227)

Forces all arguments to be wrapped in quote (`"`) characters.

This is useful for passing arguments to MSYS2/Cygwin based executables: these programs will expand unquoted arguments containing wildcard characters (`?` and `*`) by searching for any file paths matching the wildcard pattern.

Adding quotes has no effect when passing arguments to programs that use msvcrt. This includes programs built with both MinGW and MSVC.

1.62.0 · Source

#### fn raw_arg<S: AsRef<OsStr>>(&mut self, text_to_append_as_is: S) -> &mut Command

Append literal text to the command line without any quoting or escaping.

This is useful for passing arguments to applications that don’t follow the standard C run-time escaping rules, such as `cmd.exe /c`.

##### §Batch files

Note the `cmd /c` command line has slightly different escaping rules than batch files themselves. If possible, it may be better to write complex arguments to a temporary `.bat` file, with appropriate escaping, and simply run that using:

    let output = Command::new("cmd").args(["/c", &format!("\"{temp_bat_file}\"")]).output();

##### §Example

Run a batch script using both trusted and untrusted arguments.

    #[cfg(windows)]
    // `my_script_path` is a path to known bat file.
    // `user_name` is an untrusted name given by the user.
    fn run_script(
        my_script_path: &str,
        user_name: &str,
    ) -> Result<std::process::Output, std::io::Error> {
        use std::io::{Error, ErrorKind};
        use std::os::windows::process::CommandExt;
        use std::process::Command;

        // Create the command line, making sure to quote the script path.
        // This assumes the fixed arguments have been tested to work with the script we're using.
        let mut cmd_args = format!(r#""{my_script_path}" "--features=[a,b,c]""#);

        // Make sure the user name is safe. In particular we need to be
        // cautious of ascii symbols that cmd may interpret specially.
        // Here we only allow alphanumeric characters.
        if !user_name.chars().all(|c| c.is_alphanumeric()) {
            return Err(Error::new(ErrorKind::InvalidInput, "invalid user name"));
        }

        // now we have validated the user name, let's add that too.
        cmd_args.push_str(" --user ");
        cmd_args.push_str(user_name);

        // call cmd.exe and return the output
        Command::new("cmd.exe")
            .arg("/c")
            // surround the entire command in an extra pair of quotes, as required by cmd.exe.
            .raw_arg(&format!("\"{cmd_args}\""))
            .output()
    }

Source

#### fn async_pipes(&mut self, always_async: bool) -> &mut Command

🔬This is a nightly-only experimental API. (`windows_process_extensions_async_pipes` #98289)

When `process::Command` creates pipes, request that our side is always async.

By default `process::Command` may choose to use pipes where both ends are opened for synchronous read or write operations. By using `async_pipes(true)`, this behavior is overridden so that our side is always async.

This is important because if doing async I/O a pipe or a file has to be opened for async access.

The end of the pipe sent to the child process will always be synchronous regardless of this option.

##### §Example

    #![feature(windows_process_extensions_async_pipes)]
    use std::os::windows::process::CommandExt;
    use std::process::{Command, Stdio};

    Command::new(program)
        .async_pipes(true)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped());

Source

#### fn spawn_with_attributes( &mut self, attribute_list: &ProcThreadAttributeList<'_>, ) -> Result<Child>

🔬This is a nightly-only experimental API. (`windows_process_extensions_raw_attribute` #114854)

Executes the command as a child process with the given `ProcThreadAttributeList`, returning a handle to it.

This method enables the customization of attributes for the spawned child process on Windows systems. Attributes offer extended configurability for process creation, but their usage can be intricate and potentially unsafe.

##### §Note

By default, stdin, stdout, and stderr are inherited from the parent process.

##### §Example

    #![feature(windows_process_extensions_raw_attribute)]
    use std::os::windows::io::AsRawHandle;
    use std::os::windows::process::{CommandExt, ProcThreadAttributeList};
    use std::process::Command;

    let parent = Command::new("cmd").spawn()?;
    let parent_process_handle = parent.as_raw_handle();

    const PROC_THREAD_ATTRIBUTE_PARENT_PROCESS: usize = 0x00020000;
    let mut attribute_list = ProcThreadAttributeList::build()
        .attribute(PROC_THREAD_ATTRIBUTE_PARENT_PROCESS, &parent_process_handle)
        .finish()
        .unwrap();

    let mut child = Command::new("cmd").spawn_with_attributes(&attribute_list)?;

Source

#### fn startupinfo_fullscreen(&mut self, enabled: bool) -> &mut Command

🔬This is a nightly-only experimental API. (`windows_process_extensions_startupinfo` #141010)

When true, sets the `STARTF_RUNFULLSCREEN` flag on the STARTUPINFO struct before passing it to `CreateProcess`.

Source

#### fn startupinfo_untrusted_source(&mut self, enabled: bool) -> &mut Command

🔬This is a nightly-only experimental API. (`windows_process_extensions_startupinfo` #141010)

When true, sets the `STARTF_UNTRUSTEDSOURCE` flag on the STARTUPINFO struct before passing it to `CreateProcess`.

Source

#### fn startupinfo_force_feedback(&mut self, enabled: Option<bool>) -> &mut Command

🔬This is a nightly-only experimental API. (`windows_process_extensions_startupinfo` #141010)

When specified, sets the following flags on the STARTUPINFO struct before passing it to `CreateProcess`:

- If `Some(true)`, sets `STARTF_FORCEONFEEDBACK`
- If `Some(false)`, sets `STARTF_FORCEOFFFEEDBACK`
- If `None`, does not set any flags

## Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

## Implementors§

1.16.0 · Source§

### impl CommandExt for Command