1//! Idiomatic inotify wrapper for the Rust programming language
2//!
3//! # About
4//!
5//! [inotify-rs] is an idiomatic wrapper around the Linux kernel's [inotify] API
6//! for the Rust programming language. It can be used for monitoring changes to
7//! files or directories.
8//!
9//! The [`Inotify`] struct is the main entry point into the API.
10//!
11//! # Example
12//!
13//! ```
14//! use inotify::{
15//! Inotify,
16//! WatchMask,
17//! };
18//!
19//! let mut inotify = Inotify::init()
20//! .expect("Error while initializing inotify instance");
21//!
22//! # // Create a temporary file, so `add_watch` won't return an error.
23//! # use std::fs::File;
24//! # let mut test_file = File::create("/tmp/inotify-rs-test-file")
25//! # .expect("Failed to create test file");
26//! #
27//! // Watch for modify and close events.
28//! inotify
29//! .add_watch(
30//! "/tmp/inotify-rs-test-file",
31//! WatchMask::MODIFY | WatchMask::CLOSE,
32//! )
33//! .expect("Failed to add file watch");
34//!
35//! # // Modify file, so the following `read_events_blocking` won't block.
36//! # use std::io::Write;
37//! # write!(&mut test_file, "something\n")
38//! # .expect("Failed to write something to test file");
39//! #
40//! // Read events that were added with `add_watch` above.
41//! let mut buffer = [0; 1024];
42//! let events = inotify.read_events_blocking(&mut buffer)
43//! .expect("Error while reading events");
44//!
45//! for event in events {
46//! // Handle event
47//! }
48//! ```
49//!
50//! # Attention: inotify gotchas
51//!
52//! inotify (as in, the Linux API, not this wrapper) has many edge cases, making
53//! it hard to use correctly. This can lead to weird and hard to find bugs in
54//! applications that are based on it. inotify-rs does its best to fix these
55//! issues, but sometimes this would require an amount of runtime overhead that
56//! is just unacceptable for a low-level wrapper such as this.
57//!
58//! We've documented any issues that inotify-rs has inherited from inotify, as
59//! far as we are aware of them. Please watch out for any further warnings
60//! throughout this documentation. If you want to be on the safe side, in case
61//! we have missed something, please read the [inotify man pages] carefully.
62//!
63//! [inotify-rs]: https://crates.io/crates/inotify
64//! [inotify]: https://en.wikipedia.org/wiki/Inotify
65//! [`Inotify`]: struct.Inotify.html
66//! [inotify man pages]: http://man7.org/linux/man-pages/man7/inotify.7.html
67
68
69#![deny(missing_docs)]
70#![deny(warnings)]
71#![deny(missing_debug_implementations)]
72
73
74#[macro_use]
75extern crate bitflags;
76
77mod events;
78mod fd_guard;
79mod inotify;
80mod util;
81mod watches;
82
83#[cfg(feature = "stream")]
84mod stream;
85
86
87pub use crate::events::{
88 Event,
89 EventMask,
90 EventOwned,
91 Events,
92};
93pub use crate::inotify::Inotify;
94pub use crate::util::{
95 get_buffer_size,
96 get_absolute_path_buffer_size,
97};
98pub use crate::watches::{
99 WatchDescriptor,
100 WatchMask,
101};
102
103#[cfg(feature = "stream")]
104pub use self::stream::EventStream;
105