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

Offset to comm string (16 bytes) in comm event data.

COMM_PID

Offset to PID in comm event data.

COMM_TGID

Offset to TGID in comm event data.

CONNECTOR_MAX_MSG_SIZE

Maximum message size for the connector protocol.

COREDUMP_PARENT_PID

Offset to parent PID in coredump event data.

COREDUMP_PARENT_TGID

Offset to parent TGID in coredump event data.

COREDUMP_PID

Offset to PID in coredump event data.

COREDUMP_TGID

Offset to TGID in coredump event data.

EXEC_PID

Offset to PID in exec event data.

EXEC_TGID

Offset to TGID in exec event data.

EXIT_CODE

Offset to exit code in exit event data.

EXIT_PARENT_PID

Offset to parent PID in exit event data.

EXIT_PARENT_TGID

Offset to parent TGID in exit event data.

EXIT_PID

Offset to PID in exit event data.

EXIT_SIGNAL

Offset to exit signal in exit event data.

EXIT_TGID

Offset to TGID in exit event data.

FORK_CHILD_PID

Offset to child PID in fork event data.

FORK_CHILD_TGID

Offset to child TGID in fork event data.

FORK_PARENT_PID

Offset to parent PID in fork event data.

FORK_PARENT_TGID

Offset to parent TGID in fork event data.

ID_EUID_EGID

Offset to effective UID/GID in uid/gid event data.

ID_PID

Offset to PID in uid/gid event data.

ID_RUID_RGID

Offset to real UID/GID in uid/gid event data.

ID_TGID

Offset to TGID in uid/gid event data.

NETLINK_CONNECTOR

Netlink protocol family for the Connector.

NETLINK_NO_ENOBUFS

Socket option to disable ENOBUFS errors on recv.

NLMSG_ALIGNTO

Alignment boundary for netlink message headers (4 bytes).

NLMSG_DONE

Done message type: marks the end of a multi-part message.

NLMSG_ERROR

Error message type: contains nlmsgerr struct.

NLMSG_MIN_TYPE

Minimum valid message type for application-specific messages.

NLMSG_NOOP

No-operation message type (ignored by netlink).

NLMSG_OVERRUN

Overrun message type: data was lost due to buffer overflow.

NLM_F_REQUEST

Netlink message flag: this is a request message.

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

Offset to PID in ptrace event data.

PTRACE_TGID

Offset to TGID in ptrace event data.

PTRACE_TRACER_PID

Offset to tracer PID in ptrace event data.

PTRACE_TRACER_TGID

Offset to tracer TGID in ptrace event data.

SID_PID

Offset to PID in session ID event data.

SID_TGID

Offset to TGID in session ID event data.

SIZE_CN_MSG

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

SIZE_COMM_EVENT

Size of comm event data (2 × i32 + char[16]: pid, tgid, comm).

SIZE_COREDUMP_EVENT

Size of coredump event data (4 × i32: pid, tgid, parent_pid, parent_tgid).

SIZE_EXEC_EVENT

Size of exec event data (2 × i32: pid, tgid).

SIZE_EXIT_EVENT

Size of exit event data (4 × i32 + u32 + u32: pid, tgid, exit_code, exit_signal, parent_pid, parent_tgid).

SIZE_FORK_EVENT

Per-event sub-structure sizes (all within the event_data union): Size of fork event data (4 × i32: parent_pid, parent_tgid, child_pid, child_tgid).

SIZE_ID_EVENT

Size of uid/gid event data (2 × i32 + ruid/rgid union + euid/egid union).

SIZE_NLMSGHDR

Size of struct nlmsghdr in bytes (without alignment).

SIZE_PTRACE_EVENT

Size of ptrace event data (4 × i32: pid, tgid, tracer_pid, tracer_tgid).

SIZE_SID_EVENT

Size of session ID event data (2 × i32: pid, tgid).

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.

parse_cn_msg

Parse a cn_msg payload (starting from cb_id) into a ProcEvent.

parse_netlink_message

Parse a single netlink message payload (starting after nlmsghdr) into a ProcEvent.

Type Aliases

Result

Convenience alias for Result<T, Error>.