The file-notify Reference Manual

This is the file-notify Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 05:10:37 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 file-notify

Access to file change and access notification.

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://shinmera.github.io/file-notify

Source Control

(GIT https://github.com/Shinmera/file-notify.git)

Bug Tracker

https://github.com/Shinmera/file-notify/issues

License

zlib

Version

1.0.0

Defsystem Dependency

trivial-features (system).

Dependencies
  • documentation-utils (system).
  • cffi (system).
  • com-on (system)., for feature :windows
Source

file-notify.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 file-notify/file-notify.asd

Source

file-notify.asd.

Parent Component

file-notify (system).

ASDF Systems

file-notify.


3.1.2 file-notify/package.lisp

Source

file-notify.asd.

Parent Component

file-notify (system).

Packages

org.shirakumo.file-notify.


3.1.3 file-notify/protocol.lisp

Dependency

package.lisp (file).

Source

file-notify.asd.

Parent Component

file-notify (system).

Public Interface
Internals

3.1.4 file-notify/inotify.lisp

If Feature

:linux

Dependency

protocol.lisp (file).

Source

file-notify.asd.

Parent Component

file-notify (system).

Public Interface
Internals

3.1.5 file-notify/windows.lisp

If Feature

:windows

Dependencies
Source

file-notify.asd.

Parent Component

file-notify (system).


3.1.6 file-notify/fsevent.lisp

If Feature

:darwin

Dependencies
Source

file-notify.asd.

Parent Component

file-notify (system).


3.1.7 file-notify/documentation.lisp

Dependencies
Source

file-notify.asd.

Parent Component

file-notify (system).


4 Packages

Packages are listed by definition order.


4.1 org.shirakumo.file-notify

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Macros

Macro: with-events ((file change-type &rest args) &body body)

Shorthand macro to process file change events.

See PROCESS-EVENTS

Package

org.shirakumo.file-notify.

Source

protocol.lisp.


5.1.2 Ordinary functions

Function: init (&key flags)

Initialises the library for use.

You should call this function before anything else. It is safe to call this function an arbitrary number of times, initialisation will only occur once.

See SHUTDOWN

Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: list-watched ()

Returns the list of files the user passed to WATCH.

See WATCH

Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: process-events (function &key timeout)

Processes available file change events.

FUNCTION is called with two arguments – the path of the file changed, and the type of change event that occurred. The function may be called multiple times.

TIMEOUT may be either T, NIL, or a real in [0, infty[.
When T, events will be continuously and indefinitely received. When NIL, events will only be processed if immediately available. When a real, the function will wait up to at most that number of seconds to receive events.

The events received may be of types that were not explicitly requested in the WATCH command, and for files that were not explicitly watched. It is up to you to only look at the files and event types you care about.

The TYPE passed to the function may be one of the following:

:ACCESS — The file was accessed somehow.
:ATTRIBUTE — The file’s attributes were changed. :CLOSE-NOWRITE — The file was closed without writing. :CLOSE-WRITE — The file was closed and written to.
:CREATE — The file was created.
:DELETE — The file was deleted.
:MODIFY — The file was modified somehow.
:MOVE — The file was moved.
:MOVED-FROM — A file was moved and this is the old name. :MOVED-TO — A file was moved and this is the new name. :OPEN — The file was opened.

Note: on MacOS the timeout parameter is almost guaranteed to be useless.

See WATCH
See UNWATCH
See WITH-EVENTS
See NORMALIZE-EVENT

Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: shutdown ()

Cleans up and shuts down the library.

All active watches will be cleared after this call.

After calling this you should not call any other library functions unless you also call INIT again beforehand.

See INIT

Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: unwatch (file/s)

Removes one or more files from the watch list.

FILE/S may either be a single pathname, or a list of pathnames for files to be unwatched. If a given pathname was not watched, it is ignored.

Note that, depending on other files being watched, you may still receive events for a file even after you’ve explicitly unwatched it.

See WATCH
See LIST-WATCHED

Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: watch (file/s &key events)

Adds one or more files to the watch list.

FILE/S may either be a single pathname, or a list of pathnames for
files to be watched. If a given file does not exist or is not
accessible, an error may be signalled.

EVENTS should be T or a list of events to watch. Supported event types
are:

:ACCESS — [LINUX] The file was accessed.
:ALL — [ALL] All available events are watched.
:ATTRIBUTE — [ALL] The file attributes changed.
:CLOSE — [LINUX] A file was closed.
:CLOSE-NOWRITE — [LINUX] A file was closed without writing. :CLOSE-WRITE — [LINUX] A file was closed after writing.
:CREATE — [ALL] A file was created.
:DELETE — [ALL] A file was deleted.
:DELETE-SELF — [LINUX] The file was deleted.
:MODIFY — [ALL] The file was modified.
:MOVE — [ALL] A move or rename occurred.
:MOVE-SELF — [LINUX] The file was moved.
:MOVED-FROM — [LINUX] A file was moved from elsewhere.
:MOVED-TO — [LINUX] A file was moved elsewhere.
:OPEN — [LINUX] The file was opened.
:RENAME-FILE — [WINDOWS] A file was renamed, created, or deleted. :RENAME-DIRECTORY — [WINDOWS] A directory was renamed, created, or deleted. :SECURITY — [WINDOWS] A security descriptor changed
:SIZE — [WINDOWS] The size of the file changed

It is safe to call WATCH on the same file multiple times. Subsequent watches will be ignored, and the watch will only happen once.

When a directory is watched, events for files contained within the directory (subject to the above event filters) will be watched.

Note that it is not guaranteed that the filename you passed will
actually be watched. The underlying system may not accurately support
the capabilities you asked and may upgrade the events watched or even
the files being watched.

This will call INIT for you.

See UNWATCH
See LIST-WATCHED
See PROCESS-EVENTS
See INIT

Package

org.shirakumo.file-notify.

Source

inotify.lisp.


5.1.3 Conditions

Condition: failure

Erro signalled when an OS failure occurs.

Package

org.shirakumo.file-notify.

Source

protocol.lisp.

Direct superclasses

error.

Direct subclasses

inotify-failure.


5.2 Internals


5.2.1 Special variables

Special Variable: *fd*
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Special Variable: *path->watch*
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Special Variable: *watch->path*
Package

org.shirakumo.file-notify.

Source

inotify.lisp.


5.2.2 Symbol macros

Symbol Macro: errno
Package

org.shirakumo.file-notify.

Source

inotify.lisp.


5.2.3 Macros

Macro: check-errno (predicate &body errno-cases)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Macro: define-implementable (name args)
Package

org.shirakumo.file-notify.

Source

protocol.lisp.

Macro: define-implementation (name args &body body)
Package

org.shirakumo.file-notify.

Source

protocol.lisp.


5.2.4 Ordinary functions

Function: %var-accessor-errno ()
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf %var-accessor-errno) ()
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: error-message (errno)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: event-cookie (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf event-cookie) (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: event-length (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf event-length) (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: event-mask (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf event-mask) (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: event-name (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf event-name) (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: event-watch (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf event-watch) (pointer-to-event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: handle-event (path watch event)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

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

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: inotify-close (fd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: inotify-failure (code &key function-name message)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: inotify-init (flags)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: inotify-read (fd buf count)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: inotify-rm-watch (inotify watch)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: map-type (type)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: poll (pollfds n timeout)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: pollfd-events (pointer-to-pollfd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf pollfd-events) (pointer-to-pollfd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: pollfd-fd (pointer-to-pollfd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf pollfd-fd) (pointer-to-pollfd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: pollfd-revents (pointer-to-pollfd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: (setf pollfd-revents) (pointer-to-pollfd)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Function: process (function)
Package

org.shirakumo.file-notify.

Source

inotify.lisp.


5.2.5 Generic functions

Generic Reader: code (condition)
Package

org.shirakumo.file-notify.

Methods
Reader Method: code ((condition inotify-failure))
Source

inotify.lisp.

Target Slot

code.

Generic Reader: function-name (condition)
Package

org.shirakumo.file-notify.

Methods
Reader Method: function-name ((condition inotify-failure))
Source

inotify.lisp.

Target Slot

function-name.

Generic Reader: message (condition)
Package

org.shirakumo.file-notify.

Methods
Reader Method: message ((condition inotify-failure))
Source

inotify.lisp.

Target Slot

message.


5.2.6 Conditions

Condition: inotify-failure
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Direct superclasses

failure.

Direct methods
Direct slots
Slot: function-name
Initform

(quote nil)

Initargs

:function-name

Readers

function-name.

Writers

This slot is read-only.

Slot: code
Initargs

:code

Readers

code.

Writers

This slot is read-only.

Slot: message
Initform

(quote nil)

Initargs

:message

Readers

message.

Writers

This slot is read-only.


5.2.7 Classes

Class: event-tclass
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Direct superclasses
  • foreign-struct-type.
  • translatable-foreign-type.
Class: pollfd-tclass
Package

org.shirakumo.file-notify.

Source

inotify.lisp.

Direct superclasses
  • foreign-struct-type.
  • translatable-foreign-type.

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
C   D   E   F   G   H   I   L   M   P   S   U   W  
Index Entry  Section

%
%var-accessor-errno: Private ordinary functions

(
(setf %var-accessor-errno): Private ordinary functions
(setf event-cookie): Private ordinary functions
(setf event-length): Private ordinary functions
(setf event-mask): Private ordinary functions
(setf event-name): Private ordinary functions
(setf event-watch): Private ordinary functions
(setf pollfd-events): Private ordinary functions
(setf pollfd-fd): Private ordinary functions
(setf pollfd-revents): Private ordinary functions

C
check-errno: Private macros
code: Private generic functions
code: Private generic functions

D
define-implementable: Private macros
define-implementation: Private macros

E
error-message: Private ordinary functions
event-cookie: Private ordinary functions
event-length: Private ordinary functions
event-mask: Private ordinary functions
event-name: Private ordinary functions
event-watch: Private ordinary functions

F
Function, %var-accessor-errno: Private ordinary functions
Function, (setf %var-accessor-errno): Private ordinary functions
Function, (setf event-cookie): Private ordinary functions
Function, (setf event-length): Private ordinary functions
Function, (setf event-mask): Private ordinary functions
Function, (setf event-name): Private ordinary functions
Function, (setf event-watch): Private ordinary functions
Function, (setf pollfd-events): Private ordinary functions
Function, (setf pollfd-fd): Private ordinary functions
Function, (setf pollfd-revents): Private ordinary functions
Function, error-message: Private ordinary functions
Function, event-cookie: Private ordinary functions
Function, event-length: Private ordinary functions
Function, event-mask: Private ordinary functions
Function, event-name: Private ordinary functions
Function, event-watch: Private ordinary functions
Function, handle-event: Private ordinary functions
Function, init: Public ordinary functions
Function, inotify-add-watch: Private ordinary functions
Function, inotify-close: Private ordinary functions
Function, inotify-failure: Private ordinary functions
Function, inotify-init: Private ordinary functions
Function, inotify-read: Private ordinary functions
Function, inotify-rm-watch: Private ordinary functions
Function, list-watched: Public ordinary functions
Function, map-type: Private ordinary functions
Function, poll: Private ordinary functions
Function, pollfd-events: Private ordinary functions
Function, pollfd-fd: Private ordinary functions
Function, pollfd-revents: Private ordinary functions
Function, process: Private ordinary functions
Function, process-events: Public ordinary functions
Function, shutdown: Public ordinary functions
Function, unwatch: Public ordinary functions
Function, watch: Public ordinary functions
function-name: Private generic functions
function-name: Private generic functions

G
Generic Function, code: Private generic functions
Generic Function, function-name: Private generic functions
Generic Function, message: Private generic functions

H
handle-event: Private ordinary functions

I
init: Public ordinary functions
inotify-add-watch: Private ordinary functions
inotify-close: Private ordinary functions
inotify-failure: Private ordinary functions
inotify-init: Private ordinary functions
inotify-read: Private ordinary functions
inotify-rm-watch: Private ordinary functions

L
list-watched: Public ordinary functions

M
Macro, check-errno: Private macros
Macro, define-implementable: Private macros
Macro, define-implementation: Private macros
Macro, with-events: Public macros
map-type: Private ordinary functions
message: Private generic functions
message: Private generic functions
Method, code: Private generic functions
Method, function-name: Private generic functions
Method, message: Private generic functions

P
poll: Private ordinary functions
pollfd-events: Private ordinary functions
pollfd-fd: Private ordinary functions
pollfd-revents: Private ordinary functions
process: Private ordinary functions
process-events: Public ordinary functions

S
shutdown: Public ordinary functions

U
unwatch: Public ordinary functions

W
watch: Public ordinary functions
with-events: Public macros


A.4 Data types