Racket bindings for the Linux inotify API

8.12

Racket bindings for the Linux inotify API🔗ℹ

package: inotify

Racket bindings for the Linux inotify file system event monitor API. A useful alternative to Racket’s native file system change events API that offers finer control over what events to be alerted about.

Currently only supported for 64-bit Racket.

It’s basically the same workflow as the native C API: First create an inotify descriptor/instance with open-inotify-instance, add files to monitor for given events with inotify-set-watch, and read inotify-events with read-inotify-event. inotify-instance objects are also sync-able; their synchronization result is an inotify-event.

procedure
(inotify-instance? obj) → boolean?
obj : any/c

Returns true if the given argument is an inotify instance.

procedure
(open-inotify-instance) → inotify-instance?

Returns a new inotify session instance.

Wrapper around the C inotify_init(2) syscall.

procedure
(close-inotify-instance in) → void?
in : inotify-instance?

Closes and frees operating system resources associated with the instance.

procedure
(inotify-watch? obj) → boolean?
obj : any/c

Returns true if the given argument is an inotify watch descriptor.

procedure
(inotify-set-watch in file events) → inotify-watch?
  in : inotify-instance?
  file : path-string?
  events : (listof symbol?)

Starts watching the given file for the given inotify events, which are symbols with the same names as the C constants - 'IN_CREATE, 'IN_MODIFY, etc. Returns a watch descriptor object that can be used to remove the watch, and used as a key for returned events.

Wrapper around the C inotify_add_watch(2) syscall.

procedure
(inotify-set-watch* in watches) → (listof inotify-watch?)
in : inotify-instance?
watches : (listof (list/c path-string? (listof symbol?)))

Adds all the given files and their desired events to the inotify watch list.

procedure
(inotify-remove-watch in wd) → void?
in : inotify-instance?
wd : inotify-watch?

Removes the given watch descriptor from the inotify instance’s monitored events.

Wrapper around the C inotify_rm_watch(2) syscall.

procedure
(call-with-inotify-instance proc) → any
  proc : (-> inotify-instance? any)
(call-with-inotify-instance watches proc) → any
  watches : (listof (list/c path-string? (listof symbol?)))
  proc : (-> inotify-instance? (listof inotify-watch?) any)

Create an inotify instance and pass it to proc, optionally creating the given watch instances and also passing them as a second argument. The inotify instance is closed when call-with-inotify-instance returns. Returns the value(s) returned by proc.

struct
(struct inotify-event (wd flags cookie name)
    #:transparent)
  wd : inotify-watch?
  flags : (listof symbol?)
  cookie : exact-nonnegative-integer?
  name : (or/c path? #f)

Information about a triggered watch event. Wrapper for the C inotify_event structure. Events are list of symbols instead of a bitmask.

procedure
(read-inotify-event in) → inotify-event?
in : inotify-instance?

Returns an inotify event, blocking until one is available if none are currently pending.

procedure
(read-inotify-event* in) → (or/c inotify-event? #f)
in : inotify-instance?

Returns an inotify event, or #f if none are currently pending.

procedure
(inotify-max-user-instances) → exact-integer?

The maximum number of inotify instances a single UID can have open.

procedure
(inotify-max-user-watches) → exact-integer?

The maximum number of watches a single UID can have active.

procedure
(inotify-max-queued-events) → exact-integer?

The maximum number of events that can be queued up waiting to be read.