The cl-inotify Reference Manual

This is the cl-inotify Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:06:20 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-inotify

Inotify binding.

Author

Olof-Joachim Frahm <>

License

Simplified BSD License

Long Description

Binding to the Linux inotify(7) API.

Dependencies
  • cffi (system).
  • binary-types (system).
  • trivial-utf-8 (system).
  • osicat (system).
  • iolib (system).
Source

cl-inotify.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 cl-inotify/src

Source

cl-inotify.asd.

Parent Component

cl-inotify (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 cl-inotify/cl-inotify.asd

Source

cl-inotify.asd.

Parent Component

cl-inotify (system).

ASDF Systems

cl-inotify.


4.1.2 cl-inotify/src/package.lisp

Source

cl-inotify.asd.

Parent Component

src (module).

Packages

cl-inotify.


4.1.3 cl-inotify/src/grovel.lisp

Source

cl-inotify.asd.

Parent Component

src (module).


4.1.4 cl-inotify/src/inotify.lisp

Source

cl-inotify.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-inotify

Binding to the Linux inotify(7) API.

Source

package.lisp.

Use List
  • cffi.
  • common-lisp.
Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Macros

Macro: do-events ((var inotify &key blocking-p) &body body)

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.

Package

cl-inotify.

Source

inotify.lisp.

Macro: with-inotify ((inotify &optional nonblocking &rest rest) &body body)

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.

Package

cl-inotify.

Source

inotify.lisp.

Macro: with-unregistered-inotify ((inotify &optional nonblocking &rest rest) &body body)

Like WITH-INOTIFY, but uses MAKE-UNREGISTERED-INOTIFY and WATCH-RAW instead. Useful if you need to monitor just a fixed set of paths.

Package

cl-inotify.

Source

inotify.lisp.


6.1.2 Ordinary functions

Function: close-inotify (inotify)

Closes the inotify event queue.

Package

cl-inotify.

Source

inotify.lisp.

Function: event-available-p (inotify)

Returns T if an event is available on the queue.

Package

cl-inotify.

Source

inotify.lisp.

Function: event-pathname/flags (inotify event &optional handle)

Returns two values PATHNAME and FLAGS for an EVENT which were used during registration. If HANDLE is specified EVENT is ignored.

Package

cl-inotify.

Source

inotify.lisp.

Reader: inotify-event-cookie (instance)
Writer: (setf inotify-event-cookie) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

cookie.

Reader: inotify-event-mask (instance)
Writer: (setf inotify-event-mask) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

mask.

Reader: inotify-event-name (instance)
Writer: (setf inotify-event-name) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

name.

Reader: inotify-event-wd (instance)
Writer: (setf inotify-event-wd) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

wd.

Reader: inotify-fd (instance)
Writer: (setf inotify-fd) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

fd.

Reader: inotify-nonblocking (instance)
Writer: (setf inotify-nonblocking) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

nonblocking.

Reader: inotify-stream (instance)
Writer: (setf inotify-stream) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

stream.

Function: list-watched (inotify)

Returns a LIST of all watched pathnames in no particular order.

Package

cl-inotify.

Source

inotify.lisp.

Function: make-inotify (&optional nonblocking)

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.

Package

cl-inotify.

Source

inotify.lisp.

Function: make-unregistered-inotify (&optional nonblocking)

Creates a new unregistered INOTIFY instance.

Package

cl-inotify.

Source

inotify.lisp.

Function: next-event (inotify)

Reads an event from the queue. Returns NIL if none is available.

Package

cl-inotify.

Source

inotify.lisp.

Function: next-events (inotify)

Reads all available events from the queue. Returns a LIST of events.

Package

cl-inotify.

Source

inotify.lisp.

Function: pathname-handle/flags (inotify pathname)

Returns a CONS cell with the values HANDLE and FLAGS if PATHNAME is being watched by INOTIFY, else NIL. The match is exact.

Package

cl-inotify.

Source

inotify.lisp.

Function: read-event (inotify)

Reads an event from the queue. Blocks if no event is available.

Package

cl-inotify.

Source

inotify.lisp.

Function: read-event-from-stream (stream)

Reads a event from the inotify stream and converts bitmasks on reading.

Package

cl-inotify.

Source

inotify.lisp.

Function: read-raw-event-from-stream (stream)

Reads a raw event from the inotify stream.

Package

cl-inotify.

Source

inotify.lisp.

Function: unwatch (inotify &key pathname event handle)

Disables watching the path associated with the supplied HANDLE (which may be one from a given EVENT) or PATHNAME.

Package

cl-inotify.

Source

inotify.lisp.

Function: unwatch-raw (inotify handle)

Stops watching the path associated with a HANDLE established by WATCH-RAW.

Package

cl-inotify.

Source

inotify.lisp.

Function: watch (inotify pathname flags &key replace-p)

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.

Package

cl-inotify.

Source

inotify.lisp.

Function: watch-raw (inotify pathname flags)

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.

Package

cl-inotify.

Source

inotify.lisp.


6.1.3 Types

Type: inotify-add-flag ()

Valid flags for the WATCH-RAW function.

Package

cl-inotify.

Source

inotify.lisp.

Type: inotify-add/read-flag ()

Shared valid flags for the WATCH-RAW and READ-EVENT functions.

Package

cl-inotify.

Source

inotify.lisp.

Type: inotify-read-flag ()

Valid flags which are returned from READ-EVENT.

Package

cl-inotify.

Source

inotify.lisp.


6.2 Internals


6.2.1 Ordinary functions

Function: copy-inotify-event (instance)
Package

cl-inotify.

Source

inotify.lisp.

Function: copy-inotify-instance (instance)
Package

cl-inotify.

Source

inotify.lisp.

Function: copy-registered-inotify-instance (instance)
Package

cl-inotify.

Source

inotify.lisp.

Function: ensure-list (arg)
Package

cl-inotify.

Source

inotify.lisp.

Function: init-endian ()

Initialises the endianess for the BINARY-TYPES library. Is automatically called when the library is loaded.

Package

cl-inotify.

Source

inotify.lisp.

Function: init-unregistered-inotify (inotify &optional nonblocking)

Creates a new inotify event queue. If NONBLOCKING is set (default), the file descriptor is set to non-blocking I/O.

Package

cl-inotify.

Source

inotify.lisp.

Function: inotify-add-watch (fd pathname mask)

Watches a path on an event queue.

Package

cl-inotify.

Source

inotify.lisp.

Function: inotify-event-p (object)
Package

cl-inotify.

Source

inotify.lisp.

Reader: inotify-handles (instance)
Writer: (setf inotify-handles) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

handles.

Function: inotify-init ()

Initialises a new inotify event queue.

Package

cl-inotify.

Source

inotify.lisp.

Function: inotify-init1 (flags)

Initialises a new inotify event queue and passes some flags along.

Package

cl-inotify.

Source

inotify.lisp.

Function: inotify-instance-p (object)
Package

cl-inotify.

Source

inotify.lisp.

Reader: inotify-pathnames (instance)
Writer: (setf inotify-pathnames) (instance)
Package

cl-inotify.

Source

inotify.lisp.

Target Slot

pathnames.

Function: inotify-rm-watch (fd wd)

Removes a watched path from an event queue.

Package

cl-inotify.

Source

inotify.lisp.

Function: make-inotify-event (&key wd mask cookie name)
Package

cl-inotify.

Source

inotify.lisp.

Function: make-inotify-instance ()
Package

cl-inotify.

Source

inotify.lisp.

Function: make-registered-inotify-instance ()
Package

cl-inotify.

Source

inotify.lisp.

Function: read-new-value (&optional stream)

READs a value from the STREAM and returns it (wrapped in a list).

Package

cl-inotify.

Source

inotify.lisp.

Function: registered-inotify-instance-p (object)
Package

cl-inotify.

Source

inotify.lisp.

Function: sane-user-flags (inotify pathname flags &key replace-p)
Package

cl-inotify.

Source

inotify.lisp.

Function: set-nonblocking (fd nonblocking)

Enables or disables NONBLOCKING mode on a file descriptor FD.

Package

cl-inotify.

Source

inotify.lisp.

Function: translate-keyword-flags (flags)
Package

cl-inotify.

Source

inotify.lisp.

Function: unix-eagain-p (fd)

Returns T on a file descriptor if trying to read raised an EAGAIN error.

Package

cl-inotify.

Source

inotify.lisp.

Function: valid-watch-flag-list-p (list)
Package

cl-inotify.

Source

inotify.lisp.

Function: valid-watch-flag-p (x)
Package

cl-inotify.

Source

inotify.lisp.


6.2.2 Structures

Structure: inotify-event

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.

Package

cl-inotify.

Source

inotify.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: wd
Initform

0

Readers

inotify-event-wd.

Writers

(setf inotify-event-wd).

Slot: mask
Initform

0

Readers

inotify-event-mask.

Writers

(setf inotify-event-mask).

Initform

0

Readers

inotify-event-cookie.

Writers

(setf inotify-event-cookie).

Slot: name
Readers

inotify-event-name.

Writers

(setf inotify-event-name).

Structure: inotify-instance

Contains the stream and file descriptor for a inotify instance.

Package

cl-inotify.

Source

inotify.lisp.

Direct superclasses

structure-object.

Direct subclasses

registered-inotify-instance.

Direct slots
Slot: fd
Readers

inotify-fd.

Writers

(setf inotify-fd).

Slot: stream
Package

common-lisp.

Readers

inotify-stream.

Writers

(setf inotify-stream).

Slot: nonblocking
Readers

inotify-nonblocking.

Writers

(setf inotify-nonblocking).

Structure: registered-inotify-instance

Additionally to the information in INOTIFY-INSTANCE, records watched paths in a dictionary.

Package

cl-inotify.

Source

inotify.lisp.

Direct superclasses

inotify-instance.

Direct slots
Slot: pathnames
Readers

inotify-pathnames.

Writers

(setf inotify-pathnames).

Slot: handles
Readers

inotify-handles.

Writers

(setf inotify-handles).


6.2.3 Types

Type: int ()
Package

cl-inotify.

Source

inotify.lisp.

Type: watch-flag-list ()

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).

Package

cl-inotify.

Source

inotify.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   E   F   I   L   M   N   P   R   S   T   U   V   W  
Index Entry  Section

(
(setf inotify-event-cookie): Public ordinary functions
(setf inotify-event-mask): Public ordinary functions
(setf inotify-event-name): Public ordinary functions
(setf inotify-event-wd): Public ordinary functions
(setf inotify-fd): Public ordinary functions
(setf inotify-handles): Private ordinary functions
(setf inotify-nonblocking): Public ordinary functions
(setf inotify-pathnames): Private ordinary functions
(setf inotify-stream): Public ordinary functions

C
close-inotify: Public ordinary functions
copy-inotify-event: Private ordinary functions
copy-inotify-instance: Private ordinary functions
copy-registered-inotify-instance: Private ordinary functions

D
do-events: Public macros

E
ensure-list: Private ordinary functions
event-available-p: Public ordinary functions
event-pathname/flags: Public ordinary functions

F
Function, (setf inotify-event-cookie): Public ordinary functions
Function, (setf inotify-event-mask): Public ordinary functions
Function, (setf inotify-event-name): Public ordinary functions
Function, (setf inotify-event-wd): Public ordinary functions
Function, (setf inotify-fd): Public ordinary functions
Function, (setf inotify-handles): Private ordinary functions
Function, (setf inotify-nonblocking): Public ordinary functions
Function, (setf inotify-pathnames): Private ordinary functions
Function, (setf inotify-stream): Public ordinary functions
Function, close-inotify: Public ordinary functions
Function, copy-inotify-event: Private ordinary functions
Function, copy-inotify-instance: Private ordinary functions
Function, copy-registered-inotify-instance: Private ordinary functions
Function, ensure-list: Private ordinary functions
Function, event-available-p: Public ordinary functions
Function, event-pathname/flags: Public ordinary functions
Function, init-endian: Private ordinary functions
Function, init-unregistered-inotify: Private ordinary functions
Function, inotify-add-watch: Private ordinary functions
Function, inotify-event-cookie: Public ordinary functions
Function, inotify-event-mask: Public ordinary functions
Function, inotify-event-name: Public ordinary functions
Function, inotify-event-p: Private ordinary functions
Function, inotify-event-wd: Public ordinary functions
Function, inotify-fd: Public ordinary functions
Function, inotify-handles: Private ordinary functions
Function, inotify-init: Private ordinary functions
Function, inotify-init1: Private ordinary functions
Function, inotify-instance-p: Private ordinary functions
Function, inotify-nonblocking: Public ordinary functions
Function, inotify-pathnames: Private ordinary functions
Function, inotify-rm-watch: Private ordinary functions
Function, inotify-stream: Public ordinary functions
Function, list-watched: Public ordinary functions
Function, make-inotify: Public ordinary functions
Function, make-inotify-event: Private ordinary functions
Function, make-inotify-instance: Private ordinary functions
Function, make-registered-inotify-instance: Private ordinary functions
Function, make-unregistered-inotify: Public ordinary functions
Function, next-event: Public ordinary functions
Function, next-events: Public ordinary functions
Function, pathname-handle/flags: Public ordinary functions
Function, read-event: Public ordinary functions
Function, read-event-from-stream: Public ordinary functions
Function, read-new-value: Private ordinary functions
Function, read-raw-event-from-stream: Public ordinary functions
Function, registered-inotify-instance-p: Private ordinary functions
Function, sane-user-flags: Private ordinary functions
Function, set-nonblocking: Private ordinary functions
Function, translate-keyword-flags: Private ordinary functions
Function, unix-eagain-p: Private ordinary functions
Function, unwatch: Public ordinary functions
Function, unwatch-raw: Public ordinary functions
Function, valid-watch-flag-list-p: Private ordinary functions
Function, valid-watch-flag-p: Private ordinary functions
Function, watch: Public ordinary functions
Function, watch-raw: Public ordinary functions

I
init-endian: Private ordinary functions
init-unregistered-inotify: Private ordinary functions
inotify-add-watch: Private ordinary functions
inotify-event-cookie: Public ordinary functions
inotify-event-mask: Public ordinary functions
inotify-event-name: Public ordinary functions
inotify-event-p: Private ordinary functions
inotify-event-wd: Public ordinary functions
inotify-fd: Public ordinary functions
inotify-handles: Private ordinary functions
inotify-init: Private ordinary functions
inotify-init1: Private ordinary functions
inotify-instance-p: Private ordinary functions
inotify-nonblocking: Public ordinary functions
inotify-pathnames: Private ordinary functions
inotify-rm-watch: Private ordinary functions
inotify-stream: Public ordinary functions

L
list-watched: Public ordinary functions

M
Macro, do-events: Public macros
Macro, with-inotify: Public macros
Macro, with-unregistered-inotify: Public macros
make-inotify: Public ordinary functions
make-inotify-event: Private ordinary functions
make-inotify-instance: Private ordinary functions
make-registered-inotify-instance: Private ordinary functions
make-unregistered-inotify: Public ordinary functions

N
next-event: Public ordinary functions
next-events: Public ordinary functions

P
pathname-handle/flags: Public ordinary functions

R
read-event: Public ordinary functions
read-event-from-stream: Public ordinary functions
read-new-value: Private ordinary functions
read-raw-event-from-stream: Public ordinary functions
registered-inotify-instance-p: Private ordinary functions

S
sane-user-flags: Private ordinary functions
set-nonblocking: Private ordinary functions

T
translate-keyword-flags: Private ordinary functions

U
unix-eagain-p: Private ordinary functions
unwatch: Public ordinary functions
unwatch-raw: Public ordinary functions

V
valid-watch-flag-list-p: Private ordinary functions
valid-watch-flag-p: Private ordinary functions

W
watch: Public ordinary functions
watch-raw: Public ordinary functions
with-inotify: Public macros
with-unregistered-inotify: Public macros


A.4 Data types