README

   1 CL-INOTIFY - Interface to the linux inotify API.
   2
   3 Copyright (C) 2009 Olof-Joachim Frahm
   4 Released under the GPL3 (or any later version).
   5
   6 Working, but unfinished.
   7 Implementations currently supported: SBCL
   8
   9 Uses CFFI, the binary-types (ASDF enhanced from
  10 http://github.com/Ferada/cl-notify or see
  11 http://www.cliki.net/Binary-types) and utils-frahm
  12 (http://github.com/Ferada/utils-frahm) libraries.
  13
  14
  15 HOWTO
  16
  17 After loading the library use MAKE-NOTIFY to create a new event queue.
  18 The NONBLOCKING argument currently determines if we use the standard
  19 CL:LISTEN function or SB-UNIX:UNIX-READ to check for available events.
  20
  21 The result of MAKE-NOTIFY is used with WATCH and UNWATCH, the first
  22 being used to watch a file or directory, the second to stop watching
  23 it.  The FLAGS parameter of WATCH is described in the notify(7) manpage;
  24 you can use a combination of the flags (as keywords) to create a
  25 suitable bitmask.
  26
  27 For example, to watch for modified or closed files in a directory, call
  28 (WATCH notify "foo/" '(:modify :close)).
  29
  30 The result of WATCH is a handle (currently a FIXNUM, but I wouldn't rely
  31 on that) which can be fed to UNWATCH, but isn't useful for anything
  32 else.
  33
  34 To finally get the events from the queue, use READ-EVENT (which blocks)
  35 or NEXT-EVENT (which doesn't block).  EVENT-AVAILABLEP does what it
  36 should do, NEXT-EVENTS retrieves all currently available events as a
  37 list and DO-EVENTS (nonblocking) iterates over available events.
  38
  39 The enhanced API registers all watched paths in a table, so you can use
  40 WATCHEDP to check if a pathname (exact match) is being watched and
  41 LIST-WATCHED to return all watched paths as a list.
  42
  43 UNWATCH has to be called with the path or the handle of the watched file
  44 or directory (a path'll looked up in the same table as with WATCHEDP).
  45
  46
  47 The raw API, which doesn't register watched paths, consists of
  48 READ-RAW-EVENT-FROM-STREAM, READ-EVENT-FROM-STREAM, WATCH-RAW and
  49 UNWATCH-RAW.  They are just a thin wrapper around the C functions, but
  50 I've exported them in case someone doesn't like the upper layers.
  51
  52
  53 TODO
  54
  55 - more functionality to examine read events
  56 - extend to other APIs?
  57 - make things more implementation independent
  58 - (maybe) don't use the libc for this, direct syscall
  59
  60 DONE
  61 - easier interface for (e)poll/select maybe using iolib (done, using
  62   CL:LISTEN and/or SB-UNIX:UNIX-READ)