README

   1 CL-INOTIFY - Interface to the Linux inotify API.
   2
   3 Copyright (C) 2011 Olof-Joachim Frahm
   4 Released under a Simplified BSD license.
   5
   6 Working, but unfinished.
   7 Implementations currently running on: SBCL.
   8
   9 Uses CFFI, binary-types (from [my Github][1] or see [CLiki][2]) and
  10 trivial-utf-8.  Doesn't use iolib, because we don't need most of the
  11 functionality, although it might gain us some implementation
  12 independence (patches which can be conditionally compiled are welcome).
  13
  14
  15 # HOWTO
  16
  17 After loading the library use `MAKE-INOTIFY` to create a new event
  18 queue.  The `NONBLOCKING` argument currently determines if we use the
  19 standard `CL:LISTEN` function or `SB-UNIX:UNIX-READ` to check for
  20 available events.
  21
  22 The result of `MAKE-INOTIFY` is used with `WATCH` and `UNWATCH`, the first
  23 being used to watch a file or directory, the second to stop watching
  24 it.  The `FLAGS` parameter of `WATCH` is described in the notify(7)
  25 manpage; you can use a combination of the flags (as keywords) to create
  26 a suitable bitmask.  The types `INOTIFY-ADD/READ-FLAG`,
  27 `INOTIFY-READ-FLAG` and `INOTIFY-ADD-FLAG` are also defined and can be
  28 examined.
  29
  30 For example, to watch for modified or closed files in a directory, call
  31 `(WATCH inotify "foo/" '(:modify :close))`.
  32
  33 The result of `WATCH` is a handle (currently a `FIXNUM`, but I wouldn't
  34 rely on that) which can be fed to `UNWATCH` and can be translated from
  35 events with `EVENT-PATHNAME/FLAGS`.
  36
  37 To finally get the events from the queue, use `READ-EVENT` (which
  38 blocks) or `NEXT-EVENT` (which doesn't block).  `EVENT-AVAILABLEP` does
  39 what it should do, `NEXT-EVENTS` retrieves all currently available
  40 events as a list and `DO-EVENTS` (nonblocking) iterates over available
  41 events.
  42
  43 The enhanced API registers all watched paths in a hashtable, so you can
  44 use `PATHNAME-HANDLE/FLAGS` to check if a pathname (exact match) is
  45 being watched and `LIST-WATCHED` to return all watched paths as a list.
  46 `EVENT-PATHNAME/FLAGS` may be used to get the pathname and flags for a
  47 read event.
  48
  49 `UNWATCH` has to be called with the path or the handle of the watched
  50 file or directory (a path will be looked up in the same table as with
  51 `PATHNAME-HANDLE/FLAGS`).
  52
  53
  54 The raw API, which doesn't register watched paths, consists of
  55 `READ-RAW-EVENT-FROM-STREAM`, `READ-EVENT-FROM-STREAM`, `WATCH-RAW` and
  56 `UNWATCH-RAW`.  They are just a thin wrapper around the C functions, but
  57 they're exported in case someone doesn't like the upper layers.
  58
  59
  60 # EXAMPLE
  61
  62     > (use-package '#:cl-inotify)
  63     > (defvar *tmp*)
  64     > (setf *tmp* (make-notify))
  65     > (watch *tmp* "/var/tmp/" :all-events)
  66     > (next-events *tmp*)
  67     > (close-inotify *tmp*)
  68
  69
  70 # TODO
  71
  72 - more functionality to examine read events
  73 - extend to other APIs?
  74 - make things more implementation independent
  75 - (maybe) don't use the libc for this, direct syscall
  76 - (maybe) add iolib replacement for io functions
  77
  78 # DONE
  79
  80 - easier interface for (e)poll/select maybe using iolib (done, using
  81   CL:LISTEN and/or SB-UNIX:UNIX-READ)
  82
  83
  84 LINKS
  85
  86 [1]: https://github.com/Ferada/binary-types
  87 [2]: http://www.cliki.net/Binary-types