Crate fanotify_fid 

fanotify-fid

Linux fanotify FID (File Identifier) mode event parser and file handle utilities.

This crate fills the gap left by fanotify-rs, which only supports non-FID (legacy) event reading. If you pass FAN_REPORT_FID / FAN_REPORT_DIR_FID / FAN_REPORT_NAME to fanotify_init, you must use this crate (or equivalent code) to correctly parse the variable-length events.

Requirements

• Linux kernel ≥ 5.1 (FID mode), ≥ 5.15 (FAN_REPORT_TARGET_FID)
• CAP_SYS_ADMIN capability (run as root)
• Minimum Rust version: 1.75 (edition 2024)

Error handling

All operations return Result<T, FanotifyError>. Each error variant includes the raw errno and a man-page-level description explaining the cause, common pitfalls, and how to fix it.

Quick start

use fanotify_fid::prelude::*;
use std::os::fd::OwnedFd;


// 1. Create fanotify group in FID mode
let fan = Fanotify::new()
    .nonblock()
    .report_fid()
    .report_dir_fid()
    .report_name()
    .init()
    .unwrap();

// 2. Add marks (whole filesystem)
fan.mark(FAN_MARK_ADD | FAN_MARK_FILESYSTEM,
         FAN_CREATE | FAN_DELETE | FAN_MODIFY,
         "/").unwrap();

// 3. Open mount fds for handle resolution
let mount_fds = vec![open_mount("/")];

// 4. Read events
let mut buf = Vec::with_capacity(65536);
let events = fan.read_events(&mount_fds, &mut buf, None).unwrap();

for ev in &events {
    println!("{:?} {:?}", ev.event_names(), ev.path);
}

Modules

consts

FAN_* constants from Linux kernel UAPI (linux/fanotify.h).

handle

Safe wrappers around name_to_handle_at and open_by_handle_at.

parse

Low-level parsing of fanotify FID-format events from a raw byte buffer.

prelude

Convenience re-exports for the most common types and constants.

read

High-level fanotify FID event reader.

types

Kernel data structures and parsed event types for fanotify FID mode.

Structs

Fanotify

An RAII fanotify file descriptor with safe mark and read_events methods.

FanotifyBuilder

Builder for Fanotify.

Enums

FanotifyError

Error type for all fanotify operations.

Functions

fanotify_init

Thin safe wrapper around fanotify_init (raw syscall).

fanotify_mark

Thin safe wrapper around fanotify_mark (raw syscall).

open_mount

Open a path with O_PATH to obtain a mount fd for handle resolution.

Type Aliases

Result

Alias for Result<T, FanotifyError>.