Struct WSLCommand 

pub struct WSLCommand<'a> { /* private fields */ }

The WSLCommand struct represents a command that can be executed within the WSL environment. A prepared command to be executed inside WSL.

WSLCommand is a builder-style abstraction around the WSL Plugin API execution functions (ExecuteBinary / ExecuteBinaryInDistribution).

Instances of WSLCommand are created through ApiV1::new_command, ensuring they are always tied to a valid API handle and session.

Key points

• The program path is a Linux path (UTF-8, Unix-style) represented by Utf8UnixPath.
• Arguments are stored as Cow<'a, str> to minimize allocations.
• argv[0] can be overridden; otherwise it defaults to the program path.
• The execution target can be the system context or a specific distribution.

Argument semantics

The underlying WSL Plugin API expects a NULL-terminated argv array:

argv[0] = program name
argv[1..] = user arguments

This type exposes:

• WSLCommand::argv for iterating over the full argument vector,
• WSLCommand::arg0 / WSLCommand::with_arg0 to override argv[0].

Examples

Basic execution

let stream = api
    .new_command(SessionID::from(0), "/bin/cat")
    .with_arg("/proc/version")
    .execute()?;

Overriding argv[0]

Some programs inspect argv[0] to determine their behavior (for example busybox).

let stream = api
    .new_command(session_id, "/bin/busybox")
    .with_arg0("sh")
    .with_args(["-c", "echo hello"])
    .execute()?;

Executing in a user distribution

let distro: UserDistributionID = "3B6F3C1E-9B4A-4F2C-8E7A-2A9C6D4E1F52".parse().unwrap();
let stream = api
    .new_command(SessionID::from(0), "/bin/echo")
    .with_distribution_id(DistributionID::User(distro))
    .with_arg("hello")
    .execute()?;

Notes

• WSLCommand::execute consumes the command and returns a connected TcpStream to the process stdin/stdout.
• stderr is forwarded to dmesg on the Linux side.
• This type performs no validation of the Linux path or arguments beyond UTF-8 handling.

Implementations

impl<'a> WSLCommand<'a>

pub fn get_path(&self) -> &Utf8UnixPath

Returns the program path as a Utf8UnixPath.

pub fn get_arg0(&self) -> &str

Returns argv[0].

If arg0 has not been overridden, this returns the program path string.

pub const fn is_standard_arg_0(&self) -> bool

Returns true if argv[0] is the default value (the program path).

pub fn reset_arg0(&mut self) -> &mut Self

Resets argv[0] to its default value (the program path).

pub fn arg0<T: Into<Cow<'a, str>>>(&mut self, arg0: T) -> &mut Self

Sets argv[0] (builder-style, by mutable reference).

pub fn with_arg0<T: Into<Cow<'a, str>>>(self, arg0: T) -> Self

Sets argv[0] (builder-style, by value).

pub fn arg<T: Into<Cow<'a, str>>>(&mut self, arg: T) -> &mut Self

Pushes one argument (argv[n], n >= 1), builder-style by mutable reference.

pub fn with_arg<T: Into<Cow<'a, str>>>(self, arg: T) -> Self

Pushes one argument (argv[n], n >= 1), builder-style by value.

pub fn args<I>(&mut self, args: I) -> &mut Self

where I: IntoIterator, I::Item: Into<Cow<'a, str>>,

Extends arguments from an iterator, builder-style by mutable reference.

pub fn with_args<I>(self, args: I) -> Self

where I: IntoIterator, I::Item: Into<Cow<'a, str>>,

Extends arguments from an iterator, builder-style by value.

pub fn get_args(&self) -> impl ExactSizeIterator<Item = &str>

Returns an iterator over user-provided arguments (argv[1..]).

pub fn argv(&self) -> impl Iterator<Item = &str>

Returns an iterator over the full argv (argv[0] + argv[1..]).

pub fn clear_args(&mut self) -> &mut Self

Clears user-provided arguments (argv[1..]).

pub fn truncate_args(&mut self, i: usize) -> &mut Self

Truncates user-provided arguments (argv[1..]) to length i.

pub fn distribution_id(&mut self, distribution_id: DistributionID) -> &mut Self

Sets the distribution target (builder-style by mutable reference).

pub fn with_distribution_id(self, distribution_id: DistributionID) -> Self

Sets the distribution target (builder-style by value).

pub fn reset_distribution_id(&mut self) -> &mut Self

Resets the distribution target to DistributionID::System.

pub const fn get_distribution_id(&self) -> DistributionID

Returns the current distribution target.

pub fn prepare(&self) -> PreparedWSLCommand<'a>

Prepare a WSLCommand for execution, encoding the path and arguments into C-compatible formats.

Trait Implementations

impl<'a> Clone for WSLCommand<'a>

fn clone(&self) -> WSLCommand<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for WSLCommand<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<&WSLCommand<'a>> for PreparedWSLCommand<'a>

fn from(value: &WSLCommand<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<WSLCommand<'a>> for PreparedWSLCommand<'a>

fn from(value: WSLCommand<'a>) -> Self

Converts to this type from the input type.

impl WSLCommandExecution for WSLCommand<'_>

fn execute(&self) -> ApiResult<TcpStream>

Executes the command via the underlying WSL Plugin API.