1fcc4238f6a0b2b48f31c289fb704c199e71d818
[cl-inotify.git] / 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 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 and can be translated from events
29 with EVENT-PATHNAME/FLAGS.
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 PATHNAME-HANDLE/FLAGS to check if a pathname (exact match) is being
38 watched and LIST-WATCHED to return all watched paths as a list.
39 EVENT-PATHNAME/FLAGS may be used to get the pathname and flags for a
40 read event.
41
42 UNWATCH has to be called with the path or the handle of the watched file
43 or directory (a path'll looked up in the same table as with WATCHEDP).
44
45
46 The raw API, which doesn't register watched paths, consists of
47 READ-RAW-EVENT-FROM-STREAM, READ-EVENT-FROM-STREAM, WATCH-RAW and
48 UNWATCH-RAW.  They are just a thin wrapper around the C functions, but
49 I've exported them in case someone doesn't like the upper layers.
50
51
52 TODO
53
54 - more functionality to examine read events
55 - extend to other APIs?
56 - make things more implementation independent
57 - (maybe) don't use the libc for this, direct syscall
58
59 DONE
60 - easier interface for (e)poll/select maybe using iolib (done, using
61   CL:LISTEN and/or SB-UNIX:UNIX-READ)
62
63
64 LINKS
65
66 [1]: http://github.com/Ferada/cl-notify
67 [2]: http://www.cliki.net/Binary-types