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(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 Polling
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 the polling infrastructure and a snapshot-delta helper, so you don't have to reimplement "read twice, subtract, divide by elapsed time" yourself.
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. For cumulative counters, pair it with Sampler<T> (from the watch feature): Sampler::update(snapshot) returns the previous snapshot along with the elapsed time between the two reads, leaving the subtraction and rate division to you.
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 |
tokio |
watch |
inotify-based Watcher API for regular files, plus Sampler<T> snapshot-delta helper |
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 polling 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;