arrowd / libinotify-kqueue Goto Github PK

libinotify-kqueue
=================

Copyright (c) 2011-2014 Dmitry Matveev <[email protected]>
Copyright (c) 2014-2018 Vladimir Kondratyev <[email protected]>

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 unawared of
that can lose datastream event position syncronization 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 with increasing it or
with supporting of concatenation of event parts. Usage of dinamicaly
allocated buffers and read(2)s sized with FIONREAD ioctl(2) or alikes
can be considered to be 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.