Skip to main content

sys_lib/
host.rs

1//! The machine and its environment.
2//!
3//! ```
4//! use sys_lib as sys;
5//!
6//! println!("running on {}", sys::host::name()?);
7//! # Ok::<(), sys_lib::Error>(())
8//! ```
9
10use core::time::Duration;
11use std::time::SystemTime;
12
13use crate::Result;
14
15/// The host name. A live reading: DHCP and `hostnamectl` change it while
16/// processes run. A name that is not UTF-8 is converted lossily, and one
17/// longer than 255 bytes is truncated (E-95).
18///
19/// The host name is an identifying value: keep it out of output that leaves
20/// the machine unless that is intended.
21///
22/// # Errors
23///
24/// `NotFound` or `PermissionDenied` when a sandbox hides it; `Os` when the
25/// system call fails.
26pub fn name() -> Result<String> {
27    crate::sys::host_name()
28}
29
30/// The time since the machine booted, including time suspended: monotonic.
31///
32/// ```
33/// println!("up {:?}", sys_lib::host::uptime()?);
34/// # Ok::<(), sys_lib::Error>(())
35/// ```
36///
37/// # Errors
38///
39/// `Os` when the clock cannot be read.
40pub fn uptime() -> Result<Duration> {
41    crate::sys::uptime()
42}
43
44/// When the machine booted: stable when the wall clock steps.
45///
46/// # Errors
47///
48/// `NotFound` when the boot time is hidden; `Malformed`; `Os`.
49pub fn boot_time() -> Result<SystemTime> {
50    crate::sys::boot_time()
51}
52
53/// How many processes and threads the machine runs. Totals only: no process
54/// is listed or inspected.
55#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
56#[non_exhaustive]
57pub struct Processes {
58    /// Processes. Inside a container, the container's process namespace.
59    pub total: u64,
60    /// Threads, when reported.
61    pub threads: Option<u64>,
62    /// Runnable right now, when reported (Linux).
63    pub running: Option<u64>,
64}
65
66/// How many processes and threads the machine runs.
67///
68/// ```
69/// let p = sys_lib::host::processes()?;
70/// println!("{} processes, {:?} threads", p.total, p.threads);
71/// # Ok::<(), sys_lib::Error>(())
72/// ```
73///
74/// # Errors
75///
76/// `TooLarge` past 4 million processes (Linux); `NotFound`; `Os`.
77pub fn processes() -> Result<Processes> {
78    crate::sys::processes()
79}
80
81/// How many files are open across the machine.
82#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
83#[non_exhaustive]
84pub struct OpenFiles {
85    /// Open now (Windows: handles).
86    pub open: Option<u64>,
87    /// The system-wide maximum (Windows has none).
88    pub max: Option<u64>,
89}
90
91/// How many files are open across the machine, and the maximum.
92///
93/// # Errors
94///
95/// `NotFound`; `Malformed`; `Os`.
96pub fn open_files() -> Result<OpenFiles> {
97    crate::sys::host_open_files()
98}
99
100#[cfg(test)]
101mod tests {
102    #[test]
103    fn test_host_counts_and_clocks_live() {
104        let up = super::uptime().unwrap();
105        assert!(up.as_secs() > 0);
106        let boot = super::boot_time().unwrap();
107        assert!(boot < std::time::SystemTime::now());
108        let p = super::processes().unwrap();
109        assert!(p.total >= 1);
110        if let Some(t) = p.threads {
111            assert!(t >= p.total);
112        }
113        let f = super::open_files().unwrap();
114        if let (Some(open), Some(max)) = (f.open, f.max) {
115            assert!(open <= max);
116        }
117    }
118
119    #[test]
120    fn test_host_name_is_not_empty() {
121        let name = super::name().unwrap();
122        assert!(!name.is_empty() && name.len() <= 255);
123    }
124}