X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=README.md;h=389c40e59be25130c4e63af75cc43f13933603a5;hb=HEAD;hp=655aaf26f12c1d0213e1334949b0185c7abf9510;hpb=532536021f6a8aac755fd186a629da402d7f37dd;p=cl-inotify.git diff --git a/README.md b/README.md index 655aaf2..389c40e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ CL-INOTIFY - Interface to the Linux inotify(7) API. -Copyright (C) 2011 Olof-Joachim Frahm +Copyright (C) 2011-12 Olof-Joachim Frahm Released under a Simplified BSD license. @@ -9,24 +9,77 @@ Working, but unfinished. Implementations currently running on: SBCL. Uses CFFI, binary-types (from [my Github][1] or see [CLiki][2]) and -trivial-utf-8. Doesn't use iolib, because we don't need most of the +trivial-utf-8. Doesn't use iolib, because I don't need most of the functionality, although it might gain us some implementation -independence (patches which can be conditionally compiled are welcome). +independence (patches which can be conditionally compiled are most +welcome; in any case patches are welcome). A similar package is at [stassats Github][3]. +This document helps only with the aspects of this binding, so reading +the man-page and other information on the inotify-facility may be +needed. Reading the next sections and the docstrings of exported +symbols should get you going, otherwise the source itself may also be of +some value. + + +# REPLSHOT + +Macros make keeping track easier, so the following example is +straightforward: + + > (with-inotify (inotify T ("." :all-events)) + > (do-events (event inotify :blocking-p T) + > (format T "~A~%" event))) + > => + > #S(CL-INOTIFY::INOTIFY-EVENT :WD 1 :MASK (CREATE) :COOKIE 0 :NAME .zshist.LOCK) + > #S(CL-INOTIFY::INOTIFY-EVENT :WD 1 :MASK (OPEN) :COOKIE 0 :NAME .zshist) + > #S(CL-INOTIFY::INOTIFY-EVENT :WD 1 :MASK (MODIFY) :COOKIE 0 :NAME .zshist) + > #S(CL-INOTIFY::INOTIFY-EVENT :WD 1 :MASK (CLOSE-WRITE) :COOKIE 0 :NAME .zshist) + > #S(CL-INOTIFY::INOTIFY-EVENT :WD 1 :MASK (DELETE) :COOKIE 0 :NAME .zshist.LOCK) + > ... + +(Tilde-expansion has to happen at another level, else I would've used +that.) + +The first parameter is (per convention) the symbol to which the queue is +bound, the second is the parameter to `MAKE-INOTIFY`. The `&REST` list +consists of parameter lists for the `WATCH`-function, which is called +for every list before the `&BODY` is executed. We don't actually need +to `UNWATCH` every watched path as closing the queue will also take care +of that. + + +# LOWER-LEVEL USAGE EXAMPLE + +You don't have to use macros: all functionality is available in function +form, although some care should be taken as currently no cleanup handler +is registered for opened queues, or rather their file handles. + + > (use-package '#:cl-inotify) + > (defvar *tmp*) + > (setf *tmp* (make-notify)) + > (watch *tmp* "/var/tmp/" :all-events) + > (next-events *tmp*) + > (close-inotify *tmp*) + # HOWTO +So this section deals in depth with the various bits which make the +examples above tick. + + After loading the library use `MAKE-INOTIFY` to create a new event -queue. The `NONBLOCKING` argument currently determines if we use the -standard `CL:LISTEN` function or `SB-UNIX:UNIX-READ` to check for -available events. +queue. The `NONBLOCKING` argument sets the `SB-POSIX:O-NONBLOCK` bit on +the stream so we don't block while reading. Nevertheless, +`EVENT-AVAILABLE-P` works either way (by using `CL:LISTEN`, or a custom +function which works directly on the file descriptor). The result of `MAKE-INOTIFY` is used with `WATCH` and `UNWATCH`, the first being used to watch a file or directory, the second to stop watching it. The `FLAGS` parameter of `WATCH` is described in the notify(7) -manpage; you can use a combination of the flags (as keywords) to create +man-page; you can use a combination of the flags (as keywords) to create a suitable bitmask. The types `INOTIFY-ADD/READ-FLAG`, `INOTIFY-READ-FLAG` and `INOTIFY-ADD-FLAG` are also defined and can be examined. @@ -61,31 +114,82 @@ The raw API, which doesn't register watched paths, consists of they're exported in case someone doesn't like the upper layers. +# EVENT-BASED PROCESSING + In case you want to use `epoll` or `select` on the event queue you can access the file descriptor yourself and then use the normal functions -afterwards. Currently no such functionality is integrated here. - - -# EXAMPLE - - > (use-package '#:cl-inotify) - > (defvar *tmp*) - > (setf *tmp* (make-notify)) - > (watch *tmp* "/var/tmp/" :all-events) - > (next-events *tmp*) - > (close-inotify *tmp*) +afterwards. Currently no such functionality is integrated here, however +the following sketch shows how something can be accomplished using +iolib: + + (with-unregistered-inotify (inotify T ("." :all-events)) + (flet ((inotify-input (&rest rest) + (declare (ignore rest)) + (format T "~{~A~%~}" (next-events inotify)))) + (iolib:with-event-base (event-base) + (iolib:set-io-handler event-base (inotify-fd inotify) :read #'inotify-input) + (iolib:event-dispatch event-base)))) + +Note that we perform all inotify business only when something happens in +that directory, so instead of doing nothing, we could actually do useful +work, e.g. communicating with a process: This snippet was extracted +from a function which uses behaviour to monitor a LaTeX process for +written files to get the output file name without relying on heuristics +about the generated filename. As it stands you have to split this into +threads, or use `IOLIB:EVENT-DISPATCH` with a timeout while periodically +checking the process status. + + +# REFERENCE + +Here follows a list of valid keywords for the `INOTIFY-FLAG` type: + +* `:ACCESS` +* `:MODIFY` +* `:ATTRIB` +* `:CLOSE-WRITE` +* `:CLOSE-NOWRITE` +* `:CLOSE` +* `:OPEN` +* `:MOVED-FROM` +* `:MOVED-TO` +* `:MOVE` +* `:CREATE` +* `:DELETE` +* `:DELETE-SELF` +* `:MOVE-SELF` +* `:UNMOUNT` +* `:Q-OVERFLOW` +* `:IGNORED` +* `:ONLYDIR` +* `:DONT-FOLLOW` +* `:MASK-ADD` +* `:ISDIR` +* `:ONESHOT` +* `:ALL-EVENTS` + + +The `INOTIFY-EVENT` structure has the slots `WD`, `MASK`, `COOKIE` and +`NAME` (with default `CONC-NAME`: `INOTIFY-EVENT-`). + +The `INOTIFY-INSTANCE` structure has the slots `FD`, `STREAM` and +`NONBLOCKING` with `CONC-NAME` `INOTIFY-`. + +The `REGISTERED-INOTIFY-INSTANCE` includes the previous structure and +only adds the `WATCHED` slot under the same `CONC-NAME`. # TODO - more functionality to examine read events - extend to other APIs? -- make things more implementation independent +- make things more implementation independent (partly done, still needs + fd-streams everywhere, or skip them entirely) - (maybe) don't use the libc for this, direct syscall - (maybe) add iolib replacement for io functions -- easier interface for (e)poll/select maybe using iolib (done, using - CL:LISTEN and/or SB-UNIX:UNIX-READ) - +- the nonblocking mode is pretty useless, because for one the READ + functions still block and also LISTEN seems to work just fine and it's + not even needed for multiplexing, so why keep this in? [1]: https://github.com/Ferada/binary-types [2]: http://www.cliki.net/Binary-types