Changed license to Simplified BSD.
[cl-inotify.git] / README
diff --git a/README b/README
index f63d46f..6dee4f1 100644 (file)
--- a/README
+++ b/README
@@ -1,8 +1,65 @@
-CL-NOTIFY
+CL-INOTIFY - Interface to the Linux inotify API.
 
-Interface to the linux inotify API.  Rudimentary, but working.
+Copyright (C) 2011 Olof-Joachim Frahm
+Released under a Simplified BSD license.
 
-Implementations currently supported: SBCL
+Working, but unfinished.
+Implementations currently tested on: SBCL.
 
-Uses the binary-types library (ASDF enhanced from
-http://github.com/Ferada/cl-notify or see http://www.cliki.net/Binary-types).
+Uses CFFI and the binary-types library (from [1] or see [2]).
+
+
+HOWTO
+
+After loading the library use MAKE-INOTIFY 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-INOTIFY 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 inotify "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 hashtable, 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)
+
+
+LINKS
+
+[1]: http://github.com/Ferada/cl-notify
+[2]: http://www.cliki.net/Binary-types