Struct inotify::Inotify

pub struct Inotify(_);

Idiomatic Rust wrapper for Linux's inotify API

Inotify is a wrapper around an inotify instance. It generally tries to adhere to the underlying inotify API as closely as possible, while at the same time making access to it safe and convenient.

Please note that using inotify correctly is not always trivial, and while this wrapper tries to alleviate that, it is not perfect. Please refer to the inotify man pages for potential problems to watch out for.

Examples

use inotify::{
    Inotify,
    watch_mask,
};

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

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

// Read events that were added with `add_watch` 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
}

Methods

impl Inotify

fn init() -> Result<Inotify>

Creates an Inotify instance

Initializes an inotify instance by calling inotify_init1.

This method passes both flags accepted by inotify_init1, and doesn't allow the user any choice in the matter, as not passing any of the flags would be inappropriate in the context of this wrapper:

• IN_CLOEXEC prevents leaking file descriptors to other processes.
• IN_NONBLOCK controls the blocking behavior of the inotify API, which is entirely managed by this wrapper.

Errors

Directly returns the error from the call to inotify_init1, without adding any error conditions of its own.

Examples

use inotify::Inotify;

let inotify = Inotify::init()
    .expect("Failed to initialize an inotify instance");

fn add_watch<P>(&mut self, path: P, mask: WatchMask) -> Result<WatchDescriptor> where
    P: AsRef<Path>, 

Watches the file at the given path

Adds a watch for the file at the given path by calling inotify_add_watch. Returns a watch descriptor that can be used to refer to this watch later.

The mask argument defines what kind of changes the file should be watched for, and how to do that. See the documentation of WatchMask for details.

Errors

Directly returns the error from the call to inotify_add_watch, without adding any error conditions of its own.

Examples

use inotify::{
    Inotify,
    watch_mask,
};

let mut inotify = Inotify::init()
    .expect("Failed to initialize an inotify instance");

inotify.add_watch("/tmp/inotify-rs-test-file", watch_mask::MODIFY)
    .expect("Failed to add file watch");

// Handle events for the file here

fn rm_watch(&mut self, wd: WatchDescriptor) -> Result<()>

Stops watching a file

Removes the watch represented by the provided WatchDescriptor by calling inotify_rm_watch. You can obtain a WatchDescriptor by saving one returned by Inotify::add_watch or from the wd field of Event.

Errors

Directly returns the error from the call to inotify_rm_watch, without adding any error conditions of its own.

Examples

use inotify::Inotify;

let mut inotify = Inotify::init()
    .expect("Failed to initialize an inotify instance");

let mut buffer = [0; 1024];
let events = inotify
    .read_events_blocking(&mut buffer)
    .expect("Error while waiting for events");

for event in events {
    inotify.rm_watch(event.wd);
}

fn read_events_blocking<'a>(
    &mut self,
    buffer: &'a mut [u8]
) -> Result<Events<'a>>

Waits until events are available, then returns them

This method will block the current thread until at least one event is available. If this is not desirable, please take a look at read_events.

Errors

Directly returns the error from the call to read, without adding any error conditions of its own.

fn read_events<'a>(&mut self, buffer: &'a mut [u8]) -> Result<Events<'a>>

Returns any available events

Returns an iterator over all events that are currently available. If no events are available, an iterator is still returned.

The buffer argument, as the name indicates, is used as a buffer for the inotify events. Its contents may be overwritten.

If you need a method that will block until at least one event is available, please call read_events_blocking.

Errors

This function directly returns all errors from the call to read. In addition, ErrorKind::UnexpectedEof is returned, if the call to read returns 0, signaling end-of-file.

If buffer is too small, this will result in an error with ErrorKind::InvalidInput. On very old Linux kernels, ErrorKind::UnexpectedEof will be returned instead.

Examples

use inotify::Inotify;

let mut inotify = Inotify::init()
    .expect("Failed to initialize an inotify instance");

let mut buffer = [0; 1024];
let events = inotify.read_events(&mut buffer)
    .expect("Error while reading events");

for event in events {
    // Handle event
}

fn close(self) -> Result<()>

Closes the inotify instance

Closes the file descriptor referring to the inotify instance. The user usually doesn't have to call this function, as the underlying inotify instance is closed automatically, when Inotify is dropped.

Errors

Directly returns the error from the call to close, without adding any error conditions of its own.

Examples

use inotify::Inotify;

let mut inotify = Inotify::init()
    .expect("Failed to initialize an inotify instance");

inotify.close()
    .expect("Failed to close inotify instance");

unsafe fn fd(&mut self) -> &mut RawFd

Access inotify file descriptor

This method provides access to the inotify file descriptor. While this is not required for any of the tasks that are covered by this API, it might be necessary for providing additional features on top of it.

Safety

This function is marked unsafe, as direct access to the file descriptor allows for all kinds of actions that could cause Inotify to no longer work correctly. Please be aware of what you're doing, and how this might affect the inotify-rs code.

Trait Implementations

impl Drop for Inotify

fn drop(&mut self)

A method called when the value goes out of scope.