inotify/
lib.rs

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//! The [`EventStream`] struct is designed to be used with async streams.
11//!
12//! # Examples
13//!
14//! If you just want to synchronously retrieve events
15//! ```
16//! use inotify::{
17//!     Inotify,
18//!     WatchMask,
19//! };
20//!
21//! let mut inotify = Inotify::init()
22//!     .expect("Error while initializing inotify instance");
23//!
24//! # // Create a temporary file, so `Watches::add` won't return an error.
25//! # use std::fs::File;
26//! # let mut test_file = File::create("/tmp/inotify-rs-test-file")
27//! #     .expect("Failed to create test file");
28//! #
29//! // Watch for modify and close events.
30//! inotify
31//!     .watches()
32//!     .add(
33//!         "/tmp/inotify-rs-test-file",
34//!         WatchMask::MODIFY | WatchMask::CLOSE,
35//!     )
36//!     .expect("Failed to add file watch");
37//!
38//! # // Modify file, so the following `read_events_blocking` won't block.
39//! # use std::io::Write;
40//! # write!(&mut test_file, "something\n")
41//! #     .expect("Failed to write something to test file");
42//! #
43//! // Read events that were added with `Watches::add` above.
44//! let mut buffer = [0; 1024];
45//! let events = inotify.read_events_blocking(&mut buffer)
46//!     .expect("Error while reading events");
47//!
48//! for event in events {
49//!     // Handle event
50//! }
51//! ```
52//! When you want to read events asynchronously, you need to convert it to [`EventStream`].
53//! The transform function is [`Inotify::into_event_stream`]
54//! ```
55//! # async fn stream_events() {
56//! # use futures_util::StreamExt;
57//! #
58//! # let mut inotify = inotify::Inotify::init()
59//! #     .expect("Error while initializing inotify instance");
60//! #
61//! let mut buffer = [0; 1024];
62//! let mut stream = inotify.into_event_stream(&mut buffer)
63//!     .expect("Error converting to stream");
64//!
65//! // Read events from async stream
66//! while let Some(event_or_error) = stream.next().await {
67//!     println!("event: {:?}", event_or_error.expect("Stream error"));
68//! }
69//! # }
70//! ```
71//! # Attention: inotify gotchas
72//!
73//! inotify (as in, the Linux API, not this wrapper) has many edge cases, making
74//! it hard to use correctly. This can lead to weird and hard to find bugs in
75//! applications that are based on it. inotify-rs does its best to fix these
76//! issues, but sometimes this would require an amount of runtime overhead that
77//! is just unacceptable for a low-level wrapper such as this.
78//!
79//! We've documented any issues that inotify-rs has inherited from inotify, as
80//! far as we are aware of them. Please watch out for any further warnings
81//! throughout this documentation. If you want to be on the safe side, in case
82//! we have missed something, please read the [inotify man pages] carefully.
83//!
84//! [inotify-rs]: https://crates.io/crates/inotify
85//! [inotify]: https://en.wikipedia.org/wiki/Inotify
86//! [inotify man pages]: http://man7.org/linux/man-pages/man7/inotify.7.html
87//!
88//! # `Vec` as buffers
89//!
90//! Using a `Vec::with_capacity(4096)` as a buffer is problematic, since this buffer has reserved
91//! capacity but length `0`. Use `vec![0u8; 4096]` instead.
92
93#![deny(missing_docs)]
94#![deny(warnings)]
95#![deny(missing_debug_implementations)]
96
97#[macro_use]
98extern crate bitflags;
99
100mod events;
101mod fd_guard;
102mod inotify;
103mod util;
104mod watches;
105
106#[cfg(feature = "stream")]
107mod stream;
108
109pub use crate::events::{
110    Event, EventAuxiliaryFlags, EventKind, EventMask, EventMaskParseError, EventOwned, Events,
111    ParsedEventMask,
112};
113pub use crate::inotify::Inotify;
114pub use crate::util::{get_absolute_path_buffer_size, get_buffer_size};
115pub use crate::watches::{WatchDescriptor, WatchMask, Watches};
116
117#[cfg(feature = "stream")]
118pub use self::stream::EventStream;
inotify/lib.rs

inotify/
lib.rs
