Struct Library

pub struct Library { /* private fields */ }

A loaded wslapi.dll or api-ms-win-wsl-api-l1-1-0.dll instance

Implementations

impl Library

pub fn new() -> Result<Self>

Attempt to load wslapi.dll

Examples found in repository

examples/basic.rs (line 9)

fn main() {
    let ubuntu = "Ubuntu";
    let nonexistant = "Nonexistant";

    let wsl = Library::new().unwrap();
    assert!( wsl.is_distribution_registered(ubuntu));
    assert!(!wsl.is_distribution_registered(nonexistant));
    assert!(wsl.get_distribution_configuration(nonexistant).is_err());

    let cfg = wsl.get_distribution_configuration(ubuntu).unwrap();
    assert!(cfg.default_uid == 0 || (1000 ..= 2000).contains(&cfg.default_uid)); // Root or regular UID
    assert!(cfg.flags & WSL_DISTRIBUTION_FLAGS::DEFAULT == WSL_DISTRIBUTION_FLAGS::DEFAULT);
    assert!((1..=2).contains(&cfg.version)); // WSL version

    println!("Environment varibales:");
    for (k,v) in cfg.default_environment_variables.iter() {
        // XXX: This might be inaccurate / depend on the linux locale?  Good enough for a demo though!
        let k = String::from_utf8_lossy(k);
        let v = String::from_utf8_lossy(v);
        println!("{: <10} = {}", k, v);
    }

    wsl.launch_interactive(ubuntu, "echo testing 123", true).unwrap();

    let stdin  = "echo testing 456\necho PATH: ${PATH}\nasdf";
    let stdout = std::fs::File::create("target/basic.txt").unwrap();
    let stderr = std::fs::File::create("CON").unwrap();
    wsl.launch(ubuntu, "sh", true, stdin, stdout, stderr).unwrap().wait().unwrap();

    println!("\rPress ENTER to quit");
    let _ = std::io::stdin().read_line(&mut String::new());
}

pub fn is_distribution_registered( &self, distribution_name: impl AsRef<OsStr>, ) -> bool

Determines if a distribution is registered with the Windows Subsystem for Linux (WSL).

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).

Returns

• true if the supplied distribution is currently registered
• false otherwise.

See Also

• WslIsDistributionRegistered - the underlying API

Examples found in repository

examples/basic.rs (line 10)

fn main() {
    let ubuntu = "Ubuntu";
    let nonexistant = "Nonexistant";

    let wsl = Library::new().unwrap();
    assert!( wsl.is_distribution_registered(ubuntu));
    assert!(!wsl.is_distribution_registered(nonexistant));
    assert!(wsl.get_distribution_configuration(nonexistant).is_err());

    let cfg = wsl.get_distribution_configuration(ubuntu).unwrap();
    assert!(cfg.default_uid == 0 || (1000 ..= 2000).contains(&cfg.default_uid)); // Root or regular UID
    assert!(cfg.flags & WSL_DISTRIBUTION_FLAGS::DEFAULT == WSL_DISTRIBUTION_FLAGS::DEFAULT);
    assert!((1..=2).contains(&cfg.version)); // WSL version

    println!("Environment varibales:");
    for (k,v) in cfg.default_environment_variables.iter() {
        // XXX: This might be inaccurate / depend on the linux locale?  Good enough for a demo though!
        let k = String::from_utf8_lossy(k);
        let v = String::from_utf8_lossy(v);
        println!("{: <10} = {}", k, v);
    }

    wsl.launch_interactive(ubuntu, "echo testing 123", true).unwrap();

    let stdin  = "echo testing 456\necho PATH: ${PATH}\nasdf";
    let stdout = std::fs::File::create("target/basic.txt").unwrap();
    let stderr = std::fs::File::create("CON").unwrap();
    wsl.launch(ubuntu, "sh", true, stdin, stdout, stderr).unwrap().wait().unwrap();

    println!("\rPress ENTER to quit");
    let _ = std::io::stdin().read_line(&mut String::new());
}

pub fn register_distribution( &self, distribution_name: impl AsRef<OsStr>, tar_gz_filename: impl AsRef<Path>, ) -> Result<()>

Registers a new distribution with the Windows Subsystem for Linux (WSL).

Consider using wsl --import <Distro> <InstalLocation> <FileName> instead:
The directory containing the executable will be registered as the BasePath for rootfs / temp to be placed in.
This odd design choice stems from WslRegisterDistribution itself! Wasn’t that a bad choice as far back as Windows XP?
This also limits you to a single registration per executable!

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).
• tar_gz_filename - Full path to a .tar.gz file containing the file system of the distribution to register.

Returns

• Err(Error) - if distribution_name contained '\0' characters
• Err(Error) - if distribution_name already existed
• Err(Error) - if tar_gz_filename contained '\0' characters
• Err(Error) - if tar_gz_filename wasn’t an absolute path?
• Err(Error) - if tar_gz_filename wasn’t a valid path
• Err(Error) - if the executable’s directory already contains a registered distribution
• Err(Error) - if the executable’s directory wasn’t writable?
• Err(Error) - if WslRegisterDistribution otherwise failed
• Ok(()) - otherwise

See Also

• WslRegisterDistribution - the underlying API

pub fn unregister_distribution( &self, distribution_name: impl AsRef<OsStr>, ) -> Result<()>

Unregisters a distribution from the Windows Subsystem for Linux (WSL).

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).

Returns

• Err(Error) - if distribution_name contained '\0' characters
• Err(Error) - if distribution_name didn’t exist?
• Err(Error) - if WslUnregisterDistribution failed
• Ok(()) - otherwise

See Also

• WslUnregisterDistribution - the underlying API

pub fn configure_distribution( &self, distribution_name: impl AsRef<OsStr>, default_uid: ULONG, wsl_distribution_flags: WSL_DISTRIBUTION_FLAGS, ) -> Result<()>

Modifies the behavior of a distribution registered with the Windows Subsystem for Linux (WSL).

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).
• default_uid - The Linux user ID to use when launching new WSL sessions for this distribution.
• wsl_distribution_flags - Flags specifying what behavior to use for this distribution.

Returns

• Err(Error) - if distribution_name contained '\0' characters
• Err(Error) - if distribution_name didn’t exist?
• Err(Error) - if WslConfigureDistribution otherwise failed (invalid uid? invalid flags?)
• Ok(()) - otherwise

Returns

pub fn get_distribution_configuration( &self, distribution_name: impl AsRef<OsStr>, ) -> Result<Configuration>

Retrieves the current configuration of a distribution registered with the Windows Subsystem for Linux (WSL).

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).

Returns

• Err(Error) - if distribution_name contained '\0' characters
• Err(Error) - if distribution_name didn’t exist?
• Err(Error) - if WslGetDistributionConfiguration failed
• Ok(Configuration { version, default_uid, flags, default_environment_variables }) - otherwise

See Also

• WslGetDistributionConfiguration - the underlying API
• Configuration - the returned struct

Examples found in repository

examples/basic.rs (line 12)

fn main() {
    let ubuntu = "Ubuntu";
    let nonexistant = "Nonexistant";

    let wsl = Library::new().unwrap();
    assert!( wsl.is_distribution_registered(ubuntu));
    assert!(!wsl.is_distribution_registered(nonexistant));
    assert!(wsl.get_distribution_configuration(nonexistant).is_err());

    let cfg = wsl.get_distribution_configuration(ubuntu).unwrap();
    assert!(cfg.default_uid == 0 || (1000 ..= 2000).contains(&cfg.default_uid)); // Root or regular UID
    assert!(cfg.flags & WSL_DISTRIBUTION_FLAGS::DEFAULT == WSL_DISTRIBUTION_FLAGS::DEFAULT);
    assert!((1..=2).contains(&cfg.version)); // WSL version

    println!("Environment varibales:");
    for (k,v) in cfg.default_environment_variables.iter() {
        // XXX: This might be inaccurate / depend on the linux locale?  Good enough for a demo though!
        let k = String::from_utf8_lossy(k);
        let v = String::from_utf8_lossy(v);
        println!("{: <10} = {}", k, v);
    }

    wsl.launch_interactive(ubuntu, "echo testing 123", true).unwrap();

    let stdin  = "echo testing 456\necho PATH: ${PATH}\nasdf";
    let stdout = std::fs::File::create("target/basic.txt").unwrap();
    let stderr = std::fs::File::create("CON").unwrap();
    wsl.launch(ubuntu, "sh", true, stdin, stdout, stderr).unwrap().wait().unwrap();

    println!("\rPress ENTER to quit");
    let _ = std::io::stdin().read_line(&mut String::new());
}

pub fn launch_interactive( &self, distribution_name: impl AsRef<OsStr>, command: impl AsRef<OsStr>, use_current_working_directory: bool, ) -> Result<DWORD>

Launches an interactive Windows Subsystem for Linux (WSL) process in the context of a particular distribution. This differs from Library::launch in that the end user will be able to interact with the newly-created process.

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).
• command - Command to execute. If no command is supplied, launches the default shell.
• use_current_working_directory - Governs whether or not the launched process should inherit the calling process’s working directory. If false, the process is started in the WSL default user’s home directory (“~”).

Returns

• Err(Error) - if distribution_name contained '\0' characters
• Err(Error) - if distribution_name didn’t exist?
• Err(Error) - if command contained '\0' characters
• Err(Error) - if WslLaunchInteractive otherwise failed
• Ok(DWORD) - the exit code of the process after it exits.

See Also

• Library::launch - non-interactive, programatic interaction
• WslLaunchInteractive - the underlying API

Examples found in repository

examples/basic.rs (line 27)

fn main() {
    let ubuntu = "Ubuntu";
    let nonexistant = "Nonexistant";

    let wsl = Library::new().unwrap();
    assert!( wsl.is_distribution_registered(ubuntu));
    assert!(!wsl.is_distribution_registered(nonexistant));
    assert!(wsl.get_distribution_configuration(nonexistant).is_err());

    let cfg = wsl.get_distribution_configuration(ubuntu).unwrap();
    assert!(cfg.default_uid == 0 || (1000 ..= 2000).contains(&cfg.default_uid)); // Root or regular UID
    assert!(cfg.flags & WSL_DISTRIBUTION_FLAGS::DEFAULT == WSL_DISTRIBUTION_FLAGS::DEFAULT);
    assert!((1..=2).contains(&cfg.version)); // WSL version

    println!("Environment varibales:");
    for (k,v) in cfg.default_environment_variables.iter() {
        // XXX: This might be inaccurate / depend on the linux locale?  Good enough for a demo though!
        let k = String::from_utf8_lossy(k);
        let v = String::from_utf8_lossy(v);
        println!("{: <10} = {}", k, v);
    }

    wsl.launch_interactive(ubuntu, "echo testing 123", true).unwrap();

    let stdin  = "echo testing 456\necho PATH: ${PATH}\nasdf";
    let stdout = std::fs::File::create("target/basic.txt").unwrap();
    let stderr = std::fs::File::create("CON").unwrap();
    wsl.launch(ubuntu, "sh", true, stdin, stdout, stderr).unwrap().wait().unwrap();

    println!("\rPress ENTER to quit");
    let _ = std::io::stdin().read_line(&mut String::new());
}

pub fn launch<I, O, E>( &self, distribution_name: impl AsRef<OsStr>, command: impl AsRef<OsStr>, use_current_working_directory: bool, stdin: I, stdout: O, stderr: E, ) -> Result<Process>

where I: TryInto<Stdio>, I::Error: Display, O: TryInto<Stdio>, O::Error: Display, E: TryInto<Stdio>, E::Error: Display,

Launches a Windows Subsystem for Linux (WSL) process in the context of a particular distribution.

Arguments

• distribution_name - Unique name representing a distribution (for example, “Fabrikam.Distro.10.01”).
• command - Command to execute. If no command is supplied, launches the default shell.
• use_current_working_directory - Governs whether or not the launched process should inherit the calling process’s working directory. If false, the process is started in the WSL default user’s home directory (“~”).
• stdin - Handle to use for STDIN.
• stdout - Handle to use for STDOUT.
• stderr - Handle to use for STDERR.

Returns

• Err(Error) - if distribution_name contained '\0' characters
• Err(Error) - if distribution_name didn’t exist?
• Err(Error) - if command contained '\0' characters
• Err(Error) - if stdin, stdout, or stderr failed to convert to Stdio
• Err(Error) - if stdin, stdout, or stderr was an invalid handle for WslLaunch
• Err(Error) - if WslLaunch otherwise failed
• Ok(Process) - if the WSL process that launched successfully

See Also

• Process
• Library::launch_interactive - interactive, inherits the same console handles
• WslLaunch - the underlying API

Examples found in repository

examples/basic.rs (line 32)

fn main() {
    let ubuntu = "Ubuntu";
    let nonexistant = "Nonexistant";

    let wsl = Library::new().unwrap();
    assert!( wsl.is_distribution_registered(ubuntu));
    assert!(!wsl.is_distribution_registered(nonexistant));
    assert!(wsl.get_distribution_configuration(nonexistant).is_err());

    let cfg = wsl.get_distribution_configuration(ubuntu).unwrap();
    assert!(cfg.default_uid == 0 || (1000 ..= 2000).contains(&cfg.default_uid)); // Root or regular UID
    assert!(cfg.flags & WSL_DISTRIBUTION_FLAGS::DEFAULT == WSL_DISTRIBUTION_FLAGS::DEFAULT);
    assert!((1..=2).contains(&cfg.version)); // WSL version

    println!("Environment varibales:");
    for (k,v) in cfg.default_environment_variables.iter() {
        // XXX: This might be inaccurate / depend on the linux locale?  Good enough for a demo though!
        let k = String::from_utf8_lossy(k);
        let v = String::from_utf8_lossy(v);
        println!("{: <10} = {}", k, v);
    }

    wsl.launch_interactive(ubuntu, "echo testing 123", true).unwrap();

    let stdin  = "echo testing 456\necho PATH: ${PATH}\nasdf";
    let stdout = std::fs::File::create("target/basic.txt").unwrap();
    let stderr = std::fs::File::create("CON").unwrap();
    wsl.launch(ubuntu, "sh", true, stdin, stdout, stderr).unwrap().wait().unwrap();

    println!("\rPress ENTER to quit");
    let _ = std::io::stdin().read_line(&mut String::new());
}