run_as/
lib.rs

1//! This library implements basic support for running a command in an elevated context.
2//!
3//! In particular this runs a command through "sudo" or other platform equivalents.
4//!
5//! ## Basic Usage
6//!
7//! The library provides a single struct called `Command` which largely follows the
8//! API of `std::process::Command`.  However it does not support capturing output or
9//! gives any guarantees for the working directory or environment.  This is because
10//! the platform APIs do not have support for that either in some cases.
11//!
12//! In particular the working directory is always the system32 folder on windows and
13//! the environment variables are always the ones of the initial system session on
14//! OS X if the GUI mode is used.
15//!
16//! ```rust,no_run
17//! use run_as::Command;
18//!
19//! let status = Command::new("rm")
20//!     .arg("/usr/local/my-app")
21//!     .status()
22//!     .unwrap();
23//! ```
24//!
25//! ## Platform Support
26//!
27//! The following platforms are supported:
28//!
29//! * Windows: always GUI mode
30//! * OS X: GUI and CLI mode
31//! * Linux: GUI and CLI mode
32
33use std::ffi::{OsStr, OsString};
34
35#[cfg(target_os = "macos")]
36mod impl_darwin;
37#[cfg(unix)]
38mod impl_unix;
39#[cfg(windows)]
40mod impl_windows;
41
42#[cfg(unix)]
43pub use crate::impl_unix::is_elevated;
44
45#[cfg(windows)]
46pub use crate::impl_windows::is_elevated;
47
48/// A process builder for elevated execution
49pub struct Command {
50    command: OsString,
51    args: Vec<OsString>,
52    force_prompt: bool,
53    hide: bool,
54    gui: bool,
55    wait_to_complete: bool,
56}
57
58/// The `Command` type acts as a process builder for spawning programs that run in
59/// an elevated context.
60///
61/// Example:
62///
63/// ```rust,no_run
64/// use run_as::Command;
65/// let status = Command::new("cmd").status();
66/// ```
67impl Command {
68    /// Creates a new command type for a given program.
69    ///
70    /// The default configuration is to spawn without arguments, to be visible and
71    /// to not be launched from a GUI context.
72    pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
73        Command {
74            command: program.as_ref().to_os_string(),
75            args: vec![],
76            hide: false,
77            gui: false,
78            force_prompt: true,
79            wait_to_complete: true,
80        }
81    }
82
83    /// Add an argument to pass to the program.
84    pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command {
85        self.args.push(arg.as_ref().to_os_string());
86        self
87    }
88
89    /// Add multiple arguments to pass to the program.
90    pub fn args<S: AsRef<OsStr>>(&mut self, args: &[S]) -> &mut Command {
91        for arg in args {
92            self.arg(arg);
93        }
94        self
95    }
96
97    /// Controls the visibility of the program on supported platforms.  The default is
98    /// to launch the program visible.
99    pub fn show(&mut self, val: bool) -> &mut Command {
100        self.hide = !val;
101        self
102    }
103
104    /// Controls the GUI context.  The default behavior is to assume that the program is
105    /// launched from a command line (not using a GUI).  This primarily controls how the
106    /// elevation prompt is rendered.  On some platforms like Windows the elevation prompt
107    /// is always a GUI element.
108    ///
109    /// If the preferred mode is not available it falls back to the other automatically.
110    pub fn gui(&mut self, val: bool) -> &mut Command {
111        self.gui = val;
112        self
113    }
114
115    /// Can disable the prompt forcing for supported platforms.  Mostly this allows sudo
116    /// on unix platforms to not prompt for a password.
117    pub fn force_prompt(&mut self, val: bool) -> &mut Command {
118        self.force_prompt = val;
119        self
120    }
121
122    /// Controls whether to wait for the command to complete.  The default is to wait.
123    /// If set to false the command is started and the function returns immediately.
124    /// The exit status in that case is always reported as success.
125    pub fn wait_to_complete(&mut self, val: bool) -> &mut Command {
126        self.wait_to_complete = val;
127        self
128    }
129
130    /// Executes a command as a child process, waiting for it to finish and
131    /// collecting its exit status.
132    pub fn status(&mut self) -> std::io::Result<std::process::ExitStatus> {
133        #[cfg(all(unix, target_os = "macos"))]
134        use crate::impl_darwin::runas_impl;
135        #[cfg(all(unix, not(target_os = "macos")))]
136        use impl_unix::runas_impl;
137        #[cfg(windows)]
138        use impl_windows::runas_impl;
139        runas_impl(self)
140    }
141}
run_as/lib.rs

run_as/
lib.rs
