The file-notify Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

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 Wed Jun 15 04:32:23 2022 GMT+0.

Table of Contents


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.


Previous: , Up: Systems   [Contents][Index]

2.1 file-notify

Access to file change and access notification.

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

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.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

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.


Previous: , Up: Packages   [Contents][Index]

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.


Next: , Previous: , Up: Definitions   [Contents][Index]

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.


Next: , Previous: , Up: Public Interface   [Contents][Index]

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


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Next: , Previous: , Up: Internals   [Contents][Index]

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.


Previous: , Up: Internals   [Contents][Index]

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


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

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

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

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   D   E   F   I   O   P   S   W  
Index Entry  Section

C
Class, event-tclass: Private classes
Class, pollfd-tclass: Private classes
Condition, failure: Public conditions
Condition, inotify-failure: Private conditions

D
documentation.lisp: The file-notify/documentation․lisp file

E
event-tclass: Private classes

F
failure: Public conditions
File, documentation.lisp: The file-notify/documentation․lisp file
File, file-notify.asd: The file-notify/file-notify․asd file
File, fsevent.lisp: The file-notify/fsevent․lisp file
File, inotify.lisp: The file-notify/inotify․lisp file
File, package.lisp: The file-notify/package․lisp file
File, protocol.lisp: The file-notify/protocol․lisp file
File, windows.lisp: The file-notify/windows․lisp file
file-notify: The file-notify system
file-notify.asd: The file-notify/file-notify․asd file
fsevent.lisp: The file-notify/fsevent․lisp file

I
inotify-failure: Private conditions
inotify.lisp: The file-notify/inotify․lisp file

O
org.shirakumo.file-notify: The org․shirakumo․file-notify package

P
Package, org.shirakumo.file-notify: The org․shirakumo․file-notify package
package.lisp: The file-notify/package․lisp file
pollfd-tclass: Private classes
protocol.lisp: The file-notify/protocol․lisp file

S
System, file-notify: The file-notify system

W
windows.lisp: The file-notify/windows․lisp file

Jump to:   C   D   E   F   I   O   P   S   W