Struct Watches

Source

pub struct Watches { /* private fields */ }

Expand description

Interface for adding and removing watches

Implementations§

Source §

impl Watches

Source

pub fn add(&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.watches().add("/tmp/inotify-rs-test-file", WatchMask::MODIFY)
    .expect("Failed to add file watch");

// Handle events for the file here

Source

pub fn remove(&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 Watches::add, 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");
let mut watches = inotify.watches();

for event in events {
    watches.remove(event.wd);
}