Fixed a typo, added a howto to the README.

[cl-inotify.git] / README

diff --git a/README b/README
index 662af2a..c35c24e 100644 (file)
--- a/README
+++ b/README
@@ -1,11 +1,62 @@
-CL-NOTIFY
+CL-NOTIFY - Interface to the linux inotify API.
 
-Interface to the linux inotify API.  Working, but unfinished.
+Copyright (C) 2009 Olof-Joachim Frahm
+Released under the GPL3 (or any later version).
 
+Working, but unfinished.
 Implementations currently supported: 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, 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.
 
-Copyright (C) 2009 Olof-Joachim Frahm
-Released under the GPL3 (or any later version).
+
+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)