106 lines
2.9 KiB
Rust
106 lines
2.9 KiB
Rust
//! Idiomatic inotify wrapper for the Rust programming language
|
|
//!
|
|
//! # About
|
|
//!
|
|
//! [inotify-rs] is an idiomatic wrapper around the Linux kernel's [inotify] API
|
|
//! for the Rust programming language. It can be used for monitoring changes to
|
|
//! files or directories.
|
|
//!
|
|
//! The [`Inotify`] struct is the main entry point into the API.
|
|
//!
|
|
//! # Example
|
|
//!
|
|
//! ```
|
|
//! use inotify::{
|
|
//! Inotify,
|
|
//! WatchMask,
|
|
//! };
|
|
//!
|
|
//! let mut inotify = Inotify::init()
|
|
//! .expect("Error while initializing inotify instance");
|
|
//!
|
|
//! # // Create a temporary file, so `Watches::add` won't return an error.
|
|
//! # use std::fs::File;
|
|
//! # let mut test_file = File::create("/tmp/inotify-rs-test-file")
|
|
//! # .expect("Failed to create test file");
|
|
//! #
|
|
//! // Watch for modify and close events.
|
|
//! inotify
|
|
//! .watches()
|
|
//! .add(
|
|
//! "/tmp/inotify-rs-test-file",
|
|
//! WatchMask::MODIFY | WatchMask::CLOSE,
|
|
//! )
|
|
//! .expect("Failed to add file watch");
|
|
//!
|
|
//! # // Modify file, so the following `read_events_blocking` won't block.
|
|
//! # use std::io::Write;
|
|
//! # write!(&mut test_file, "something\n")
|
|
//! # .expect("Failed to write something to test file");
|
|
//! #
|
|
//! // Read events that were added with `Watches::add` 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
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! # Attention: inotify gotchas
|
|
//!
|
|
//! inotify (as in, the Linux API, not this wrapper) has many edge cases, making
|
|
//! it hard to use correctly. This can lead to weird and hard to find bugs in
|
|
//! applications that are based on it. inotify-rs does its best to fix these
|
|
//! issues, but sometimes this would require an amount of runtime overhead that
|
|
//! is just unacceptable for a low-level wrapper such as this.
|
|
//!
|
|
//! We've documented any issues that inotify-rs has inherited from inotify, as
|
|
//! far as we are aware of them. Please watch out for any further warnings
|
|
//! throughout this documentation. If you want to be on the safe side, in case
|
|
//! we have missed something, please read the [inotify man pages] carefully.
|
|
//!
|
|
//! [inotify-rs]: https://crates.io/crates/inotify
|
|
//! [inotify]: https://en.wikipedia.org/wiki/Inotify
|
|
//! [inotify man pages]: http://man7.org/linux/man-pages/man7/inotify.7.html
|
|
|
|
|
|
#![deny(missing_docs)]
|
|
#![deny(warnings)]
|
|
#![deny(missing_debug_implementations)]
|
|
|
|
|
|
#[macro_use]
|
|
extern crate bitflags;
|
|
|
|
mod events;
|
|
mod fd_guard;
|
|
mod inotify;
|
|
mod util;
|
|
mod watches;
|
|
|
|
#[cfg(feature = "stream")]
|
|
mod stream;
|
|
|
|
|
|
pub use crate::events::{
|
|
Event,
|
|
EventMask,
|
|
EventOwned,
|
|
Events,
|
|
};
|
|
pub use crate::inotify::Inotify;
|
|
pub use crate::util::{
|
|
get_buffer_size,
|
|
get_absolute_path_buffer_size,
|
|
};
|
|
pub use crate::watches::{
|
|
Watches,
|
|
WatchDescriptor,
|
|
WatchMask,
|
|
};
|
|
|
|
#[cfg(feature = "stream")]
|
|
pub use self::stream::EventStream;
|