T. R. Bernstein
3c852a565c
The stream's element is now the enum InotifyEvent, and the struct that describes a change to a watched item is FileSystemEvent. A queue overflow was an event with descriptor -1 and an empty path that every consumer had to know about; as a case, the compiler makes them handle it. The enum is also where failed watches of a growing tree will be reported, since no call site can catch them.
53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# ``Inotify``
|
|
|
|
Monitor filesystem events on Linux using modern Swift concurrency.
|
|
|
|
## Overview
|
|
|
|
The Inotify library wraps the Linux [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) 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, such as after a kernel queue overflow.
|
|
|
|
```swift
|
|
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")
|
|
}
|
|
}
|
|
```
|
|
|
|
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/Inotify``
|
|
- ``InotifyEvent``
|
|
- ``FileSystemEvent``
|
|
- ``InotifyEventMask``
|
|
|
|
### Articles
|
|
|
|
- <doc:WatchingDirectoryTrees>
|
|
|
|
### Errors
|
|
|
|
- ``InotifyError``
|
|
- ``DirectoryResolverError``
|
|
|
|
### Low-Level Types
|
|
|
|
- ``RawInotifyEvent``
|