proc_connector/lib.rs
1//! # proc-connector
2//!
3//! A safe, modern Rust wrapper for the **Linux Process Event Connector**
4//! (netlink `NETLINK_CONNECTOR` + `CN_IDX_PROC`).
5//!
6//! Provides full coverage of all kernel process event types via a
7//! type-safe, zero-overhead API.
8//!
9//! **Linux only.** Compilation on non-Linux platforms will fail with a
10//! clear error message.
11//!
12//! ## Quick start
13//!
14//! ```no_run
15//! # use proc_connector::{ProcConnector, ProcEvent};
16//! # use std::time::Duration;
17//!
18//! // Create connector (requires CAP_NET_ADMIN)
19//! let conn = ProcConnector::new().expect("create connector");
20//! let mut buf = vec![0u8; 4096];
21//!
22//! // Blocking receive with timeout
23//! match conn.recv_timeout(&mut buf, Duration::from_secs(1)) {
24//! Ok(Some(event)) => println!("got event: {event}"),
25//! Ok(None) => println!("timeout"),
26//! Err(e) => eprintln!("error: {e}"),
27//! }
28//! ```
29//!
30//! ## Async integration
31//!
32//! ```no_run
33//! # use proc_connector::ProcConnector;
34//! # use std::os::fd::AsRawFd;
35//! let conn = ProcConnector::new().unwrap();
36//! let raw_fd = conn.as_raw_fd();
37//! // Use with tokio:
38//! // let async_fd = tokio::io::unix::AsyncFd::new(conn).unwrap();
39//! ```
40//!
41//! ## Design philosophy (inspired by `fanotify-fid`)
42//!
43//! - **Safe API**: internal `unsafe` is confined to protocol parsing;
44//! callers receive a fully safe interface.
45//! - **Complete event coverage**: all `PROC_EVENT_*` variants are exposed
46//! as a `ProcEvent` enum with structured fields.
47//! - **Zero-copy where possible**: parsing happens only after a successful
48//! `recv`, with buffer ownership left to the caller.
49//! - **Async-ready**: `as_raw_fd()` exposes the underlying socket fd for
50//! integration with `tokio::AsyncFd`, `mio`, or other event loops.
51//! - **No overreach**: does NOT manage threads, cache `/proc` data, or
52//! impose any event processing policy.
53
54#[cfg(not(target_os = "linux"))]
55compile_error!("proc-connector only supports Linux");
56
57mod consts;
58mod error;
59mod iter;
60mod parse;
61mod proc_event;
62mod socket;
63
64// Re-exports — the full public API
65pub use consts::*;
66pub use error::{Error, Result};
67pub use iter::NetlinkMessageIter;
68pub use parse::{parse_cn_msg, parse_netlink_message};
69pub use proc_event::ProcEvent;
70pub use socket::{EventMask, ProcConnector};