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 10+ kernel process event types via a
7//! type-safe, zero-overhead, and fully safe API.
8//!
9//! ## Quick start
10//!
11//! ```no_run
12//! # use proc_connector::{ProcConnector, ProcEvent};
13//! # use std::time::Duration;
14//!
15//! // Create connector (requires CAP_NET_ADMIN)
16//! let conn = ProcConnector::new().expect("create connector");
17//! let mut buf = vec![0u8; 4096];
18//!
19//! // Blocking receive with timeout
20//! match conn.recv_timeout(&mut buf, Duration::from_secs(1)) {
21//! Ok(Some(event)) => println!("got event: {event}"),
22//! Ok(None) => println!("timeout"),
23//! Err(e) => eprintln!("error: {e}"),
24//! }
25//! ```
26//!
27//! ## Async integration
28//!
29//! ```no_run
30//! # use proc_connector::ProcConnector;
31//! # use std::os::fd::AsRawFd;
32//! let conn = ProcConnector::new().unwrap();
33//! let raw_fd = conn.as_raw_fd();
34//! // Use with tokio:
35//! // let async_fd = tokio::io::unix::AsyncFd::new(conn).unwrap();
36//! ```
37//!
38//! ## Design philosophy (inspired by `fanotify-fid`)
39//!
40//! - **Safe API**: internal `unsafe` is confined to protocol parsing;
41//! callers receive a fully safe interface.
42//! - **Complete event coverage**: all `PROC_EVENT_*` variants are exposed
43//! as a `ProcEvent` enum with structured fields.
44//! - **Zero-copy where possible**: parsing happens only after a successful
45//! `recv`, with buffer ownership left to the caller.
46//! - **Async-ready**: `as_raw_fd()` exposes the underlying socket fd for
47//! integration with `tokio::AsyncFd`, `mio`, or other event loops.
48//! - **No overreach**: does NOT manage threads, cache `/proc` data, or
49//! impose any event processing policy.
50
51mod consts;
52mod error;
53mod event;
54mod socket;
55
56// Re-exports — the full public API
57pub use consts::*;
58pub use error::{Error, Result};
59pub use event::{NetlinkMessageIter, ProcEvent};
60pub use socket::ProcConnector;