Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-inotify Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:24:55 2020 GMT+0.
• Introduction | What cl-inotify is all about | |
• Systems | The systems documentation | |
• Modules | The modules documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
CL-INOTIFY - Binding to the Linux inotify(7) API.
Copyright (C) 2011-15 Olof-Joachim Frahm
Released under a Simplified BSD license.
Working, but unfinished.
Uses CFFI, binary-types (from my Github or see CLiki) and trivial-utf-8. Doesn't require iolib, because I don't need most of the functionality, although it might add some implementation independence (patches which can be conditionally compiled are most welcome; in any case patches are always welcome). The tests require fiveam.
Similar packages are inotify and cl-fsnotify.
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.
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.
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*)
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 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)
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.
For example, to watch for modified or closed files in a directory, call
(WATCH inotify "foo/" '(:modify :close))
.
The result of WATCH
is a handle (currently a FIXNUM
, but I wouldn't
rely on that) which can be fed to UNWATCH
and can be translated from
events with EVENT-PATHNAME/FLAGS
.
To finally get the events from the queue, use READ-EVENT
(which
blocks) or NEXT-EVENT
(which doesn't block). EVENT-AVAILABLE-P
does
what it should do, NEXT-EVENTS
retrieves all currently available
events as a list and DO-EVENTS
(nonblocking) iterates over available
events.
The enhanced API registers all watched paths in a hashtable, so you can
use PATHNAME-HANDLE/FLAGS
to check if a pathname (exact match) is
being watched and LIST-WATCHED
to return all watched paths as a list.
EVENT-PATHNAME/FLAGS
may be used to get the pathname and flags for a
read event.
UNWATCH
has to be called with the path or the handle of the watched
file or directory (a path will be looked up in the same table as with
PATHNAME-HANDLE/FLAGS
).
The raw API, which doesn't register watched paths, consists of
READ-RAW-EVENT-FROM-STREAM
, READ-EVENT-FROM-STREAM
, WATCH-RAW
and
UNWATCH-RAW
. They are just a thin wrapper around the C functions, but
they're exported in case someone doesn't like the upper layers.
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, 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.
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
.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-inotify system |
Olof-Joachim Frahm <olof@macrolet.net>
Simplified BSD License
Inotify binding.
Binding to the Linux inotify(7) API.
cl-inotify.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
• The cl-inotify/src module |
cl-inotify (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The cl-inotify.asd file | ||
• The cl-inotify/src/package.lisp file | ||
• The cl-inotify/src/grovel.lisp file | ||
• The cl-inotify/src/inotify.lisp file |
Next: The cl-inotify/src/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-inotify.asd
cl-inotify (system)
Next: The cl-inotify/src/grovel․lisp file, Previous: The cl-inotify․asd file, Up: Lisp files [Contents][Index]
src (module)
src/package.lisp
Next: The cl-inotify/src/inotify․lisp file, Previous: The cl-inotify/src/package․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/grovel.lisp
Previous: The cl-inotify/src/grovel․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/inotify.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The cl-inotify package |
Binding to the Linux inotify(7) API.
package.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros | ||
• Exported functions | ||
• Exported types |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Loops BODY with VAR bound to the next events retrieved from INOTIFY. The macro uses NEXT-EVENT, so reading an event won’t block and the loop terminates if no events are available. If BLOCKING-P is set, the loop blocks if no events are available, otherwise it exits as soon as no events were encountered.
inotify.lisp (file)
Executes BODY with a newly created queue bound to INOTIFY if true.
See MAKE-INOTIFY for more information about possible arguments.
The REST is a list of argument forms for the WATCH function, i.e. one or
more forms (PATHNAME FLAGS &KEY (REPLACE-P T)).
Since the QUEUE is closed on unwinding, this macro doesn’t bother with UNWATCH calls on all WATCHed paths.
inotify.lisp (file)
Like WITH-INOTIFY, but uses MAKE-UNREGISTERED-INOTIFY and WATCH-RAW instead. Useful if you need to monitor just a fixed set of paths.
inotify.lisp (file)
Next: Exported types, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Closes the inotify event queue.
inotify.lisp (file)
Returns T if an event is available on the queue.
inotify.lisp (file)
Returns two values PATHNAME and FLAGS for an EVENT which were used during registration. If HANDLE is specified EVENT is ignored.
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
Returns a LIST of all watched pathnames in no particular order.
inotify.lisp (file)
Creates a new registered INOTIFY instance. In NONBLOCKING mode, the file descriptor is set to non-blocking mode. The resulting object has to be closed with CLOSE-INOTIFY.
inotify.lisp (file)
Creates a new unregistered INOTIFY instance.
inotify.lisp (file)
Reads an event from the queue. Returns NIL if none is available.
inotify.lisp (file)
Reads all available events from the queue. Returns a LIST of events.
inotify.lisp (file)
Returns a CONS cell with the values HANDLE and FLAGS if PATHNAME is being watched by INOTIFY, else NIL. The match is exact.
inotify.lisp (file)
Reads an event from the queue. Blocks if no event is available.
inotify.lisp (file)
Reads a event from the inotify stream and converts bitmasks on reading.
inotify.lisp (file)
Reads a raw event from the inotify stream.
inotify.lisp (file)
Disables watching the path associated with the supplied HANDLE (which may be one from a given EVENT) or PATHNAME.
inotify.lisp (file)
Stops watching the path associated with a HANDLE established by WATCH-RAW.
inotify.lisp (file)
Adds PATHNAME (either pathname or string) to be watched and records the watched paths. FLAGS (a list of keywords) determines how exactly (see inotify(7) for detailed information). Returns a handle which can be used with UNWATCH and EVENT-PATHNAME/FLAGS. If REPLACE-P is set to T (default), the flags mask is replaced rather than OR-ed to the current mask (if it exists). The :MASK-ADD flag is therefore removed from the FLAGS argument.
inotify.lisp (file)
Adds PATHNAME (either of type PATHNAME or STRING) to be watched. FLAGS determines how exactly (see inotify(7) for detailed information) and can be of type LIST, KEYWORD or a raw numerical value (which isn’t checked for validity though). Returns a handle which can be used with UNWATCH-RAW.
inotify.lisp (file)
Previous: Exported functions, Up: Exported definitions [Contents][Index]
Valid flags for the WATCH-RAW function.
inotify.lisp (file)
Shared valid flags for the WATCH-RAW and READ-EVENT functions.
inotify.lisp (file)
Valid flags which are returned from READ-EVENT.
inotify.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal constants | ||
• Internal functions | ||
• Internal structures | ||
• Internal types |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-inotify-20200427-git/src/grovel.processed-grovel-file
Next: Internal structures, Previous: Internal constants, Up: Internal definitions [Contents][Index]
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
Initialises the endianess for the BINARY-TYPES library. Is automatically called when the library is loaded.
inotify.lisp (file)
Creates a new inotify event queue. If NONBLOCKING is set (default), the file descriptor is set to non-blocking I/O.
inotify.lisp (file)
Watches a path on an event queue.
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
Initialises a new inotify event queue.
inotify.lisp (file)
Initialises a new inotify event queue and passes some flags along.
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
Removes a watched path from an event queue.
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
READs a value from the STREAM and returns it (wrapped in a list).
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
Enables or disables NONBLOCKING mode on a file descriptor FD.
inotify.lisp (file)
inotify.lisp (file)
Returns T on a file descriptor if trying to read raised an EAGAIN error.
inotify.lisp (file)
inotify.lisp (file)
inotify.lisp (file)
Next: Internal types, Previous: Internal functions, Up: Internal definitions [Contents][Index]
An inotify native event structure.
WD is the watch/file descriptor,
MASK is the (parsed) combination of events,
COOKIE is a unique integer which connects related events,
NAME optionally identifies a file relative to a watched directory.
inotify.lisp (file)
structure-object (structure)
0
inotify-event-wd (function)
(setf inotify-event-wd) (function)
0
inotify-event-mask (function)
(setf inotify-event-mask) (function)
0
inotify-event-cookie (function)
(setf inotify-event-cookie) (function)
inotify-event-name (function)
(setf inotify-event-name) (function)
Contains the stream and file descriptor for a inotify instance.
inotify.lisp (file)
structure-object (structure)
registered-inotify-instance (structure)
inotify-fd (function)
(setf inotify-fd) (function)
inotify-stream (function)
(setf inotify-stream) (function)
inotify-nonblocking (function)
(setf inotify-nonblocking) (function)
Additionally to the information in INOTIFY-INSTANCE, records watched paths in a dictionary.
inotify.lisp (file)
inotify-instance (structure)
inotify-pathnames (function)
(setf inotify-pathnames) (function)
inotify-handles (function)
(setf inotify-handles) (function)
Previous: Internal structures, Up: Internal definitions [Contents][Index]
inotify.lisp (file)
Valid flags argument for the WATCH function, a list of keywords from INOTIFY-ADD-FLAG. Basically only :MASK-ADD and :ONESHOT are removed. The :MASK-ADD behaviour is replicated with the REPLACE-P argument; the :ONESHOT behaviour doesn’t play well with the WATCH function design (and thus should be used only with WATCH-RAW).
inotify.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | C F L M |
---|
Jump to: | C F L M |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
C D E F I L M N P R S T U V W |
---|
Jump to: | (
C D E F I L M N P R S T U V W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | C F H I M N P S W |
---|
Jump to: | C F H I M N P S W |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C I P R S T W |
---|
Jump to: | C I P R S T W |
---|