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