libinotify-kqueue ================= Copyright (c) 2011-2014 Dmitry Matveev <firstname.lastname@example.org> Copyright (c) 2014-2018 Vladimir Kondratyev <email@example.com> The purpose of this library is to provide inotify API on the *BSD family of operating systems. The library uses kqueue(2) to monitor the file system activity. Requirements ------------ - gcc, g++, automake, autoconf, libtool; - NetBSD, OpenBSD, FreeBSD (all tested), Mac OS X (reported to work). Downloading ----------- This project does not have a special home page yet. The source code and the issue tracker are hosted on Github: https://github.com/libinotify-kqueue/libinotify-kqueue Building -------- Building from a git snaphost is as simple as: $ autoreconf -fvi $ ./configure $ make Testing ------- After you build the library, you can run tests to ensure that everything works in your system: $ make test There are 100+ tests, and since some events cann't be implemented using only original kqueue(2), these tests will most probably fail: > In test "Directory notifications": > failed: receive IN_MOVED_FROM event on moving file from directory to > another location within the same mount point > failed: receive IN_MOVED_TO event on moving file to directory from > another location within the same mount point > In test "Open/close notifications": > failed: receive IN_OPEN on cat > failed: receive IN_CLOSE_NOWRITE on cat > failed: receive IN_OPEN on ls > failed: receive IN_CLOSE_NOWRITE on ls > failed: receive IN_OPEN on modify > failed: receive IN_CLOSE_WRITE on modify > In test "Symbolic links": > failed: Start watch successfully on a symlink file with IN_DONT_FOLLOW > failed: Receive IN_ATTRIB after touching symlink itself > failed: Receive IN_MOVE_SELF after moving the symlink > failed: Receive IN_DELETE_SELF after removing the symlink To solve these issues some vfs and kqueue extensions was developed. Patches can be found in patches subdirectory of project and are applicable to FreeBSD 11-CURRENT. A patched kernel passes all tests flawlessly. If you will get any other results, please feel free to report it at: https://github.com/libinotify-kqueue/libinotify-kqueue/issues Using ----- To use the library, all you need to do is to link your application with it (adding -linotify to LDFLAGS works in almost all cases). Of course, you will need to have include (-I) and linker (-L) directories to be properly set in your project. Since the heart of the library is kqueue(2), the library has to keep many files open to provide proper monitoring. It is especially important when you monitor a single but large directory. Rules are: If application specifies only IN_CREATE, IN_DELETE, IN_MOVED_FROM, IN_MOVED_TO, IN_DELETE_SELF or IN_MOVE_SELF events in mask argument of inotify_add_watch(2) then libinotify opens only watched directory itself. Adding IN_CLOSE_WRITE and/or IN_MODIFY events to ones mentioned before leads to opening of every regular file inside a watched directory. And adding one of IN_ACCESS, IN_ATTRIB, IN_CLOSE_NOWRITE or IN_OPEN flags to event mask leads to opening of all directories as well as regular files inside a watched directory. You can run out of file descriptors, so do not forget request more with setrlimit(2) before starting monitoring. Note that fcntl(2) calls are not supported on descriptors returned by the library's inotify_init(). Linux implementation does not allow partial event reads from inotify file descriptor while socketpair(2) used for libinotify-kqueue allows arbitrary amount of data to be read from. So software unaware of that can lose datastream event position synchronization that leads to unpredictable results. To avoid that as much as possible socketpair buffer size has been reduced to reasonable small value (currently 4K) exposed as IN_DEF_SOCKBUFSIZE in sys/inotify.h header so it completely fits in read(2) buffer of most common applications. Applications using smaller read(2) buffer sizes should be fixed by increasing it or supporting concatenation of event parts. Usage of dynamically allocated buffers and read(2)s sized with FIONREAD ioctl(2) or alike can be considered safe. Status ------ The library is almost feature-complete, i.e. it implements and provides most of what can be implemented/provided using kqueue(2). Current state of project is described in following table: Original Patched Inotify event kernel kernel Event flags Supported IN_ACCESS No Yes IN_IGNORED Yes IN_ATTRIB Yes Yes IN_ISDIR Yes IN_CLOSE_WRITE No Yes IN_UNMOUNT Yes IN_CLOSE_NOWRITE No Yes IN_Q_OVERFLOW Yes IN_CREATE Yes Yes IN_DELETE Yes Yes Watch flags Supported IN_DELETE_SELF Yes Yes IN_MODIFY Yes Yes IN_ONLYDIR Yes IN_MOVE_SELF Yes Yes IN_DONT_FOLLOW Yes ** IN_MOVED_FROM Yes * Yes IN_EXCL_UNLINK No *** IN_MOVED_TO Yes * Yes IN_MASK_ADD Yes IN_OPEN No Yes IN_ONESHOT Yes * Only renaming file inside watched directory is supported ** Watching a symlink requires O_SYMLINK kernel patch to be applied *** Libinotify-kqueue behaves as IN_EXCL_UNLINK flag is always set Thanks ------ Thanks to Julio Merino for mentoring this work during the initial library development on Google Summer Of Code 2011. Thanks to Antoine Jacoutot for support, reports, and the work on the related glib-kqueue project. Thanks to bugreporters: Baptiste Daroussin, Stanislav Sedov, Dmitry Okunev, luoqi-git. License ------- libinotify-kqueue is redistributed under the terms of MIT License. See file LICENSE for details.