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 `Watches::add` 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 //!     .watches()
30 //!     .add(
31 //!         "/tmp/inotify-rs-test-file",
32 //!         WatchMask::MODIFY | WatchMask::CLOSE,
33 //!     )
34 //!     .expect("Failed to add file watch");
35 //!
36 //! # // Modify file, so the following `read_events_blocking` won't block.
37 //! # use std::io::Write;
38 //! # write!(&mut test_file, "something\n")
39 //! #     .expect("Failed to write something to test file");
40 //! #
41 //! // Read events that were added with `Watches::add` above.
42 //! let mut buffer = [0; 1024];
43 //! let events = inotify.read_events_blocking(&mut buffer)
44 //!     .expect("Error while reading events");
45 //!
46 //! for event in events {
47 //!     // Handle event
48 //! }
49 //! ```
50 //!
51 //! # Attention: inotify gotchas
52 //!
53 //! inotify (as in, the Linux API, not this wrapper) has many edge cases, making
54 //! it hard to use correctly. This can lead to weird and hard to find bugs in
55 //! applications that are based on it. inotify-rs does its best to fix these
56 //! issues, but sometimes this would require an amount of runtime overhead that
57 //! is just unacceptable for a low-level wrapper such as this.
58 //!
59 //! We've documented any issues that inotify-rs has inherited from inotify, as
60 //! far as we are aware of them. Please watch out for any further warnings
61 //! throughout this documentation. If you want to be on the safe side, in case
62 //! we have missed something, please read the [inotify man pages] carefully.
63 //!
64 //! [inotify-rs]: https://crates.io/crates/inotify
65 //! [inotify]: https://en.wikipedia.org/wiki/Inotify
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]
75 extern crate bitflags;
76 
77 mod events;
78 mod fd_guard;
79 mod inotify;
80 mod util;
81 mod watches;
82 
83 #[cfg(feature = "stream")]
84 mod stream;
85 
86 
87 pub use crate::events::{
88     Event,
89     EventMask,
90     EventOwned,
91     Events,
92 };
93 pub use crate::inotify::Inotify;
94 pub use crate::util::{
95     get_buffer_size,
96     get_absolute_path_buffer_size,
97 };
98 pub use crate::watches::{
99     Watches,
100     WatchDescriptor,
101     WatchMask,
102 };
103 
104 #[cfg(feature = "stream")]
105 pub use self::stream::EventStream;
106