From 8505fc396a872cfc4622714f4eab73b3a30523ae Mon Sep 17 00:00:00 2001 From: Olof-Joachim Frahm Date: Fri, 18 Dec 2009 21:38:12 +0100 Subject: [PATCH] Fixed a typo, added a howto to the README. --- README | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++------ inotify.lisp | 4 ++-- package.lisp | 5 ++++- 3 files changed, 63 insertions(+), 9 deletions(-) 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 -- 1.7.10.4