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;
unsafe fn raw_attribute<T: Copy + Send + Sync + 'static>(
&mut self,
attribute: usize,
value: T,
) -> &mut Command;
}
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 · sourcefn creation_flags(&mut self, flags: u32) -> &mut Command
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
.
sourcefn show_window(&mut self, cmd_show: u16) -> &mut Command
🔬This is a nightly-only experimental API. (windows_process_extensions_show_window
#127544)
fn show_window(&mut self, cmd_show: u16) -> &mut Command
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
sourcefn force_quotes(&mut self, enabled: bool) -> &mut Command
🔬This is a nightly-only experimental API. (windows_process_extensions_force_quotes
#82227)
fn force_quotes(&mut self, enabled: bool) -> &mut Command
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 · sourcefn raw_arg<S: AsRef<OsStr>>(&mut self, text_to_append_as_is: S) -> &mut Command
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();
Run§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()
}
Runsourcefn async_pipes(&mut self, always_async: bool) -> &mut Command
🔬This is a nightly-only experimental API. (windows_process_extensions_async_pipes
#98289)
fn async_pipes(&mut self, always_async: bool) -> &mut Command
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());
Runsourceunsafe fn raw_attribute<T: Copy + Send + Sync + 'static>(
&mut self,
attribute: usize,
value: T,
) -> &mut Command
🔬This is a nightly-only experimental API. (windows_process_extensions_raw_attribute
#114854)
unsafe fn raw_attribute<T: Copy + Send + Sync + 'static>( &mut self, attribute: usize, value: T, ) -> &mut Command
windows_process_extensions_raw_attribute
#114854)Set a raw attribute on the command, providing extended configuration options for Windows processes.
This method allows you to specify custom attributes for a child process on Windows systems using raw attribute values. Raw attributes provide extended configurability for process creation, but their usage can be complex and potentially unsafe.
The attribute
parameter specifies the raw attribute to be set, while the value
parameter holds the value associated with that attribute. Please refer to the
windows-rs
documentation or the Win32 API documentation for detailed information
about available attributes and their meanings.
§Note
The maximum number of raw attributes is the value of u32::MAX
.
If this limit is exceeded, the call to process::Command::spawn
will return an Error
indicating that the maximum number of attributes has been exceeded.
§Safety
The usage of raw attributes is potentially unsafe and should be done with caution. Incorrect attribute values or improper configuration can lead to unexpected behavior or errors.
§Example
The following example demonstrates how to create a child process with a specific parent process ID using a raw attribute.
#![feature(windows_process_extensions_raw_attribute)]
use std::os::windows::{process::CommandExt, io::AsRawHandle};
use std::process::Command;
let parent = Command::new("cmd").spawn()?;
let mut child_cmd = Command::new("cmd");
const PROC_THREAD_ATTRIBUTE_PARENT_PROCESS: usize = 0x00020000;
unsafe {
child_cmd.raw_attribute(PROC_THREAD_ATTRIBUTE_PARENT_PROCESS, parent.as_raw_handle() as isize);
}
let mut child = child_cmd.spawn()?;
Run§Safety Note
Remember that improper use of raw attributes can lead to undefined behavior or security vulnerabilities. Always consult the documentation and ensure proper attribute values are used.