Debian Codegraph @

src/sys/inotify.rs

raw
1 //! Monitoring API for filesystem events.
2 //!
3 //! Inotify is a Linux-only API to monitor filesystems events.
4 //!
5 //! For more documentation, please read [inotify(7)](https://man7.org/linux/man-pages/man7/inotify.7.html).
6 //!
7 //! # Examples
8 //!
9 //! Monitor all events happening in directory "test":
10 //! ```no_run
11 //! # use nix::sys::inotify::{AddWatchFlags,InitFlags,Inotify};
12 //! #
13 //! // We create a new inotify instance.
14 //! let instance = Inotify::init(InitFlags::empty()).unwrap();
15 //!
16 //! // We add a new watch on directory "test" for all events.
17 //! let wd = instance.add_watch("test", AddWatchFlags::IN_ALL_EVENTS).unwrap();
18 //!
19 //! loop {
20 //! // We read from our inotify instance for events.
21 //! let events = instance.read_events().unwrap();
22 //! println!("Events: {:?}", events);
23 //! }
24 //! ```
25
26 use crate::errno::Errno;
27 use crate::unistd::read;
28 use crate::NixPath;
29 use crate::Result;
30 use cfg_if::cfg_if;
31 use libc::{c_char, c_int};
32 use std::ffi::{CStr, OsStr, OsString};
33 use std::mem::{size_of, MaybeUninit};
34 use std::os::unix::ffi::OsStrExt;
35 use std::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, OwnedFd, RawFd};
36 use std::ptr;
37
38 libc_bitflags! {
39 /// Configuration options for [`inotify_add_watch`](fn.inotify_add_watch.html).
40 pub struct AddWatchFlags: u32 {
41 /// File was accessed.
42 IN_ACCESS;
43 /// File was modified.
44 IN_MODIFY;
45 /// Metadata changed.
46 IN_ATTRIB;
47 /// Writable file was closed.
48 IN_CLOSE_WRITE;
49 /// Nonwritable file was closed.
50 IN_CLOSE_NOWRITE;
51 /// File was opened.
52 IN_OPEN;
53 /// File was moved from X.
54 IN_MOVED_FROM;
55 /// File was moved to Y.
56 IN_MOVED_TO;
57 /// Subfile was created.
58 IN_CREATE;
59 /// Subfile was deleted.
60 IN_DELETE;
61 /// Self was deleted.
62 IN_DELETE_SELF;
63 /// Self was moved.
64 IN_MOVE_SELF;
65
66 /// Backing filesystem was unmounted.
67 IN_UNMOUNT;
68 /// Event queue overflowed.
69 IN_Q_OVERFLOW;
70 /// File was ignored.
71 IN_IGNORED;
72
73 /// Combination of `IN_CLOSE_WRITE` and `IN_CLOSE_NOWRITE`.
74 IN_CLOSE;
75 /// Combination of `IN_MOVED_FROM` and `IN_MOVED_TO`.
76 IN_MOVE;
77
78 /// Only watch the path if it is a directory.
79 IN_ONLYDIR;
80 /// Don't follow symlinks.
81 IN_DONT_FOLLOW;
82
83 /// Event occurred against directory.
84 IN_ISDIR;
85 /// Only send event once.
86 IN_ONESHOT;
87 /// All of the events.
88 IN_ALL_EVENTS;
89 }
90 }
91
92 libc_bitflags! {
93 /// Configuration options for [`inotify_init1`](fn.inotify_init1.html).
94 pub struct InitFlags: c_int {
95 /// Set the `FD_CLOEXEC` flag on the file descriptor.
96 IN_CLOEXEC;
97 /// Set the `O_NONBLOCK` flag on the open file description referred to by the new file descriptor.
98 IN_NONBLOCK;
99 }
100 }
101
102 /// An inotify instance. This is also a file descriptor, you can feed it to
103 /// other interfaces consuming file descriptors, epoll for example.
104 #[derive(Debug)]
105 pub struct Inotify {
106 fd: OwnedFd,
107 }
108
109 /// This object is returned when you create a new watch on an inotify instance.
110 /// It is then returned as part of an event once triggered. It allows you to
111 /// know which watch triggered which event.
112 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, Ord, PartialOrd)]
113 pub struct WatchDescriptor {
114 wd: i32,
115 }
116
117 /// A single inotify event.
118 ///
119 /// For more documentation see, [inotify(7)](https://man7.org/linux/man-pages/man7/inotify.7.html).
120 #[derive(Debug)]
121 pub struct InotifyEvent {
122 /// Watch descriptor. This field corresponds to the watch descriptor you
123 /// were issued when calling add_watch. It allows you to know which watch
124 /// this event comes from.
125 pub wd: WatchDescriptor,
126 /// Event mask. This field is a bitfield describing the exact event that
127 /// occured.
128 pub mask: AddWatchFlags,
129 /// This cookie is a number that allows you to connect related events. For
130 /// now only IN_MOVED_FROM and IN_MOVED_TO can be connected.
131 pub cookie: u32,
132 /// Filename. This field exists only if the event was triggered for a file
133 /// inside the watched directory.
134 pub name: Option<OsString>,
135 }
136
137 impl Inotify {
138 /// Initialize a new inotify instance.
139 ///
140 /// Returns a Result containing an inotify instance.
141 ///
142 /// For more information see, [inotify_init(2)](https://man7.org/linux/man-pages/man2/inotify_init.2.html).
143 pub fn init(flags: InitFlags) -> Result<Inotify> {
144 let res = Errno::result(unsafe { libc::inotify_init1(flags.bits()) });
145
146 res.map(|fd| Inotify {
147 fd: unsafe { OwnedFd::from_raw_fd(fd) },
148 })
149 }
150
151 /// Adds a new watch on the target file or directory.
152 ///
153 /// Returns a watch descriptor. This is not a File Descriptor!
154 ///
155 /// For more information see, [inotify_add_watch(2)](https://man7.org/linux/man-pages/man2/inotify_add_watch.2.html).
156 pub fn add_watch<P: ?Sized + NixPath>(
157 &self,
158 path: &P,
159 mask: AddWatchFlags,
160 ) -> Result<WatchDescriptor> {
161 let res = path.with_nix_path(|cstr| unsafe {
162 libc::inotify_add_watch(
163 self.fd.as_raw_fd(),
164 cstr.as_ptr(),
165 mask.bits(),
166 )
167 })?;
168
169 Errno::result(res).map(|wd| WatchDescriptor { wd })
170 }
171
172 /// Removes an existing watch using the watch descriptor returned by
173 /// inotify_add_watch.
174 ///
175 /// Returns an EINVAL error if the watch descriptor is invalid.
176 ///
177 /// For more information see, [inotify_rm_watch(2)](https://man7.org/linux/man-pages/man2/inotify_rm_watch.2.html).
178 pub fn rm_watch(&self, wd: WatchDescriptor) -> Result<()> {
179 cfg_if! {
180 if #[cfg(target_os = "linux")] {
181 let arg = wd.wd;
182 } else if #[cfg(target_os = "android")] {
183 let arg = wd.wd as u32;
184 }
185 }
186 let res = unsafe { libc::inotify_rm_watch(self.fd.as_raw_fd(), arg) };
187
188 Errno::result(res).map(drop)
189 }
190
191 /// Reads a collection of events from the inotify file descriptor. This call
192 /// can either be blocking or non blocking depending on whether IN_NONBLOCK
193 /// was set at initialization.
194 ///
195 /// Returns as many events as available. If the call was non blocking and no
196 /// events could be read then the EAGAIN error is returned.
197 pub fn read_events(&self) -> Result<Vec<InotifyEvent>> {
198 let header_size = size_of::<libc::inotify_event>();
199 const BUFSIZ: usize = 4096;
200 let mut buffer = [0u8; BUFSIZ];
201 let mut events = Vec::new();
202 let mut offset = 0;
203
204 let nread = read(&self.fd, &mut buffer)?;
205
206 while (nread - offset) >= header_size {
207 let event = unsafe {
208 let mut event = MaybeUninit::<libc::inotify_event>::uninit();
209 ptr::copy_nonoverlapping(
210 buffer.as_ptr().add(offset),
211 event.as_mut_ptr().cast(),
212 (BUFSIZ - offset).min(header_size),
213 );
214 event.assume_init()
215 };
216
217 let name = match event.len {
218 0 => None,
219 _ => {
220 let ptr = unsafe {
221 buffer.as_ptr().add(offset + header_size)
222 as *const c_char
223 };
224 let cstr = unsafe { CStr::from_ptr(ptr) };
225
226 Some(OsStr::from_bytes(cstr.to_bytes()).to_owned())
227 }
228 };
229
230 events.push(InotifyEvent {
231 wd: WatchDescriptor { wd: event.wd },
232 mask: AddWatchFlags::from_bits_truncate(event.mask),
233 cookie: event.cookie,
234 name,
235 });
236
237 offset += header_size + event.len as usize;
238 }
239
240 Ok(events)
241 }
242
243 /// Constructs an `Inotify` wrapping an existing `OwnedFd`.
244 ///
245 /// # Safety
246 ///
247 /// `OwnedFd` is a valid `Inotify`.
248 pub unsafe fn from_owned_fd(fd: OwnedFd) -> Self {
249 Self {
250 fd
251 }
252 }
253 }
254
255 impl FromRawFd for Inotify {
256 unsafe fn from_raw_fd(fd: RawFd) -> Self {
257 Inotify {
258 fd: unsafe { OwnedFd::from_raw_fd(fd) },
259 }
260 }
261 }
262
263 impl AsFd for Inotify {
264 fn as_fd(&'_ self) -> BorrowedFd<'_> {
265 self.fd.as_fd()
266 }
267 }
268
269 impl From<Inotify> for OwnedFd {
270 fn from(value: Inotify) -> Self {
271 value.fd
272 }
273 }