README.md

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