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}