FSEvents is a file system events API in Apple's macOS operating system that allows applications to register for notifications when the contents of a directory hierarchy are modified. It provides a mechanism for applications to detect changes to files and directories on a local filesystem.
Overview
When the filesystem is changed, the macOS kernel passes notifications through the special device file /dev/fsevents to a userspace process called fseventsd. This daemon aggregates multiple changes to a given directory tree that occur within a short period of time and then notifies applications that have registered to receive changes for the affected directories.
Technical Architecture
The FSEvents system consists of three primary components:
- Kernel code that passes raw event data to user space through the special device file.
- A daemon (
fseventsd) that filters the event stream and sends notifications to registered applications. - A database that stores a persistent record of all changes.
History and Development
FSEvents was introduced in Mac OS X 10.5 (Leopard) in 2007 as part of Apple's "Leopard Technology Series for Developers." It was designed to address the need for efficient monitoring of large directory hierarchies.
In its initial implementation, FSEvents did not "watch" the filesystem in the manner of Linux's inotify. The API did not provide notifications for changes to individual files; instead, an application registered to receive notifications of changes to a given directory and had to determine for itself which specific file or files had changed.
With the release of Mac OS X 10.7 (Lion) in 2011, Apple added the capability to register for notifications of individual file modifications through the kFSEventStreamCreateFlagFileEvents flag.
Features
The API provides several notable capabilities:
- Change notifications: Applications can be notified when directory hierarchies are modified.
- Persistent change tracking: Applications can determine whether the contents of a directory hierarchy have changed since a given event ID or timestamp. This makes it useful for backup applications that need to identify changed files since a prior point in time.
- Event coalescing: Multiple changes occurring within a short time window are combined into a single notification, improving efficiency.
Applications and Usage
FSEvents is used in a variety of contexts:
- Backup software: Uses FSEvents to determine which files have changed since a particular timestamp or event ID.
- Spotlight (macOS's search indexer): Tracks file system modifications to maintain its index.
- Development tools: Detect when files are modified by other applications within project bundles.
- Security and forensic tools: Track file system activity on a specific volume for analysis purposes.
Relationship to Other Technologies
FSEvents is often compared to kernel queues (kqueue), which provide an alternative mechanism for file system event notification on macOS. The Apple documentation describes kqueue as an alternative to FSEvents and discusses when it may be appropriate to use one over the other. FSEvents is generally considered more efficient for monitoring large directory hierarchies, while kqueue provides finer-grained file-level notifications.
Cross-Platform Bindings
The FSEvents API is accessible from various programming environments beyond native C/C++ development. Notably, the fsevents Node.js module provides native access to the macOS FSEvents API for JavaScript applications. This low-level library is used as a backend for cross-platform file-watching modules such as Chokidar. The API is widely regarded as a fast and lightweight alternative to kqueue for file monitoring on macOS.
References
- Apple Developer Documentation: File System Events API
- Wikipedia: FSEvents
- Apple's "File System Events Programming Guide"
