Crate proc_connector 

proc-connector

A safe, modern Rust wrapper for the Linux Process Event Connector (netlink NETLINK_CONNECTOR + CN_IDX_PROC).

Provides full coverage of all 10+ kernel process event types via a type-safe, zero-overhead, and fully safe API.

Quick start

// Create connector (requires CAP_NET_ADMIN)
let conn = ProcConnector::new().expect("create connector");
let mut buf = vec![0u8; 4096];

// Blocking receive with timeout
match conn.recv_timeout(&mut buf, Duration::from_secs(1)) {
    Ok(Some(event)) => println!("got event: {event}"),
    Ok(None) => println!("timeout"),
    Err(e) => eprintln!("error: {e}"),
}

Async integration

let conn = ProcConnector::new().unwrap();
let raw_fd = conn.as_raw_fd();
// Use with tokio:
// let async_fd = tokio::io::unix::AsyncFd::new(conn).unwrap();

Design philosophy (inspired by fanotify-fid)

• Safe API: internal unsafe is confined to protocol parsing; callers receive a fully safe interface.
• Complete event coverage: all PROC_EVENT_* variants are exposed as a ProcEvent enum with structured fields.
• Zero-copy where possible: parsing happens only after a successful recv, with buffer ownership left to the caller.
• Async-ready: as_raw_fd() exposes the underlying socket fd for integration with tokio::AsyncFd, mio, or other event loops.
• No overreach: does NOT manage threads, cache /proc data, or impose any event processing policy.

Structs

NetlinkMessageIter

Iterator over multiple netlink messages packed into a single receive buffer.

ProcConnector

A safe handle to a Linux Netlink Proc Connector socket.

Enums

Error

Errors that can occur during proc connector operations.

ProcEvent

A parsed process event from the Linux Proc Connector.

Constants

CN_IDX_PROC

Connector index for process events.

CN_VAL_PROC

Connector value for process events.

COMM_DATA

COMM_PID

COMM_TGID

CONNECTOR_MAX_MSG_SIZE

Maximum message size for the connector protocol.

COREDUMP_PARENT_PID

COREDUMP_PARENT_TGID

COREDUMP_PID

COREDUMP_TGID

EXEC_PID

EXEC_TGID

EXIT_CODE

EXIT_PARENT_PID

EXIT_PARENT_TGID

EXIT_PID

EXIT_SIGNAL

EXIT_TGID

FORK_CHILD_PID

FORK_CHILD_TGID

FORK_PARENT_PID

FORK_PARENT_TGID

ID_EUID_EGID

ID_PID

ID_RUID_RGID

ID_TGID

NETLINK_CONNECTOR

Netlink protocol family for the Connector.

NETLINK_NO_ENOBUFS

NLMSG_ALIGNTO

NLMSG_DONE

NLMSG_ERROR

NLMSG_MIN_TYPE

Minimum valid message type for application-specific messages.

NLMSG_NOOP

NLMSG_OVERRUN

NLM_F_REQUEST

PROC_CN_MCAST_IGNORE

Multicast operation: stop listening.

PROC_CN_MCAST_LISTEN

Multicast operation: start listening.

PROC_EVENT_COMM

Process name (comm) changed.

PROC_EVENT_COREDUMP

Process dumped core.

PROC_EVENT_EXEC

A process executed a new program (exec).

PROC_EVENT_EXIT

Process exited.

PROC_EVENT_FORK

A process was forked.

PROC_EVENT_GID

Real/effective GID changed.

PROC_EVENT_HEADER_SIZE

Offset from proc_event base to event_data union.

PROC_EVENT_PTRACE

ptrace attach/detach.

PROC_EVENT_SID

Session ID changed.

PROC_EVENT_UID

Real/effective UID changed.

PTRACE_PID

PTRACE_TGID

PTRACE_TRACER_PID

PTRACE_TRACER_TGID

SID_PID

SID_TGID

SIZE_CN_MSG

Size of struct cn_msg header (excluding flexible data array).

SIZE_COMM_EVENT

SIZE_COREDUMP_EVENT

SIZE_EXEC_EVENT

SIZE_EXIT_EVENT

SIZE_FORK_EVENT

Per-event sub-structure sizes (all within the event_data union):

SIZE_ID_EVENT

SIZE_NLMSGHDR

Size of struct nlmsghdr in bytes (without alignment).

SIZE_PTRACE_EVENT

SIZE_SID_EVENT

Functions

nlmsg_align

Round len up to the nearest multiple of NLMSG_ALIGNTO.

nlmsg_hdrlen

Total header length of nlmsghdr after alignment.

nlmsg_length

Full message length: len bytes of payload plus aligned header.

Type Aliases

Result

Convenience alias for Result<T, Error>.