Struct inotify::Inotify

pub struct Inotify { /* fields omitted */ }

Idiomatic Rust wrapper around Linux’s inotify API

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

Please refer to the top-level documentation for further details and a usage example.

Implementations

impl Inotify

pub 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, not giving the user any choice in the matter, as not passing 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");

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

Adds or updates a watch for the given path

Adds a new watch or updates an existing one for the file referred to by path. 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.

If this method is used to add a new watch, a new WatchDescriptor is returned. If it is used to update an existing watch, a WatchDescriptor that equals the previously returned WatchDescriptor for that watch is returned instead.

Under the hood, this method just calls inotify_add_watch and does some trivial translation between the types on the Rust side and the C side.

Attention: Updating watches and hardlinks

As mentioned above, this method can be used to update an existing watch. This is usually done by calling this method with the same path argument that it has been called with before. But less obviously, it can also happen if the method is called with a different path that happens to link to the same inode.

You can detect this by keeping track of WatchDescriptors and the paths they have been returned for. If the same WatchDescriptor is returned for a different path (and you haven’t freed the WatchDescriptor by removing the watch), you know you have two paths pointing to the same inode, being watched by the same watch.

Errors

Directly returns the error from the call to inotify_add_watch (translated into an io::Error), without adding any error conditions of its own.

Examples

use inotify::{
    Inotify,
    WatchMask,
};

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

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

// Handle events for the file here

pub 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. WatchDescriptors can be obtained via Inotify::add_watch, or from the wd field of Event.

Errors

Directly returns the error from the call to inotify_rm_watch. Returns an io::Error with ErrorKind::InvalidInput, if the given WatchDescriptor did not originate from this Inotify instance.

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);
}

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

Waits until events are available, then returns them

Blocks the current thread until at least one event is available. If this is not desirable, please consider Inotify::read_events.

This method calls Inotify::read_events internally and behaves essentially the same, apart from the blocking behavior. Please refer to the documentation of Inotify::read_events for more information.

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

Returns one buffer’s worth of available events

Reads as many events as possible into buffer, and returns an iterator over them. If no events are available, an iterator is still returned. If you need a method that will block until at least one event is available, please consider read_events_blocking.

Please note that inotify will merge identical successive unread events into a single event. This means this method can not be used to count the number of file system events.

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

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;
use std::io::ErrorKind;

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

let mut buffer = [0; 1024];
let events = loop {
    match inotify.read_events(&mut buffer) {
        Ok(events) => break events,
        Err(error) if error.kind() == ErrorKind::WouldBlock => continue,
        _ => panic!("Error while reading events"),
    }
};

for event in events {
    // Handle event
}

pub fn event_stream<T>(&mut self, buffer: T) -> Result<EventStream<T>> where
    T: AsMut<[u8]> + AsRef<[u8]>, 

Create a stream which collects events

Returns a Stream over all events that are available. This stream is an infinite source of events.

An internal buffer which can hold the largest possible event is used.

pub 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");

Trait Implementations

impl AsRawFd for Inotify

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Inotify

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromRawFd for Inotify

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for Inotify

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.