Skip to main content

sys_lib/process/
mod.rs

1//! This process: its id, the user it runs as, whether it is elevated, and the
2//! process guard every long-running service starts with.
3//!
4//! sys-lib does not list or inspect other processes.
5//!
6//! ```
7//! use sys_lib as sys;
8//!
9//! println!("pid {} as {}", sys::process::id(), sys::process::user()?.name);
10//! if sys::process::is_elevated()? {
11//!     println!("running as root or an elevated Administrator");
12//! }
13//! # Ok::<(), sys_lib::Error>(())
14//! ```
15
16#[cfg(feature = "guard")]
17mod guard;
18
19#[cfg(feature = "guard")]
20#[cfg_attr(docsrs, doc(cfg(feature = "guard")))]
21pub use guard::{Guard, GuardBuilder, GuardReport, GuardWarning, guard};
22
23use crate::Result;
24
25/// This process's id.
26#[must_use]
27pub fn id() -> u32 {
28    std::process::id()
29}
30
31/// A user account.
32#[derive(Clone, Debug, PartialEq, Eq)]
33#[non_exhaustive]
34pub struct User {
35    /// The account name.
36    pub name: String,
37    /// The numeric user id (Unix); `None` on Windows, where accounts are SIDs.
38    pub id: Option<u32>,
39    /// Root, or an Administrator with an elevated token.
40    pub is_admin: bool,
41}
42
43/// The effective user this process runs as now.
44///
45/// On Linux and macOS the name comes from the system's user database (NSS),
46/// which can read `/etc/passwd` or, with directory-service users, wait on the
47/// network: keep it off hot paths. A user id without an entry gives its number
48/// as the name.
49///
50/// # Errors
51///
52/// `Os` when the user cannot be looked up.
53pub fn user() -> Result<User> {
54    crate::sys::user()
55}
56
57/// Whether this process runs as root, or with an elevated Administrator token.
58///
59/// This is a check, not a control: privilege drops belong to shield-sec, which
60/// calls this afterwards to verify.
61///
62/// ```
63/// if sys_lib::process::is_elevated()? {
64///     // refuse to serve requests until privileges are dropped
65/// }
66/// # Ok::<(), sys_lib::Error>(())
67/// ```
68///
69/// # Errors
70///
71/// `Os` when the token cannot be queried (Windows).
72pub fn is_elevated() -> Result<bool> {
73    crate::sys::is_elevated()
74}
75
76/// A resource limit: soft and hard values, `None` meaning unlimited or not
77/// applicable.
78#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
79#[non_exhaustive]
80pub struct Limit {
81    /// The limit in force.
82    pub soft: Option<u64>,
83    /// The ceiling the soft limit may be raised to without privileges.
84    pub hard: Option<u64>,
85}
86
87#[cfg(test)]
88mod tests {
89    use super::*;
90
91    #[test]
92    fn test_process_id_matches_std() {
93        assert_eq!(id(), std::process::id());
94    }
95
96    #[test]
97    fn test_process_user_has_a_name() {
98        let u = user().unwrap();
99        assert!(!u.name.is_empty());
100        assert_eq!(u.is_admin, is_elevated().unwrap());
101        if cfg!(unix) {
102            assert!(u.id.is_some());
103        }
104    }
105}