Struct inotify::Inotify

source ·

pub struct Inotify { /* private fields */ }

Expand description

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§

source §

impl Inotify

source

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.

pub fn watches(&self) -> Watches

Gets an interface that allows adding and removing watches. See Watches::add and Watches::remove.

source

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

👎Deprecated: use Inotify.watches().add() instead

Deprecated: use Inotify.watches().add() instead

source

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

👎Deprecated: use Inotify.watches().remove() instead

Deprecated: use Inotify.watches().remove() instead

source

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.

source

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
}

source

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

👎Deprecated: use into_event_stream() instead, which enforces a single Stream and predictable reads

Deprecated: use into_event_stream() instead, which enforces a single Stream and predictable reads. Using this method to create multiple EventStream instances from one Inotify is unsupported, as they will contend over one event source and each produce unpredictable stream contents.

source

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

Create a stream which collects events. Consumes the Inotify instance.

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.

source

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