7.8 Monitoring file system events

The inotify API allows us to monitor file system events; for an overview of the API we must refer to the inotify(7) manual page.

Struct Type: struct-inotify-event

Scheme level representation of the C language type struct inotify-event, see the inotify(7) manual page. It has the following fields:

wd

An exact integer in the range of the C language type int.

mask

An exact integer in the range of the C language type uint32_t.

cookie

An exact integer in the range of the C language type uint32_t.

len

An exact integer in the range of the C language type uint32_t. Zero or the number of bytes in the pathname represented by the name field.

name

A bytevector representing a file system pathname or #f.

Function: make-struct-inotify-event

Function: make-struct-inotify-event wd mask cookie len name

Build and return a new instance of struct-inotify-event. When no arguments are given: all the fields are set to the fixnum zero, but the field name which is set to #f.

Function: struct-inotify-event? obj

Return #t if obj is an instance of struct-inotify-event.

Function: struct-inotify-event-wd iev

Function: struct-inotify-event-mask iev

Function: struct-inotify-event-cookie iev

Function: struct-inotify-event-len iev

Function: struct-inotify-event-name iev

Accessors for the fields of struct-inotify-event.

Function: set-struct-inotify-event-wd! iev value

Function: set-struct-inotify-event-mask! iev value

Function: set-struct-inotify-event-cookie! iev value

Function: set-struct-inotify-event-len! iev value

Function: set-struct-inotify-event-name! iev value

Mutators for the fields of struct-inotify-event.

Function: inotify-init

Interface to the C function inotify_init(), see the manual page inotify_init(2). Initialise a new inotify instance; if successful return a file descriptor associated to a new event queue, else raise an exception.

Function: inotify-init1 flags

Interface to the C function inotify_init1(), see the manual page inotify_init1(2). Initialise a new inotify instance; if successful return a file descriptor associated to a new event queue, else raise an exception.

flags must be a fixnum representing the bitwise inclusive OR combination of IN_NONBLOCK and IN_CLOEXEC.

Function: inotify-add-watch fd pathname mask

Interface to the C function inotify_add_watch(), see the manual page inotify_add_watch(2). Add a watch to an initialised inotify instance; if successful return an exact integer representing watch descriptor, else raise an exception.

fd must be a finxum representing the file descriptor associated to the inotify instance. pathname must be a Scheme string or bytevector representing the pathname to watch. mask must be an exact integer in the range of the C language type uint32_t representing the watch mask.

Function: inotify-rm-watch fd wd

Interface to the C function inotify_rm_watch(), see the manual page inotify_rm_watch(2). Remove an existing watch from an inotify instance; if successful return unspecified values, else raise an exception.

fd must be a fixnum representing the file descriptor associated to the inotify instance. wd must be an exact integer in the range of the C language type int representing the watch descriptor.

The following meaningless example shows how to watch for a modification event on a file:

#!r6rs
(import (vicare)
  (prefix (vicare linux) lx.)
  (prefix (vicare posix) px.)
  (vicare platform constants)
  (vicare language-extensions syntaxes))

(let* ((infd     (lx.inotify-init))
       (pathname "inotify.test")
       (fd       (px.open pathname
                          (fxior O_CREAT O_EXCL O_RDWR)
                          (fxior S_IRUSR S_IWUSR))))
  (unwind-protect
       (let ((wd (lx.inotify-add-watch infd pathname
                                       IN_MODIFY)))
         (unwind-protect
              (begin
                (px.write fd #vu8(1 2 3))
                ;; let the event happen
                (px.select-fd infd 1 0)
                (let ((ev (lx.inotify-read infd)))
                  (lx.struct-inotify-event? ev)
                  ⇒ #t
                  (= wd (lx.struct-inotify-event-wd ev))
                  ⇒ #t
                  (lx.struct-inotify-event-len ev)
                  ⇒ 0
                  (lx.struct-inotify-event-name ev)
                  ⇒ #f
                  ))
              (lx.inotify-rm-watch infd wd)))
     (px.close fd)
     (delete-file pathname)))