Procfs

https://docs.rs/procfs/latest/
Admin
This crate provides an interface to the Linux `procfs` filesystem, offering access to kernel data...
Tokens:6,558
Snippets:28
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get System Boot Time

Source: https://docs.rs/procfs/latest/procfs/trait

The `boot_time` method retrieves the system's boot time as a `DateTime<Local>`. It returns a `Result` which is either the `DateTime` or a `ProcError` if an error occurs during retrieval.

```Rust
fn boot_time(&self) -> Result<DateTime<Local>, ProcError>
```

--------------------------------

### Get System Cgroup Controllers - Rust

Source: https://docs.rs/procfs/latest/src/procfs/cgroups

Retrieves information about the cgroup controllers compiled into the kernel. This function reads from the /proc/cgroups file and requires the procfs_core crate.

```Rust
use crate::{Current, ProcResult};
use procfs_core::CGroupControllers;

/// Information about the cgroup controllers that are compiled into the kernel
///
/// (since Linux 2.6.24)
pub fn cgroups() -> ProcResult<CGroupControllers> {
    CGroupControllers::current()
}
```

--------------------------------

### Get Process Cgroups - Rust

Source: https://docs.rs/procfs/latest/src/procfs/cgroups

Describes the control groups to which a process belongs. The output format varies between cgroups version 1 and version 2 hierarchies. This method is part of the Process struct and reads from the 'cgroup' file for a given process.

```Rust
use super::process::Process;
use procfs_core::ProcessCGroups;

impl Process {
    /// Describes control groups to which the process with the corresponding PID belongs.
    ///
    /// The displayed information differs for cgroupsversion 1 and version 2 hierarchies.
    pub fn cgroups(&self) -> ProcResult<ProcessCGroups> {
        self.read("cgroup")
    }
}
```

--------------------------------

### Get max_user_watches

Source: https://docs.rs/procfs/latest/src/procfs/sys/fs/epoll

Retrieves the limit on the total number of file descriptors that a user can register across all epoll instances. This value is per real user ID and depends on kernel version and available memory.

```Rust
pub fn max_user_watches() -> ProcResult<u64> {
    read_value("/proc/sys/fs/epoll/max_user_watches")
}
```

--------------------------------

### SystemInfoInterface Trait Documentation

Source: https://docs.rs/procfs/latest/procfs/trait

Documentation for the SystemInfoInterface trait, which provides methods for retrieving system information. It is implemented for ExplicitSystemInfo and LocalSystemInfo.

```APIDOC
trait SystemInfoInterface {
    // ... other methods ...
    fn boot_time(&self) -> Result<DateTime<Local>, ProcError>;
    // ... other methods ...
}

// Implementors:
// impl SystemInfoInterface for ExplicitSystemInfo
// impl SystemInfoInterface for LocalSystemInfo
```

--------------------------------

### Procfs Keyring Tests

Source: https://docs.rs/procfs/latest/src/procfs/keyring

Unit tests for the procfs keyring module, demonstrating how to fetch and print key information and key user data.

```Rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_keys() {
        for key in keys().unwrap() {
            println!("{:#?}", key);
        }
    }

    #[test]
    fn test_key_users() {
        for (_user, data) in key_users().unwrap() {
            println!("{:#?}", data);
        }
    }
}
```

--------------------------------

### Procfs BinfmtMisc Tests

Source: https://docs.rs/procfs/latest/src/procfs/sys/fs/binfmt_misc

Contains tests for the binfmt_misc functionality within the procfs crate. It asserts the enabled status, interpreter path, and data extension of a binfmt_misc entry. It also includes a test to list and print all binfmt_misc entries.

```Rust
    #[test]
    fn test_binfmt_misc_entry() {
        // Assuming 'entry' is a valid BinFmtMiscEntry
        // let entry = ...;
        assert!(entry.enabled);
        assert_eq!(entry.interpreter, "/bin/hello");
        if let BinFmtData::Extension(ext) = entry.data {
            assert_eq!(ext, "hello");
        } else {
            panic!("Unexpected data");
        }
    }

    #[test]
    fn live() {
        for entry in super::list().unwrap() {
            println!("{:?}", entry);
        }
    }
```

--------------------------------

### SwapPageFlags Methods

Source: https://docs.rs/procfs/latest/procfs/process/struct

This section details the methods provided by the procfs crate's SwapPageFlags struct. These methods allow for manipulation and querying of swap page flags, including operations like checking for all flags, emptiness, intersections, unions, and retrieving specific swap information.

```APIDOC
SwapPageFlags:
  all() -> Self
    Returns a SwapPageFlags instance with all flags set.
  bits() -> u64
    Returns the raw bit representation of the flags.
  complement() -> Self
    Returns a SwapPageFlags instance with all flags complemented.
  contains(other: Self) -> bool
    Checks if this instance contains all flags set in another instance.
  difference(other: Self) -> Self
    Returns a SwapPageFlags instance representing the difference (flags in self but not in other).
  empty() -> Self
    Returns an empty SwapPageFlags instance.
  from_bits(bits: u64) -> Self
    Creates a SwapPageFlags instance from raw bits, ignoring unknown flags.
  from_bits_retain(bits: u64) -> Self
    Creates a SwapPageFlags instance from raw bits, retaining unknown flags.
  from_bits_truncate(bits: u64) -> Self
    Creates a SwapPageFlags instance from raw bits, truncating unknown flags.
  from_name(name: &str) -> Option<Self>
    Creates a SwapPageFlags instance from a flag name.
  get_swap_offset() -> u32
    Retrieves the swap offset.
  get_swap_type() -> u8
    Retrieves the swap type.
  insert(other: Self) -> Self
    Inserts flags from another instance into this one.
  intersection(other: Self) -> Self
    Returns a SwapPageFlags instance representing the intersection (common flags).
  intersects(other: Self) -> bool
    Checks if this instance shares any flags with another instance.
  is_all() -> bool
    Checks if all possible flags are set.
  is_empty() -> bool
    Checks if no flags are set.
  iter() -> impl Iterator<Item = Self>
    Returns an iterator over the set flags.
  iter_names() -> impl Iterator<Item = &'static str>
    Returns an iterator over the names of the set flags.
  remove(other: Self) -> Self
    Removes flags from another instance from this one.
  set(other: Self) -> Self
    Sets flags from another instance in this one.
  symmetric_difference(other: Self) -> Self
    Returns a SwapPageFlags instance representing the symmetric difference (flags in either, but not both).
  toggle(other: Self) -> Self
    Toggles flags from another instance in this one.
  union(other: Self) -> Self
    Returns a SwapPageFlags instance representing the union (all flags from both).
```

--------------------------------

### Procfs Sysctl Modules

Source: https://docs.rs/procfs/latest/src/procfs/sys/mod

This Rust code defines the sysctl interface for the procfs library, exposing kernel configuration variables through the /proc/sys/ directory. It includes submodules for filesystem, kernel, and virtual machine parameters.

```Rust
pub mod fs;
pub mod kernel;
pub mod vm;
```

--------------------------------

### SwapPageFlags Trait Implementations

Source: https://docs.rs/procfs/latest/procfs/process/struct

This section lists the standard and custom trait implementations for the SwapPageFlags struct. These traits enable functionalities such as binary representation, bitwise operations, cloning, debugging, serialization, and iteration.

```Rust
impl Binary for SwapPageFlags
impl BitAnd for SwapPageFlags
impl BitAndAssign for SwapPageFlags
impl BitOr for SwapPageFlags
impl BitOrAssign for SwapPageFlags
impl BitXor for SwapPageFlags
impl BitXorAssign for SwapPageFlags
impl Clone for SwapPageFlags
impl Copy for SwapPageFlags
impl Debug for SwapPageFlags
impl<'de> Deserialize<'de> for SwapPageFlags
impl Eq for SwapPageFlags
impl Extend<SwapPageFlags> for SwapPageFlags
impl Flags for SwapPageFlags
impl FromIterator<SwapPageFlags> for SwapPageFlags
impl Hash for SwapPageFlags
impl IntoIterator for SwapPageFlags
impl LowerHex for SwapPageFlags
impl Not for SwapPageFlags
impl Octal for SwapPageFlags
impl Ord for SwapPageFlags
impl PartialEq for SwapPageFlags
impl PartialOrd for SwapPageFlags
impl Serialize for SwapPageFlags
impl StructuralPartialEq for SwapPageFlags
impl Sub for SwapPageFlags
impl SubAssign for SwapPageFlags
impl UpperHex for SwapPageFlags
```

--------------------------------

### Tests for Reading Crypto Table

Source: https://docs.rs/procfs/latest/src/procfs/crypto

Contains a unit test to verify that the crypto() function successfully reads the /proc/crypto file and that the resulting table is not empty.

```Rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn read_crypto() {
        let table = crypto();
        let table = table.expect("CrytoTable should have been read");
        assert!(!table.crypto_blocks.is_empty(), "Crypto table was empty");
    }
```

--------------------------------

### Access Kernel Keys

Source: https://docs.rs/procfs/latest/src/procfs/keyring

Retrieves a list of keys for which the current thread has view permission. Each key's information includes its ID, type, usage, permissions, and description.

```Rust
use super::{Current, ProcResult};
use procfs_core::keyring::*;
use std::collections::HashMap;

impl Current for Keys {
    const PATH: &'static str = "/proc/keys";
}

/// Returns a list of the keys for which the reading thread has **view** permission, providing
/// various information about each key.
pub fn keys() -> ProcResult<Vec<Key>> {
    Keys::current().map(|k| k.0)
}
```

--------------------------------

### BinFmtFlags Methods - procfs

Source: https://docs.rs/procfs/latest/procfs/sys/fs/binfmt_misc/struct

This section documents the methods available for the BinFmtFlags struct in the procfs crate. These methods allow for manipulation and querying of binary format flags, including bitwise operations, set operations, and conversions from various representations.

```APIDOC
BinFmtFlags Methods:

all()
  Returns a BinFmtFlags with all bits set.

bits()
  Returns the underlying bits of the BinFmtFlags.

complement()
  Returns the bitwise complement of the BinFmtFlags.

contains(other: Self) -> bool
  Checks if this set contains all bits of another set.

difference(other: Self) -> Self
  Returns a new set with bits that are in this set but not in another.

empty() -> Self
  Returns an empty BinFmtFlags.

from_bits(bits: u64) -> Option<Self>
  Creates a BinFmtFlags from a u64, returning None if any bits are invalid.

from_bits_retain(bits: u64) -> Self
  Creates a BinFmtFlags from a u64, retaining all bits.

from_bits_truncate(bits: u64) -> Self
  Creates a BinFmtFlags from a u64, truncating invalid bits.

from_name(name: &str) -> Option<Self>
  Creates a BinFmtFlags from a string name, returning None if the name is unrecognized.

insert(&mut self, other: Self) -> bool
  Inserts bits from another set into this set, returning true if the set changed.

intersection(other: Self) -> Self
  Returns a new set with bits that are common to both sets.

intersects(other: Self) -> bool
  Checks if this set has any bits in common with another set.

is_all() -> bool
  Checks if all bits are set.

is_empty() -> bool
  Checks if the set is empty.

iter() -> Iter<'_, Self>
  Returns an iterator over the set bits.

iter_names() -> IterNames<'_, Self>
  Returns an iterator over the names of the set bits.

remove(&mut self, other: Self) -> bool
  Removes bits from another set from this set, returning true if the set changed.

set(&mut self, other: Self) -> bool
  Sets bits from another set into this set, returning true if the set changed.

symmetric_difference(other: Self) -> Self
  Returns a new set with bits that are in either set, but not both.

toggle(&mut self, other: Self) -> bool
  Toggles bits from another set in this set, returning true if the set changed.

union(other: Self) -> Self
  Returns a new set with bits from both sets.
```

--------------------------------

### Tests for Cgroup Functionality - Rust

Source: https://docs.rs/procfs/latest/src/procfs/cgroups

Contains unit tests for the cgroups and process_cgroups functions. These tests verify that the functions can be called and print the retrieved cgroup information.

```Rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_cgroups() {
        let groups = cgroups().unwrap();
        println!("{:?}", groups);
    }

    #[test]
    fn test_process_cgroups() {
        let myself = Process::myself().unwrap();
        let groups = myself.cgroups();
        println!("{:?}", groups);
    }
}
```

--------------------------------

### Access Key Users

Source: https://docs.rs/procfs/latest/src/procfs/keyring

Retrieves a map of user IDs to their associated key information. This function provides details on which users have keys on the system and their respective key data.

```Rust
use super::{Current, ProcResult};
use procfs_core::keyring::*;
use std::collections::HashMap;

impl Current for KeyUsers {
    const PATH: &'static str = "/proc/key-users";
}

/// Get various information for each user ID that has at least one key on the system.
pub fn key_users() -> ProcResult<HashMap<u32, KeyUser>> {
    KeyUsers::current().map(|k| k.0)
}
```

--------------------------------

### SwapPageFlags Auto Trait Implementations

Source: https://docs.rs/procfs/latest/procfs/process/struct

This section lists the auto trait implementations for the SwapPageFlags struct. These are automatically derived traits that indicate safety and concurrency properties.

```Rust
impl Freeze for SwapPageFlags
impl RefUnwindSafe for SwapPageFlags
impl Send for SwapPageFlags
impl Sync for SwapPageFlags
impl Unpin for SwapPageFlags
impl UnwindSafe for SwapPageFlags
```

--------------------------------

### Test System Request (sysrq)

Source: https://docs.rs/procfs/latest/src/procfs/sys/kernel/mod

Tests the functionality to retrieve system request (sysrq) information. It calls the sysrq function, unwraps the result, and prints the obtained information.

```Rust
    #[test]
    fn test_sysrq() {
        let sys_rq = sysrq().unwrap();
        println!("{:?}", sys_rq)
    }
```

--------------------------------

### ProcState Trait Implementations

Source: https://docs.rs/procfs/latest/procfs/process/enum

This section lists the standard trait implementations available for the ProcState enum in the procfs::process module. These traits enable fundamental behaviors like copying, debugging, and string conversion.

```Rust
impl Clone for ProcState
implements Clone

impl Copy for ProcState
implements Copy

impl Debug for ProcState
implements Debug

impl Eq for ProcState
implements Eq

impl FromStr for ProcState
implements FromStr

impl PartialEq for ProcState
implements PartialEq

impl StructuralPartialEq for ProcState
implements StructuralPartialEq
```

--------------------------------

### Read /proc/iomem

Source: https://docs.rs/procfs/latest/src/procfs/iomem

Reads and parses the /proc/iomem file. This function requires root privileges to access memory addresses correctly; otherwise, all addresses will be zero. It returns a Result containing a vector of tuples, where each tuple consists of a memory address (usize) and its corresponding PhysicalMemoryMap.

```Rust
use super::ProcResult;
use crate::Current;
use procfs_core::{Iomem, PhysicalMemoryMap};

impl Current for Iomem {
    const PATH: &'static str = "/proc/iomem";
}

/// Reads and parses the `/proc/iomem`, returning an error if there are problems.
///
/// Requires root, otherwise every memory address will be zero.
pub fn iomem() -> ProcResult<Vec<(usize, PhysicalMemoryMap)>> {
    Iomem::current().map(|v| v.0)
}
```

--------------------------------

### Rust BinFmtFlags Trait Implementations

Source: https://docs.rs/procfs/latest/procfs/sys/fs/binfmt_misc/struct

This section lists the implemented traits for the BinFmtFlags struct in the procfs library. These include standard traits like Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, and PartialOrd, as well as traits related to binary operations (BitAnd, BitOr, BitXor), hexadecimal formatting (LowerHex, UpperHex), and iterator functionality (Extend, FromIterator, IntoIterator).

```Rust
impl Binary for BinFmtFlags
impl BitAnd for BinFmtFlags
impl BitAndAssign for BinFmtFlags
impl BitOr for BinFmtFlags
impl BitOrAssign for BinFmtFlags
impl BitXor for BinFmtFlags
impl BitXorAssign for BinFmtFlags
impl Clone for BinFmtFlags
impl Copy for BinFmtFlags
impl Debug for BinFmtFlags
impl Eq for BinFmtFlags
impl Extend<BinFmtFlags> for BinFmtFlags
impl Flags for BinFmtFlags
impl FromIterator<BinFmtFlags> for BinFmtFlags
impl Hash for BinFmtFlags
impl IntoIterator for BinFmtFlags
impl LowerHex for BinFmtFlags
impl Not for BinFmtFlags
impl Octal for BinFmtFlags
impl Ord for BinFmtFlags
impl PartialEq for BinFmtFlags
impl PartialOrd for BinFmtFlags
impl PublicFlags for BinFmtFlags
impl StructuralPartialEq for BinFmtFlags
impl Sub for BinFmtFlags
impl SubAssign for BinFmtFlags
impl UpperHex for BinFmtFlags
```

--------------------------------

### Read Crypto Table

Source: https://docs.rs/procfs/latest/src/procfs/crypto

Provides a function to read the /proc/crypto file and return a CryptoTable. This implementation leverages the Current trait from procfs_core.

```Rust
use procfs_core::ProcResult;
pub use procfs_core::CryptoTable;

use crate::Current;

impl Current for CryptoTable {
    const PATH: &'static str = "/proc/crypto";
}

pub fn crypto() -> ProcResult<CryptoTable> {
    CryptoTable::current()
}
```

--------------------------------

### Test Shared Memory Settings (shmmni)

Source: https://docs.rs/procfs/latest/src/procfs/sys/kernel/mod

Tests the functionality to retrieve shared memory settings (shmmni). It calls the shmmni function and asserts that the operation is successful.

```Rust
    #[test]
    fn test_shmmni() {
        let _ = shmmni().unwrap();
    }
```

--------------------------------

### ProcState Blanket Implementations

Source: https://docs.rs/procfs/latest/procfs/process/enum

This section lists blanket implementations for the ProcState enum, which apply generic traits to the type.

```Rust
impl Any for T
implements Any

impl Borrow<T> for T
implements Borrow<T>

impl BorrowMut<T> for T
implements BorrowMut<T>

impl CloneToUninit for T
implements CloneToUninit

impl From<T> for T
implements From<T>

impl Into<U> for T
implements Into<U>

impl ToOwned for T
implements ToOwned

impl TryFrom<U> for T
implements TryFrom<U>

impl TryInto<U> for T
implements TryInto<U>
```

--------------------------------

### ProcState Auto Trait Implementations

Source: https://docs.rs/procfs/latest/procfs/process/enum

This section details the auto trait implementations for the ProcState enum. These are automatically derived traits that indicate safety and concurrency properties.

```Rust
impl Freeze for ProcState
implements Freeze

impl RefUnwindSafe for ProcState
implements RefUnwindSafe

impl Send for ProcState
implements Send

impl Sync for ProcState
implements Sync

impl Unpin for ProcState
implements Unpin

impl UnwindSafe for ProcState
implements UnwindSafe
```

--------------------------------

### Test max_user_watches

Source: https://docs.rs/procfs/latest/src/procfs/sys/fs/epoll

A test function to print the current value of max_user_watches if the kernel version is 2.6.28 or newer.

```Rust
#[test]
fn test_max_user_watches() {
    if KernelVersion::current().unwrap() >= KernelVersion::new(2, 6, 28) {
        println!("{}", max_user_watches().unwrap());
    }
}
```

--------------------------------

### Set max_user_watches

Source: https://docs.rs/procfs/latest/src/procfs/sys/fs/epoll

Sets the limit on the total number of file descriptors that a user can register across all epoll instances. This operation requires appropriate permissions.

```Rust
pub fn set_max_user_watches(val: u64) -> ProcResult<()> {
    write_value("/proc/sys/fs/epoll/max_user_watches", val)
}
```

--------------------------------

### Test Maximum Threads (threads_max)

Source: https://docs.rs/procfs/latest/src/procfs/sys/kernel/mod

Tests the functionality to retrieve the maximum number of threads (threads_max). It calls the threads_max function and asserts that the operation is successful.

```Rust
    #[test]
    fn test_threads_max() {
        let _ = threads_max().unwrap();
    }
```

--------------------------------

### DeserializeOwned for Generic Types

Source: https://docs.rs/procfs/latest/procfs/net/struct

Implements the DeserializeOwned trait for any type T that implements the Deserialize trait for any lifetime 'de. This is a common pattern when working with serialization and deserialization in Rust using the serde library.

```Rust
impl<T> DeserializeOwned for T
where
    T: for<'de> Deserialize<'de>,
```
Tokens:
Raw