Files

T

T. R. Bernstein 3c852a565c Deliver an event enum with the queue overflow as its own case

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.

2026-09-19 00:10:35 +02:00

2.0 KiB

Raw Blame History

`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, such as after a kernel queue overflow.

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

2.0 KiB Raw Blame History

Inotify