485 lines
17 KiB
Rust
485 lines
17 KiB
Rust
use std::{
|
|
ffi::CString,
|
|
io,
|
|
os::unix::ffi::OsStrExt,
|
|
os::unix::io::{
|
|
AsRawFd,
|
|
FromRawFd,
|
|
IntoRawFd,
|
|
RawFd,
|
|
},
|
|
path::Path,
|
|
sync::{
|
|
atomic::AtomicBool,
|
|
Arc,
|
|
}
|
|
};
|
|
|
|
use inotify_sys as ffi;
|
|
use libc::{
|
|
F_GETFL,
|
|
F_SETFD,
|
|
F_SETFL,
|
|
FD_CLOEXEC,
|
|
O_NONBLOCK,
|
|
fcntl,
|
|
};
|
|
|
|
use crate::events::Events;
|
|
use crate::fd_guard::FdGuard;
|
|
use crate::util::read_into_buffer;
|
|
use crate::watches::{
|
|
WatchDescriptor,
|
|
WatchMask,
|
|
};
|
|
|
|
|
|
#[cfg(feature = "stream")]
|
|
use crate::stream::EventStream;
|
|
|
|
|
|
/// Idiomatic Rust wrapper around Linux's inotify API
|
|
///
|
|
/// `Inotify` is a wrapper around an inotify instance. It generally tries to
|
|
/// adhere to the underlying inotify API closely, while making access to it
|
|
/// safe and convenient.
|
|
///
|
|
/// Please refer to the [top-level documentation] for further details and a
|
|
/// usage example.
|
|
///
|
|
/// [top-level documentation]: index.html
|
|
#[derive(Debug)]
|
|
pub struct Inotify {
|
|
fd: Arc<FdGuard>,
|
|
}
|
|
|
|
impl Inotify {
|
|
/// Creates an [`Inotify`] instance
|
|
///
|
|
/// Initializes an inotify instance by calling [`inotify_init1`].
|
|
///
|
|
/// This method passes both flags accepted by [`inotify_init1`], not giving
|
|
/// the user any choice in the matter, as not passing the flags would be
|
|
/// inappropriate in the context of this wrapper:
|
|
///
|
|
/// - [`IN_CLOEXEC`] prevents leaking file descriptors to other processes.
|
|
/// - [`IN_NONBLOCK`] controls the blocking behavior of the inotify API,
|
|
/// which is entirely managed by this wrapper.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Directly returns the error from the call to [`inotify_init1`], without
|
|
/// adding any error conditions of its own.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use inotify::Inotify;
|
|
///
|
|
/// let inotify = Inotify::init()
|
|
/// .expect("Failed to initialize an inotify instance");
|
|
/// ```
|
|
///
|
|
/// [`Inotify`]: struct.Inotify.html
|
|
/// [`inotify_init1`]: ../inotify_sys/fn.inotify_init1.html
|
|
/// [`IN_CLOEXEC`]: ../inotify_sys/constant.IN_CLOEXEC.html
|
|
/// [`IN_NONBLOCK`]: ../inotify_sys/constant.IN_NONBLOCK.html
|
|
pub fn init() -> io::Result<Inotify> {
|
|
// Initialize inotify and set CLOEXEC and NONBLOCK flags.
|
|
//
|
|
// NONBLOCK is needed, because `Inotify` manages blocking behavior for
|
|
// the API consumer, and the way we do that is to make everything non-
|
|
// blocking by default and later override that as required.
|
|
//
|
|
// CLOEXEC prevents leaking file descriptors to processes executed by
|
|
// this process and seems to be a best practice. I don't grasp this
|
|
// issue completely and failed to find any authoritative sources on the
|
|
// topic. There's some discussion in the open(2) and fcntl(2) man pages,
|
|
// but I didn't find that helpful in understanding the issue of leaked
|
|
// file descriptors. For what it's worth, there's a Rust issue about
|
|
// this:
|
|
// https://github.com/rust-lang/rust/issues/12148
|
|
let fd = unsafe {
|
|
let fd = ffi::inotify_init();
|
|
if fd == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
if fcntl(fd, F_SETFD, FD_CLOEXEC) == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
if fcntl(fd, F_SETFL, O_NONBLOCK) == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
fd
|
|
};
|
|
|
|
Ok(Inotify {
|
|
fd: Arc::new(FdGuard {
|
|
fd,
|
|
close_on_drop: AtomicBool::new(true),
|
|
}),
|
|
})
|
|
}
|
|
|
|
/// Adds or updates a watch for the given path
|
|
///
|
|
/// Adds a new watch or updates an existing one for the file referred to by
|
|
/// `path`. Returns a watch descriptor that can be used to refer to this
|
|
/// watch later.
|
|
///
|
|
/// The `mask` argument defines what kind of changes the file should be
|
|
/// watched for, and how to do that. See the documentation of [`WatchMask`]
|
|
/// for details.
|
|
///
|
|
/// If this method is used to add a new watch, a new [`WatchDescriptor`] is
|
|
/// returned. If it is used to update an existing watch, a
|
|
/// [`WatchDescriptor`] that equals the previously returned
|
|
/// [`WatchDescriptor`] for that watch is returned instead.
|
|
///
|
|
/// Under the hood, this method just calls [`inotify_add_watch`] and does
|
|
/// some trivial translation between the types on the Rust side and the C
|
|
/// side.
|
|
///
|
|
/// # Attention: Updating watches and hardlinks
|
|
///
|
|
/// As mentioned above, this method can be used to update an existing watch.
|
|
/// This is usually done by calling this method with the same `path`
|
|
/// argument that it has been called with before. But less obviously, it can
|
|
/// also happen if the method is called with a different path that happens
|
|
/// to link to the same inode.
|
|
///
|
|
/// You can detect this by keeping track of [`WatchDescriptor`]s and the
|
|
/// paths they have been returned for. If the same [`WatchDescriptor`] is
|
|
/// returned for a different path (and you haven't freed the
|
|
/// [`WatchDescriptor`] by removing the watch), you know you have two paths
|
|
/// pointing to the same inode, being watched by the same watch.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Directly returns the error from the call to
|
|
/// [`inotify_add_watch`][`inotify_add_watch`] (translated into an
|
|
/// `io::Error`), without adding any error conditions of
|
|
/// its own.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use inotify::{
|
|
/// Inotify,
|
|
/// WatchMask,
|
|
/// };
|
|
///
|
|
/// let mut inotify = Inotify::init()
|
|
/// .expect("Failed to initialize an inotify instance");
|
|
///
|
|
/// # // Create a temporary file, so `add_watch` won't return an error.
|
|
/// # use std::fs::File;
|
|
/// # File::create("/tmp/inotify-rs-test-file")
|
|
/// # .expect("Failed to create test file");
|
|
/// #
|
|
/// inotify.add_watch("/tmp/inotify-rs-test-file", WatchMask::MODIFY)
|
|
/// .expect("Failed to add file watch");
|
|
///
|
|
/// // Handle events for the file here
|
|
/// ```
|
|
///
|
|
/// [`inotify_add_watch`]: ../inotify_sys/fn.inotify_add_watch.html
|
|
/// [`WatchMask`]: struct.WatchMask.html
|
|
/// [`WatchDescriptor`]: struct.WatchDescriptor.html
|
|
pub fn add_watch<P>(&mut self, path: P, mask: WatchMask)
|
|
-> io::Result<WatchDescriptor>
|
|
where P: AsRef<Path>
|
|
{
|
|
let path = CString::new(path.as_ref().as_os_str().as_bytes())?;
|
|
|
|
let wd = unsafe {
|
|
ffi::inotify_add_watch(
|
|
**self.fd,
|
|
path.as_ptr() as *const _,
|
|
mask.bits(),
|
|
)
|
|
};
|
|
|
|
match wd {
|
|
-1 => Err(io::Error::last_os_error()),
|
|
_ => Ok(WatchDescriptor{ id: wd, fd: Arc::downgrade(&self.fd) }),
|
|
}
|
|
}
|
|
|
|
/// Stops watching a file
|
|
///
|
|
/// Removes the watch represented by the provided [`WatchDescriptor`] by
|
|
/// calling [`inotify_rm_watch`]. [`WatchDescriptor`]s can be obtained via
|
|
/// [`Inotify::add_watch`], or from the `wd` field of [`Event`].
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Directly returns the error from the call to [`inotify_rm_watch`].
|
|
/// Returns an [`io::Error`] with [`ErrorKind`]`::InvalidInput`, if the given
|
|
/// [`WatchDescriptor`] did not originate from this [`Inotify`] instance.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use inotify::Inotify;
|
|
///
|
|
/// let mut inotify = Inotify::init()
|
|
/// .expect("Failed to initialize an inotify instance");
|
|
///
|
|
/// # // Create a temporary file, so `add_watch` 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");
|
|
/// #
|
|
/// # // Add a watch and modify the file, so the code below doesn't block
|
|
/// # // forever.
|
|
/// # use inotify::WatchMask;
|
|
/// # inotify.add_watch("/tmp/inotify-rs-test-file", WatchMask::MODIFY)
|
|
/// # .expect("Failed to add file watch");
|
|
/// # use std::io::Write;
|
|
/// # write!(&mut test_file, "something\n")
|
|
/// # .expect("Failed to write something to test file");
|
|
/// #
|
|
/// let mut buffer = [0; 1024];
|
|
/// let events = inotify
|
|
/// .read_events_blocking(&mut buffer)
|
|
/// .expect("Error while waiting for events");
|
|
///
|
|
/// for event in events {
|
|
/// inotify.rm_watch(event.wd);
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// [`WatchDescriptor`]: struct.WatchDescriptor.html
|
|
/// [`inotify_rm_watch`]: ../inotify_sys/fn.inotify_rm_watch.html
|
|
/// [`Inotify::add_watch`]: struct.Inotify.html#method.add_watch
|
|
/// [`Event`]: struct.Event.html
|
|
/// [`Inotify`]: struct.Inotify.html
|
|
/// [`io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html
|
|
/// [`ErrorKind`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html
|
|
pub fn rm_watch(&mut self, wd: WatchDescriptor) -> io::Result<()> {
|
|
if wd.fd.upgrade().as_ref() != Some(&self.fd) {
|
|
return Err(io::Error::new(
|
|
io::ErrorKind::InvalidInput,
|
|
"Invalid WatchDescriptor",
|
|
));
|
|
}
|
|
|
|
let result = unsafe { ffi::inotify_rm_watch(**self.fd, wd.id) };
|
|
match result {
|
|
0 => Ok(()),
|
|
-1 => Err(io::Error::last_os_error()),
|
|
_ => panic!(
|
|
"unexpected return code from inotify_rm_watch ({})", result)
|
|
}
|
|
}
|
|
|
|
/// Waits until events are available, then returns them
|
|
///
|
|
/// Blocks the current thread until at least one event is available. If this
|
|
/// is not desirable, please consider [`Inotify::read_events`].
|
|
///
|
|
/// This method calls [`Inotify::read_events`] internally and behaves
|
|
/// essentially the same, apart from the blocking behavior. Please refer to
|
|
/// the documentation of [`Inotify::read_events`] for more information.
|
|
///
|
|
/// [`Inotify::read_events`]: struct.Inotify.html#method.read_events
|
|
/// [`read`]: ../libc/fn.read.html
|
|
pub fn read_events_blocking<'a>(&mut self, buffer: &'a mut [u8])
|
|
-> io::Result<Events<'a>>
|
|
{
|
|
unsafe {
|
|
let res = fcntl(**self.fd, F_GETFL);
|
|
if res == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
if fcntl(**self.fd, F_SETFL, res & !O_NONBLOCK) == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
};
|
|
let result = self.read_events(buffer);
|
|
unsafe {
|
|
let res = fcntl(**self.fd, F_GETFL);
|
|
if res == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
if fcntl(**self.fd, F_SETFL, res | O_NONBLOCK) == -1 {
|
|
return Err(io::Error::last_os_error());
|
|
}
|
|
};
|
|
|
|
result
|
|
}
|
|
|
|
/// Returns one buffer's worth of available events
|
|
///
|
|
/// Reads as many events as possible into `buffer`, and returns an iterator
|
|
/// over them. If no events are available, an iterator is still returned. If
|
|
/// you need a method that will block until at least one event is available,
|
|
/// please consider [`read_events_blocking`].
|
|
///
|
|
/// Please note that inotify will merge identical successive unread events
|
|
/// into a single event. This means this method can not be used to count the
|
|
/// number of file system events.
|
|
///
|
|
/// The `buffer` argument, as the name indicates, is used as a buffer for
|
|
/// the inotify events. Its contents may be overwritten.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function directly returns all errors from the call to [`read`]
|
|
/// (except EGAIN/EWOULDBLOCK, which result in an empty iterator). In
|
|
/// addition, [`ErrorKind::UnexpectedEof`] is returned, if the call to
|
|
/// [`read`] returns `0`, signaling end-of-file.
|
|
///
|
|
/// If `buffer` is too small, this will result in an error with
|
|
/// [`ErrorKind::InvalidInput`]. On very old Linux kernels,
|
|
/// [`ErrorKind::UnexpectedEof`] will be returned instead.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use inotify::Inotify;
|
|
///
|
|
/// let mut inotify = Inotify::init()
|
|
/// .expect("Failed to initialize an inotify instance");
|
|
///
|
|
/// let mut buffer = [0; 1024];
|
|
/// let events = inotify.read_events(&mut buffer)
|
|
/// .expect("Error while reading events");
|
|
///
|
|
/// for event in events {
|
|
/// // Handle event
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// [`read_events_blocking`]: struct.Inotify.html#method.read_events_blocking
|
|
/// [`read`]: ../libc/fn.read.html
|
|
/// [`ErrorKind::UnexpectedEof`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.UnexpectedEof
|
|
/// [`ErrorKind::InvalidInput`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput
|
|
pub fn read_events<'a>(&mut self, buffer: &'a mut [u8])
|
|
-> io::Result<Events<'a>>
|
|
{
|
|
let num_bytes = read_into_buffer(**self.fd, buffer);
|
|
|
|
let num_bytes = match num_bytes {
|
|
0 => {
|
|
return Err(
|
|
io::Error::new(
|
|
io::ErrorKind::UnexpectedEof,
|
|
"`read` return `0`, signaling end-of-file"
|
|
)
|
|
);
|
|
}
|
|
-1 => {
|
|
let error = io::Error::last_os_error();
|
|
if error.kind() == io::ErrorKind::WouldBlock {
|
|
return Ok(Events::new(Arc::downgrade(&self.fd), buffer, 0));
|
|
}
|
|
else {
|
|
return Err(error);
|
|
}
|
|
},
|
|
_ if num_bytes < 0 => {
|
|
panic!("{} {} {} {} {} {}",
|
|
"Unexpected return value from `read`. Received a negative",
|
|
"value that was not `-1`. According to the `read` man page",
|
|
"this shouldn't happen, as either `-1` is returned on",
|
|
"error, `0` on end-of-file, or a positive value for the",
|
|
"number of bytes read. Returned value:",
|
|
num_bytes,
|
|
);
|
|
}
|
|
_ => {
|
|
// The value returned by `read` should be `isize`. Let's quickly
|
|
// verify this with the following assignment, so we can be sure
|
|
// our cast below is valid.
|
|
let num_bytes: isize = num_bytes;
|
|
|
|
// The type returned by `read` is `isize`, and we've ruled out
|
|
// all negative values with the match arms above. This means we
|
|
// can safely cast to `usize`.
|
|
debug_assert!(num_bytes > 0);
|
|
num_bytes as usize
|
|
}
|
|
};
|
|
|
|
Ok(Events::new(Arc::downgrade(&self.fd), buffer, num_bytes))
|
|
}
|
|
|
|
/// Create a stream which collects events
|
|
///
|
|
/// Returns a `Stream` over all events that are available. This stream is an
|
|
/// infinite source of events.
|
|
///
|
|
/// An internal buffer which can hold the largest possible event is used.
|
|
#[cfg(feature = "stream")]
|
|
pub fn event_stream<T>(&mut self, buffer: T)
|
|
-> io::Result<EventStream<T>>
|
|
where
|
|
T: AsMut<[u8]> + AsRef<[u8]>,
|
|
{
|
|
EventStream::new(self.fd.clone(), buffer)
|
|
}
|
|
|
|
/// Closes the inotify instance
|
|
///
|
|
/// Closes the file descriptor referring to the inotify instance. The user
|
|
/// usually doesn't have to call this function, as the underlying inotify
|
|
/// instance is closed automatically, when [`Inotify`] is dropped.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Directly returns the error from the call to [`close`], without adding any
|
|
/// error conditions of its own.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use inotify::Inotify;
|
|
///
|
|
/// let mut inotify = Inotify::init()
|
|
/// .expect("Failed to initialize an inotify instance");
|
|
///
|
|
/// inotify.close()
|
|
/// .expect("Failed to close inotify instance");
|
|
/// ```
|
|
///
|
|
/// [`Inotify`]: struct.Inotify.html
|
|
/// [`close`]: ../libc/fn.close.html
|
|
pub fn close(self) -> io::Result<()> {
|
|
// `self` will be dropped when this method returns. If this is the only
|
|
// owner of `fd`, the `Arc` will also be dropped. The `Drop`
|
|
// implementation for `FdGuard` will attempt to close the file descriptor
|
|
// again, unless this flag here is cleared.
|
|
self.fd.should_not_close();
|
|
|
|
match unsafe { ffi::close(**self.fd) } {
|
|
0 => Ok(()),
|
|
_ => Err(io::Error::last_os_error()),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl AsRawFd for Inotify {
|
|
#[inline]
|
|
fn as_raw_fd(&self) -> RawFd {
|
|
self.fd.as_raw_fd()
|
|
}
|
|
}
|
|
|
|
impl FromRawFd for Inotify {
|
|
unsafe fn from_raw_fd(fd: RawFd) -> Self {
|
|
Inotify {
|
|
fd: Arc::new(FdGuard::from_raw_fd(fd))
|
|
}
|
|
}
|
|
}
|
|
|
|
impl IntoRawFd for Inotify {
|
|
#[inline]
|
|
fn into_raw_fd(self) -> RawFd {
|
|
self.fd.should_not_close();
|
|
self.fd.fd
|
|
}
|
|
}
|