Struct runas::Command

pub struct Command { /* fields omitted */ }

A process builder for elevated execution, providing fine-grained control over how a new process should be spawned.

A default configuration can be generated using Command::new(program), where program gives a path to the program to be executed. Additional builder methods allow the configuration to be changed (for example, by adding arguments) prior to spawning:

use runas::Command;

let child = if cfg!(target_os = "windows") {
    Command::new("cmd")
            .args(&["/C", "echo hello"])
            .spawn()
            .expect("failed to execute process")
} else {
    Command::new("sh")
            .arg("-c")
            .arg("echo hello")
            .spawn()
            .expect("failed to execute process")
};

let hello = child.wait();

Command can be reused to spawn multiple processes. The builder methods change the command without needing to immediately spawn the process.

use runas::Command;

let mut echo_hello = Command::new("sh");
echo_hello.arg("-c")
          .arg("echo hello");
let hello_1 = echo_hello.spawn().expect("failed to execute process");
let hello_2 = echo_hello.spawn().expect("failed to execute process");

Similarly, you can call builder methods after spawning a process and then spawn a new process with the modified settings.

use runas::Command;

let mut list_dir = Command::new("ls");

// Execute `ls` in the current directory of the program.
list_dir.status().expect("process failed to execute");

println!();

// Change `ls` to execute in the root directory.
list_dir.current_dir("/");

// And then execute `ls` again but in the root directory.
list_dir.status().expect("process failed to execute");

Implementations

impl Command

pub fn new<S: AsRef<OsStr>>(program: S) -> Command

Constructs a new Command for launching the program at path program, with the following default configuration:

• No arguments to the program
• Program to be visable
• Not launched from a GUI context
• Inherit the current process's environment
• Inherit the current process's working directory
• Inherit stdin/stdout/stderr for spawn or status, but create pipes for output

Builder methods are provided to change these defaults and otherwise configure the process.

If program is not an absolute path, the PATH will be searched in an OS-defined way.

The search path to be used may be controlled by setting the PATH environment variable on the Command, but this has some implementation limitations on Windows (see issue #37519).

Examples

Basic usage:

use runas::Command;

Command::new("sh")
        .spawn()
        .expect("sh command failed to start");

pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command

Adds an argument to pass to the program.

Only one argument can be passed per use. So instead of:

.arg("-C /path/to/repo")

usage would be:

.arg("-C")
.arg("/path/to/repo")

To pass multiple arguments see args.

Examples

Basic usage:

use runas::Command;

Command::new("ls")
        .arg("-l")
        .arg("-a")
        .spawn()
        .expect("ls command failed to start");

pub fn args<S: AsRef<OsStr>>(&mut self, args: &[S]) -> &mut Command

Adds multiple arguments to pass to the program.

To pass a single argument see arg.

Examples

Basic usage:

use runas::Command;

Command::new("ls")
        .args(&["-l", "-a"])
        .spawn()
        .expect("ls command failed to start");

pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command

Sets the working directory for the child process.

Platform-specific behavior

If the program path is relative (e.g., "./script.sh"), it's ambiguous whether it should be interpreted relative to the parent's working directory or relative to current_dir. The behavior in this case is platform specific and unstable, and it's recommended to use canonicalize to get an absolute program path instead.

Examples

Basic usage:

use runas::Command;

Command::new("ls")
        .current_dir("/bin")
        .spawn()
        .expect("ls command failed to start");

pub fn show(&mut self, val: bool) -> &mut Command

Controls the visibility of the program on supported platforms.

The default is to launch the program visible.

Examples

use runas::Command;

let status = Command::new("/bin/cat")
                     .arg("file.txt")
                     .disable_prompt()
                     .status()
                     .expect("failed to execute process");

assert!(status.success());

pub fn gui(&mut self, val: bool) -> &mut Command

Controls the GUI context. The default behavior is to assume that the program is launched from a command line (not using a GUI). This primarily controls how the elevation prompt is rendered. On some platforms like Windows the elevation prompt is always a GUI element.

If the preferred mode is not available it falls back to the other automatically.

pub fn disable_force_prompt(&mut self) -> &mut Command

Disabling the force prompt would allow the successive use of elevated commands on unix platforms without prompting for a password after each command.

By default, the user will be prompted on each successive command.

Examples

use runas::Command;

let status = Command::new("/bin/cat")
                     .arg("file.txt")
                     .disable_prompt()
                     .status()
                     .expect("failed to execute process");

assert!(status.success());
 
//The user won't be prompted for a password on the second run.
status = Command::new("/bin/ps")
                     .disable_prompt()
                     .status()
                     .expect("failed to execute process");

assert!(status.success());

pub fn spawn(&mut self) -> Result<Child>

Executes the command as a child process, returning a handle to it.

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

Examples

Basic usage:

use runas::Command;

Command::new("ls")
        .spawn()
        .expect("ls command failed to start");

pub fn status(&mut self) -> Result<ExitStatus>

Executes a command as a child process, waiting for it to finish and collecting its exit status.

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

Examples

use runas::Command;

let status = Command::new("/bin/cat")
                     .arg("file.txt")
                     .status()
                     .expect("failed to execute process");

println!("process exited with: {}", status);

assert!(status.success());