CL-INOTIFY - Interface to the linux inotify API.

Copyright (C) 2009 Olof-Joachim Frahm
Released under the GPL3 (or any later version).

Working, but unfinished.
Implementations currently supported: SBCL

Uses CFFI, the binary-types (ASDF enhanced from
http://github.com/Ferada/cl-notify or see
http://www.cliki.net/Binary-types) and utils-frahm
(http://github.com/Ferada/utils-frahm) libraries.


HOWTO

After loading the library use MAKE-NOTIFY to create a new event queue.
The NONBLOCKING argument currently determines if we use the standard
CL:LISTEN function or SB-UNIX:UNIX-READ to check for available events.

The result of MAKE-NOTIFY is used with WATCH and UNWATCH, the first
being used to watch a file or directory, the second to stop watching
it.  The FLAGS parameter of WATCH is described in the notify(7) manpage;
you can use a combination of the flags (as keywords) to create a
suitable bitmask.

For example, to watch for modified or closed files in a directory, call
(WATCH notify "foo/" '(:modify :close)).

The result of WATCH is a handle (currently a FIXNUM, but I wouldn't rely
on that) which can be fed to UNWATCH, but isn't useful for anything
else.

To finally get the events from the queue, use READ-EVENT (which blocks)
or NEXT-EVENT (which doesn't block).  EVENT-AVAILABLEP does what it
should do, NEXT-EVENTS retrieves all currently available events as a
list and DO-EVENTS (nonblocking) iterates over available events.

The enhanced API registers all watched paths in a table, so you can use
WATCHEDP to check if a pathname (exact match) is being watched and
LIST-WATCHED to return all watched paths as a list.

UNWATCH has to be called with the path or the handle of the watched file
or directory (a path'll looked up in the same table as with WATCHEDP).


The raw API, which doesn't register watched paths, consists of
READ-RAW-EVENT-FROM-STREAM, READ-EVENT-FROM-STREAM, WATCH-RAW and
UNWATCH-RAW.  They are just a thin wrapper around the C functions, but
I've exported them in case someone doesn't like the upper layers.


TODO

- more functionality to examine read events
- extend to other APIs?
- make things more implementation independent
- (maybe) don't use the libc for this, direct syscall

DONE
- easier interface for (e)poll/select maybe using iolib (done, using
  CL:LISTEN and/or SB-UNIX:UNIX-READ)