procfs2
A modern, zero-copy, strongly-typed Rust library for reading Linux's /proc and /sys virtual filesystems.
Features
- Native async support — Not just async file reads: a generic polling combinator (
watch()) turns any snapshot function into aStream, plus purpose-built delta-streaming for cumulative counters (see Live Monitoring) - Granular, typed errors — Distinguishes why an operation failed (process exited mid-read, unsupported kernel, permission denied, malformed data at a specific line) instead of a single generic I/O failure
- Runtime-safe — No panics in the core parsing paths; all errors returned as typed
Errorvariants - Typed API — Every kernel file maps to a concrete Rust struct or enum
- Zero-copy where possible — Parse directly from
&[u8]slices - Broad
/proccoverage — System-wide, per-process, network, cgroups - First-class
/syssupport — Block devices, network interfaces, power supply, CPU info
Quick Start
use proc;
Live Monitoring / Async Delta-Streaming
Most /proc counters (network bytes, disk I/O, CPU jiffies) are cumulative — what you usually want is a rate, not a raw snapshot. procfs2 provides this as a first-class primitive instead of leaving it to every caller to reimplement "read twice, subtract, divide by elapsed time."
use ;
use ;
use Arc;
use ;
use Duration;
/// A waker that never wakes anything. Polling the stream with it just runs
/// until the next snapshot is ready, so no external `StreamExt` is needed.
;
async
async_helpers::watch() is a generic polling combinator — it accepts any async fn() -> Result<T> and turns it into a Stream<Item = Result<T>> on a fixed interval. Layer Sampler<T> on top for automatic, wraparound-safe delta computation between consecutive snapshots.
This requires the async feature. procfs has no async or streaming API at all — everything above is a pattern procfs2 supports natively rather than something you'd hand-roll on top of a sync-only crate.
Note on inotify: Linux's
inotifydoes not reliably fire on most/procentries — the kernel allocates a fresh inode on most procfs opens, which inotify can't attach persistent watches to. procfs2 includes an inotifyWatcher(under thewatchfeature) for watching regular files, but/procmonitoring should go throughasync_helpers::watch()above, not inotify.
Installation
Add to your Cargo.toml:
[]
= "0.2"
Feature Flags
Enable additional features as needed:
[]
= "0.2"
= ["async", "serde", "macros", "watch"]
| Feature | Description | Extra Dependencies |
|---|---|---|
async |
Async read variants, generic watch() polling combinator, delta-streaming (Sampler, NetDeltaSample) |
tokio |
watch |
inotify-based Watcher API for regular files |
libc |
serde |
Serialize/Deserialize on all structs |
serde |
macros |
#[derive(ProcKeyValue)] proc-macro |
procfs2-macros |
Module Overview
/proc Module
System-wide
proc::uptime()—Uptime { total, idle }from/proc/uptimeproc::loadavg()—LoadAvg { one, five, fifteen, runnable, total }from/proc/loadavgproc::meminfo()—MemInfo { total, free, available, ... }from/proc/meminfoproc::stat()—Stat { cpu_total, per_cpu, ctxt, btime, ... }from/proc/statproc::cpuinfo()—Vec<CpuCore>from/proc/cpuinfoproc::version()—KernelVersionfrom/proc/versionproc::mounts()—Vec<Mount>from/proc/mountsproc::cgroups()—Vec<Cgroup>from/proc/cgroupsmore...
Per-Process (Process)
use Process;
Network (proc::net)
proc::net::tcp()—/proc/net/tcp(IPv4 TCP connections)proc::net::tcp6()—/proc/net/tcp6(IPv6 TCP connections)proc::net::udp()—/proc/net/udp(IPv4 UDP sockets)proc::net::udp6()—/proc/net/udp6(IPv6 UDP sockets)proc::net::unix()—/proc/net/unix(Unix domain sockets)proc::net::dev()—/proc/net/dev(per-interface stats)proc::net::arp()—/proc/net/arp(ARP table)proc::net::route()—/proc/net/route(routing table)more...
/sys Module
sys::BlockDevice::all()—/sys/block/*(disk stats, queue params, size)sys::NetInterface::all()—/sys/class/net/*(stats, operstate, MAC, MTU, flags, speed)sys::PowerSupply::all()—/sys/class/power_supply/*(type, status, capacity, voltage, current)sys::cpu_count()— Number of online CPUssys::online_cpus()—Vec<u32>of online CPU IDssys::cpu_freq(cpu)—CpuFreqInfofor a specific CPU
Unit Types
All numeric values carry their unit in the type:
use proc;
Error Handling
All operations return procfs2::Result<T>, which is Result<T, procfs2::Error>. Errors are structured by cause rather than collapsed into a single generic I/O failure — a caller can distinguish, for example, "the process exited mid-read" from "this kernel doesn't support this file" from "malformed data on line N," and handle each differently:
Where kernel formats evolve incrementally (e.g. /proc/diskstats gaining trailing fields on newer kernels), procfs2 prefers detecting the file's actual shape over hard version-gating — so a file with fewer fields on an older kernel returns partial data (Option<T> on the newer fields) instead of failing outright.
Minimum Supported Rust Version
Rust 1.86 — verified in CI by building with the 1.86.0 toolchain.
License
Licensed under the MIT License.
Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
Building
# Clone the repository
# Build with default features
# Build with all features
# Run tests (requires Linux)
# Run clippy
Running the Demo
A small CLI that dumps system info is included as an example:
Async delta-streaming and inotify examples are also included:
Running Benchmarks
Proc-Macro (Optional)
The #[derive(ProcKeyValue)] macro is in the procfs2-macros crate.
Enable with the macros feature:
use ProcKeyValue;