Crate inotify 

Idiomatic inotify wrapper for the Rust programming language

About

inotify-rs is an idiomatic wrapper around the Linux kernel’s inotify API for the Rust programming language. It can be used for monitoring changes to files or directories.

The Inotify struct is the main entry point into the API. The EventStream struct is designed to be used with async streams.

Examples

If you just want to synchronously retrieve events

use inotify::{
    Inotify,
    WatchMask,
};

let mut inotify = Inotify::init()
    .expect("Error while initializing inotify instance");

// Watch for modify and close events.
inotify
    .watches()
    .add(
        "/tmp/inotify-rs-test-file",
        WatchMask::MODIFY | WatchMask::CLOSE,
    )
    .expect("Failed to add file watch");

// Read events that were added with `Watches::add` above.
let mut buffer = [0; 1024];
let events = inotify.read_events_blocking(&mut buffer)
    .expect("Error while reading events");

for event in events {
    // Handle event
}

When you want to read events asynchronously, you need to convert it to EventStream. The transform function is Inotify::into_event_stream

let mut buffer = [0; 1024];
let mut stream = inotify.into_event_stream(&mut buffer)
    .expect("Error converting to stream");

// Read events from async stream
while let Some(event_or_error) = stream.next().await {
    println!("event: {:?}", event_or_error.expect("Stream error"));
}

Attention: inotify gotchas

inotify (as in, the Linux API, not this wrapper) has many edge cases, making it hard to use correctly. This can lead to weird and hard to find bugs in applications that are based on it. inotify-rs does its best to fix these issues, but sometimes this would require an amount of runtime overhead that is just unacceptable for a low-level wrapper such as this.

We’ve documented any issues that inotify-rs has inherited from inotify, as far as we are aware of them. Please watch out for any further warnings throughout this documentation. If you want to be on the safe side, in case we have missed something, please read the inotify man pages carefully.

Vec as buffers

Using a Vec::with_capacity(4096) as a buffer is problematic, since this buffer has reserved capacity but length 0. Use vec![0u8; 4096] instead.

Structs

Event

An inotify event

EventAuxiliaryFlags

Auxiliary flags for inotify events

EventMask

Indicates the type of an event

EventStream

Stream of inotify events

Events

Iterator over inotify events

Inotify

Idiomatic Rust wrapper around Linux’s inotify API

ParsedEventMask

A struct that provides structured access to event masks returned from reading an event from an inotify fd

WatchDescriptor

Represents a watch on an inode

WatchMask

Describes a file system watch

Watches

Interface for adding and removing watches

Enums

EventKind

Represents the type of inotify event

EventMaskParseError

An error that occured from parsing an raw event mask

Functions

get_absolute_path_buffer_size

Get the inotify event buffer size for an absolute path

get_buffer_size

Get the inotify event buffer size

Type Aliases

EventOwned

An owned version of Event