The file-notify Reference Manual

Table of Contents

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 3.0 "Montgomery Scott" on Wed Oct 13 10:52:41 2021 GMT+0.


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

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)


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

2 Systems

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


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

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
Source

file-notify.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 file-notify.asd

Location

file-notify.asd

Systems

file-notify (system)


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

3.1.2 file-notify/package.lisp

Parent

file-notify (system)

Location

package.lisp

Packages

org.shirakumo.file-notify


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

3.1.3 file-notify/protocol.lisp

Dependency

package.lisp (file)

Parent

file-notify (system)

Location

protocol.lisp

Exported Definitions
Internal Definitions

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

3.1.4 file-notify/inotify.lisp

If Feature

linux

Dependency

protocol.lisp (file)

Parent

file-notify (system)

Location

inotify.lisp

Exported Definitions
Internal Definitions

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

3.1.5 file-notify/windows.lisp

If Feature

windows

Dependencies
Parent

file-notify (system)

Location

windows.lisp


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

3.1.6 file-notify/fsevent.lisp

If Feature

darwin

Dependencies
Parent

file-notify (system)

Location

fsevent.lisp


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

3.1.7 file-notify/documentation.lisp

Dependencies
Parent

file-notify (system)

Location

documentation.lisp


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

4 Packages

Packages are listed by definition order.


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

4.1 org.shirakumo.file-notify

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.6 Conditions

Condition: inotify-failure ()
Package

org.shirakumo.file-notify

Source

inotify.lisp (file)

Direct superclasses

failure (condition)

Direct methods
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)


Previous: , Up: Internal definitions   [Contents][Index]

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)

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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, file-notify.asd: The file-notify․asd file
File, Lisp, file-notify/documentation.lisp: The file-notify/documentation․lisp file
File, Lisp, file-notify/fsevent.lisp: The file-notify/fsevent․lisp file
File, Lisp, file-notify/inotify.lisp: The file-notify/inotify․lisp file
File, Lisp, file-notify/package.lisp: The file-notify/package․lisp file
File, Lisp, file-notify/protocol.lisp: The file-notify/protocol․lisp file
File, Lisp, file-notify/windows.lisp: The file-notify/windows․lisp file
file-notify.asd: The file-notify․asd file
file-notify/documentation.lisp: The file-notify/documentation․lisp file
file-notify/fsevent.lisp: The file-notify/fsevent․lisp file
file-notify/inotify.lisp: The file-notify/inotify․lisp file
file-notify/package.lisp: The file-notify/package․lisp file
file-notify/protocol.lisp: The file-notify/protocol․lisp file
file-notify/windows.lisp: The file-notify/windows․lisp file

L
Lisp File, file-notify.asd: The file-notify․asd file
Lisp File, file-notify/documentation.lisp: The file-notify/documentation․lisp file
Lisp File, file-notify/fsevent.lisp: The file-notify/fsevent․lisp file
Lisp File, file-notify/inotify.lisp: The file-notify/inotify․lisp file
Lisp File, file-notify/package.lisp: The file-notify/package․lisp file
Lisp File, file-notify/protocol.lisp: The file-notify/protocol․lisp file
Lisp File, file-notify/windows.lisp: The file-notify/windows․lisp file

Jump to:   F   L  

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: Internal functions

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

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

D
define-implementable: Internal macros
define-implementation: Internal macros

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

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

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

H
handle-event: Internal functions

I
init: Exported functions
inotify-add-watch: Internal functions
inotify-close: Internal functions
inotify-failure: Internal functions
inotify-init: Internal functions
inotify-read: Internal functions
inotify-rm-watch: Internal functions

L
list-watched: Exported functions

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

P
poll: Internal functions
pollfd-events: Internal functions
pollfd-fd: Internal functions
pollfd-revents: Internal functions
process: Internal functions
process-events: Exported functions

S
shutdown: Exported functions

U
unwatch: Exported functions

W
watch: Exported functions
with-events: Exported macros

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

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

A.3 Variables

Jump to:   *  
C   E   F   M   S  
Index Entry  Section

*
*fd*: Internal special variables
*path->watch*: Internal special variables
*watch->path*: Internal special variables

C
code: Internal conditions

E
errno: Internal symbol macros

F
function-name: Internal conditions

M
message: Internal conditions

S
Slot, code: Internal conditions
Slot, function-name: Internal conditions
Slot, message: Internal conditions
Special Variable, *fd*: Internal special variables
Special Variable, *path->watch*: Internal special variables
Special Variable, *watch->path*: Internal special variables
Symbol Macro, errno: Internal symbol macros

Jump to:   *  
C   E   F   M   S  

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

A.4 Data types

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

C
Class, event-tclass: Internal classes
Class, pollfd-tclass: Internal classes
Condition, failure: Exported conditions
Condition, inotify-failure: Internal conditions

E
event-tclass: Internal classes

F
failure: Exported conditions
file-notify: The file-notify system

I
inotify-failure: Internal conditions

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

P
Package, org.shirakumo.file-notify: The org․shirakumo․file-notify package
pollfd-tclass: Internal classes

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

Jump to:   C   E   F   I   O   P   S