The file-notify Reference Manual

Table of Contents

The file-notify Reference Manual

This is the file-notify Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:52:41 2021 GMT+0.

1 Introduction

## About File-Notify
This is a small OS portability library to get notifications for file access and changes.

## How To
For the purpose of this tutorial we will assume ``org.shirakumo.file-notify`` has the nickname ``notify``.

Before we can even begin, we need to add a file that we want to watch.

:: common lisp
(notify:watch "~/quicklisp/")
::

Watching a directory will report all the events happening within. We can listen for them like this:

:: common lisp
(notify:with-events (file change :timeout T)
  (print (list file change)))
::

Adding, removing, or changing a file within ``~/quicklisp/`` should now show a corresponding event at the REPL.

If we no longer care about a file, it can also be ``unwatch``ed again.

For more detailed information on the behaviour and capabilities, please refer to the individual functions.

## Supported Platforms
The following platforms are supported:

- Linux (inotify)
- Windows
- macOS (fsevent)

2 Systems

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

2.1 file-notify

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

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

Description

Access to file change and access notification.

Version

1.0.0

Defsystem Dependency

trivial-features

Dependencies

• documentation-utils
• cffi
• com-on (for feature windows)

Source

file-notify.asd (file)

Components

• package.lisp (file)
• protocol.lisp (file)
• inotify.lisp (file)
• windows.lisp (file)
• fsevent.lisp (file)
• documentation.lisp (file)

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

Location

file-notify.asd

Systems

file-notify (system)

3.1.2 file-notify/package.lisp

Parent

file-notify (system)

Location

package.lisp

Packages

org.shirakumo.file-notify

3.1.3 file-notify/protocol.lisp

Dependency

package.lisp (file)

Parent

file-notify (system)

Location

protocol.lisp

Exported Definitions

• failure (condition)
• with-events (macro)

Internal Definitions

• define-implementable (macro)
• define-implementation (macro)

3.1.4 file-notify/inotify.lisp

If Feature

linux

Dependency

protocol.lisp (file)

Parent

file-notify (system)

Location

inotify.lisp

Exported Definitions

• init (function)
• list-watched (function)
• process-events (function)
• shutdown (function)
• unwatch (function)
• watch (function)

Internal Definitions

• %var-accessor-errno (function)
• (setf %var-accessor-errno) (function)
• *fd* (special variable)
• *path->watch* (special variable)
• *watch->path* (special variable)
• check-errno (macro)
• code (method)
• errno (symbol macro)
• error-message (function)
• event-cookie (function)
• (setf event-cookie) (function)
• event-length (function)
• (setf event-length) (function)
• event-mask (function)
• (setf event-mask) (function)
• event-name (function)
• (setf event-name) (function)
• event-tclass (class)
• event-watch (function)
• (setf event-watch) (function)
• function-name (method)
• handle-event (function)
• inotify-add-watch (function)
• inotify-close (function)
• inotify-failure (function)
• inotify-failure (condition)
• inotify-init (function)
• inotify-read (function)
• inotify-rm-watch (function)
• map-type (function)
• message (method)
• poll (function)
• pollfd-events (function)
• (setf pollfd-events) (function)
• pollfd-fd (function)
• (setf pollfd-fd) (function)
• pollfd-revents (function)
• (setf pollfd-revents) (function)
• pollfd-tclass (class)
• process (function)

3.1.5 file-notify/windows.lisp

If Feature

windows

Dependencies

• inotify.lisp (file)
• protocol.lisp (file)

Parent

file-notify (system)

Location

windows.lisp

3.1.6 file-notify/fsevent.lisp

If Feature

darwin

Dependencies

• windows.lisp (file)
• inotify.lisp (file)
• protocol.lisp (file)

Parent

file-notify (system)

Location

fsevent.lisp

3.1.7 file-notify/documentation.lisp

Dependencies

• fsevent.lisp (file)
• windows.lisp (file)
• inotify.lisp (file)
• protocol.lisp (file)

Parent

file-notify (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 org.shirakumo.file-notify

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• failure (condition)
• init (function)
• list-watched (function)
• process-events (function)
• shutdown (function)
• unwatch (function)
• watch (function)
• with-events (macro)

Internal Definitions

• %var-accessor-errno (function)
• (setf %var-accessor-errno) (function)
• *fd* (special variable)
• *path->watch* (special variable)
• *watch->path* (special variable)
• check-errno (macro)
• code (generic function)
• code (method)
• define-implementable (macro)
• define-implementation (macro)
• errno (symbol macro)
• error-message (function)
• event-cookie (function)
• (setf event-cookie) (function)
• event-length (function)
• (setf event-length) (function)
• event-mask (function)
• (setf event-mask) (function)
• event-name (function)
• (setf event-name) (function)
• event-tclass (class)
• event-watch (function)
• (setf event-watch) (function)
• function-name (generic function)
• function-name (method)
• handle-event (function)
• inotify-add-watch (function)
• inotify-close (function)
• inotify-failure (function)
• inotify-failure (condition)
• inotify-init (function)
• inotify-read (function)
• inotify-rm-watch (function)
• map-type (function)
• message (generic function)
• message (method)
• poll (function)
• pollfd-events (function)
• (setf pollfd-events) (function)
• pollfd-fd (function)
• (setf pollfd-fd) (function)
• pollfd-revents (function)
• (setf pollfd-revents) (function)
• pollfd-tclass (class)
• process (function)

5 Definitions

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

5.1 Exported definitions

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 (file)

5.1.2 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 (file)

Function: list-watched ()

Returns the list of files the user passed to WATCH.

See WATCH

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

5.1.3 Conditions

Condition: failure ()

Erro signalled when an OS failure occurs.

Package

org.shirakumo.file-notify

Source

protocol.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

inotify-failure (condition)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *fd*

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Special Variable: *path->watch*

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Special Variable: *watch->path*

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

5.2.2 Symbol macros

Symbol Macro: errno

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Expansion

(org.shirakumo.file-notify::%var-accessor-errno)

5.2.3 Macros

Macro: check-errno PREDICATE &body ERRNO-CASES

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Macro: define-implementable NAME ARGS

Package

org.shirakumo.file-notify

Source

protocol.lisp (file)

Macro: define-implementation NAME ARGS &body BODY

Package

org.shirakumo.file-notify

Source

protocol.lisp (file)

5.2.4 Functions

Function: %var-accessor-errno ()

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

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: error-message ERRNO

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: event-cookie POINTER-TO-EVENT

Function: (setf event-cookie) VALUE POINTER-TO-EVENT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: event-length POINTER-TO-EVENT

Function: (setf event-length) VALUE POINTER-TO-EVENT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: event-mask POINTER-TO-EVENT

Function: (setf event-mask) VALUE POINTER-TO-EVENT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: event-name POINTER-TO-EVENT

Function: (setf event-name) VALUE POINTER-TO-EVENT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: event-watch POINTER-TO-EVENT

Function: (setf event-watch) VALUE POINTER-TO-EVENT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: handle-event PATH WATCH EVENT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: inotify-add-watch INOTIFY PATHNAME MASK

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: inotify-close FD

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: inotify-failure CODE &key FUNCTION-NAME MESSAGE

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: inotify-init FLAGS

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: inotify-read FD BUF COUNT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: inotify-rm-watch INOTIFY WATCH

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: map-type TYPE

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: poll POLLFDS N TIMEOUT

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: pollfd-events POINTER-TO-POLLFD

Function: (setf pollfd-events) VALUE POINTER-TO-POLLFD

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: pollfd-fd POINTER-TO-POLLFD

Function: (setf pollfd-fd) VALUE POINTER-TO-POLLFD

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: pollfd-revents POINTER-TO-POLLFD

Function: (setf pollfd-revents) VALUE POINTER-TO-POLLFD

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Function: process FUNCTION

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

5.2.5 Generic functions

Generic Function: code CONDITION

Package

org.shirakumo.file-notify

Methods

Method: code (CONDITION inotify-failure)

Source

inotify.lisp (file)

Generic Function: function-name CONDITION

Package

org.shirakumo.file-notify

Methods

Method: function-name (CONDITION inotify-failure)

Source

inotify.lisp (file)

Generic Function: message CONDITION

Package

org.shirakumo.file-notify

Methods

Method: message (CONDITION inotify-failure)

Source

inotify.lisp (file)

5.2.6 Conditions

Condition: inotify-failure ()

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Direct superclasses

failure (condition)

Direct methods

• message (method)
• code (method)
• function-name (method)

Direct slots

Slot: function-name

Initargs

:function-name

Initform

(quote nil)

Readers

function-name (generic function)

Slot: code

Initargs

:code

Readers

code (generic function)

Slot: message

Initargs

:message

Initform

(quote nil)

Readers

message (generic function)

5.2.7 Classes

Class: event-tclass ()

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

Class: pollfd-tclass ()

Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types