From: Olof-Joachim Frahm <Olof.Frahm@web.de>
Date: Fri, 18 Dec 2009 20:38:12 +0000 (+0100)
Subject: Fixed a typo, added a howto to the README.
X-Git-Url: http://repo.macrolet.net/gitweb/?p=cl-inotify.git;a=commitdiff_plain;h=8505fc396a872cfc4622714f4eab73b3a30523ae

Fixed a typo, added a howto to the README.
---

diff --git a/README b/README
index 662af2a..c35c24e 100644
--- 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)
diff --git a/inotify.lisp b/inotify.lisp
index be9d9c6..ebeadfc 100644
--- a/inotify.lisp
+++ b/inotify.lisp
@@ -109,7 +109,7 @@ NAME optionally identifies a file relative to a watched directory."
 
 ;;;; basic wrapping of the API
 
-(defun read-raw-event (stream)
+(defun read-raw-event-from-stream (stream)
   "Reads a raw event from the inotify stream."
   (let* ((event (binary-types:read-binary 'inotify-event stream))
 	 (len (binary-types:read-binary 'binary-types:u32 stream)))
@@ -122,7 +122,7 @@ NAME optionally identifies a file relative to a watched directory."
 
 (defun read-event-from-stream (stream)
   "Reads a event from the inotify stream and converts bitmasks on reading."
-  (let ((event (read-raw-event stream)))
+  (let ((event (read-raw-event-from-stream stream)))
     (with-slots (mask) event
       (setf mask (foreign-bitfield-symbols 'inotify-flag mask)))
     event))
diff --git a/package.lisp b/package.lisp
index 0f7b202..5978614 100644
--- a/package.lisp
+++ b/package.lisp
@@ -7,11 +7,14 @@
 	   #:inotify-read-flag
 	   #:inotify-add-flag
 
+	   ;;; very raw
+	   #:read-raw-event-from-stream
+
 	   #:close-notify
 
 	   ;;; event parsing functions
 	   #:make-unregistered-notify
-	   #:read-raw-event
+	   #:read-event-from-stream
 	   #:watch-raw
 	   #:unwatch-raw