T. R. Bernstein
c037302c01
Extending an automatically watched tree to a new directory swallowed every error, so a reached watch limit or an unreadable directory left part of the tree unwatched without any sign. No call of the consumer is running at that moment, so the failures now arrive in the event stream as InotifyEvent.watchFailed, after the event that triggered the extension. The library watches what it can first: a reached limit ends the attempt, an unreadable directory is skipped with its subtree, and a directory that vanished in between is not reported. The buffer now carries the library's own events next to the kernel's, which keeps them in order and hides the stream's element type. The test runner drops root's DAC capabilities so that an unreadable directory can be tested.
2.2 KiB
Inotify
Monitor filesystem events on Linux using modern Swift concurrency.
Overview
The Inotify library wraps the Linux inotify API in a Swift-native interface built around actors and async sequences. You create an Inotify/Inotify actor, add watches for the paths you care about, and iterate over the Inotify/Inotify/events property to receive InotifyEvent values as they occur. Most of them carry a FileSystemEvent describing a change to a watched item; the others tell you when the instance cannot deliver every change, after a kernel queue overflow or when a new directory of a watched tree could not be watched.
let inotify = try Inotify()
try inotify.addWatch(path: "/tmp/inbox", mask: [.create, .modify])
for await event in await inotify.events {
switch event {
case .fileSystem(let change):
print("\(change.mask) at \(change.path)")
case .queueOverflow:
print("events were dropped, rescan")
case .watchFailed(let path, let error):
print("changes below \(path) go unreported: \(error)")
}
}
Beyond single-directory watches, the library provides two higher-level methods for monitoring entire directory trees:
Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)installs watches on every existing subdirectory at setup time.Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)does the same and automatically watches subdirectories that are created after setup.
You can also exclude certain file or directory names, exactly or by shell pattern, so that they are skipped during directory resolution and silently dropped from the event stream. See Inotify/Inotify/exclude(names:), Inotify/Inotify/exclude(patterns:) and doc:WatchingDirectoryTrees for details.
All public types conform to Sendable, so they can be safely passed across concurrency boundaries.
Topics
Essentials
Inotify/InotifyInotifyEventFileSystemEventInotifyEventMask
Articles
Errors
InotifyErrorDirectoryResolverError
Low-Level Types
RawInotifyEvent