# [−][src]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.

## Methods

### `impl Inotify`[src]

#### `pub fn init() -> Result<Inotify>`[src]

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>,` [src]

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 `WatchDescriptor`s 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<()>`[src]

Stops watching a file

Removes the watch represented by the provided `WatchDescriptor` by calling `inotify_rm_watch`. `WatchDescriptor`s 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>>`[src]

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>>`[src]

Returns any available events

Returns an iterator over all events that are currently available. 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 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` (except EGAIN/EWOULDBLOCK, which result in an empty iterator). 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
    }

#### `pub fn close(self) -> Result<()>`[src]

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 IntoRawFd for Inotify`[src]

#### `fn into_raw_fd(self) -> RawFd`[src]

Consumes this object, returning the raw underlying file descriptor. Read more

### `impl AsRawFd for Inotify`[src]

#### `fn as_raw_fd(&self) -> RawFd`[src]

Extracts the raw file descriptor. Read more

### `impl FromRawFd for Inotify`[src]

#### `unsafe fn from_raw_fd(fd: RawFd) -> Self`[src]

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

## Auto Trait Implementations

### `impl Send for Inotify`

### `impl Unpin for Inotify`

### `impl Sync for Inotify`

### `impl UnwindSafe for Inotify`

### `impl RefUnwindSafe for Inotify`

## Blanket Implementations

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)