FSEvents Flags Explained: Every Bit, Decoded
Every on-disk FSEvents flag bit with its value, the names FSEventsParser and mac_apt use, and how to read Created, Renamed, ItemCloned or EndOfTransaction.
TL;DR. The flags field is a 32-bit little-endian bit set. Read that way, Created is 0x00000001, Removed 0x00000002, Renamed 0x00000008, Modified 0x00000010, and the item type sits in the high bits (File 0x00800000, Folder 0x01000000). FSEventsParser reads the same four bytes big-endian, so its constants are byte-swapped (Created = 0x01000000), with the same names. None of these equal Apple's kFSEventStreamEventFlag* API values.
The table
Values are the u32 read little-endian (mac_apt's convention). The FSEventsParser column shows the same bit in its big-endian convention.
| Bit (LE) | FSEventsParser (BE) | Name (FSEventsParser / mac_apt) | Meaning |
|---|---|---|---|
0x00000001 | 0x01000000 | Created | Item created |
0x00000002 | 0x02000000 | Removed | Item removed |
0x00000004 | 0x04000000 | InodeMetaMod | Inode metadata changed (e.g. mode, timestamps) |
0x00000008 | 0x08000000 | Renamed / RenamedOrMoved | Renamed or moved |
0x00000010 | 0x10000000 | Modified | Content modified |
0x00000020 | 0x20000000 | Exchange | Swapped with another item (atomic save) |
0x00000040 | 0x40000000 | FinderInfoMod | Finder info changed |
0x00000080 | 0x80000000 | FolderCreated | Folder created |
0x00000100 | 0x00010000 | PermissionChange | Permissions or ownership changed |
0x00000200 | 0x00020000 | ExtendedAttrModified / XAttrModified | Extended attribute set or changed |
0x00000400 | 0x00040000 | ExtendedAttrRemoved / XAttrRemoved | Extended attribute removed |
0x00001000 | 0x00100000 | DocumentRevisioning / DocumentRevision | Document versions store involved |
0x00004000 | 0x00400000 | ItemCloned | APFS clone (copy-on-write copy), High Sierra and later |
0x00080000 | 0x00000800 | LastHardLinkRemoved | Last hard link to an inode removed |
0x00100000 | 0x00001000 | HardLink | Item is a hard link |
0x00400000 | 0x00004000 | SymbolicLink | Item is a symbolic link |
0x00800000 | 0x00008000 | FileEvent / File | Item is a file |
0x01000000 | 0x00000001 | FolderEvent / Folder | Item is a folder |
0x02000000 | 0x00000002 | Mount | A volume was mounted at this path |
0x04000000 | 0x00000004 | Unmount | A volume was unmounted from this path |
0x20000000 | 0x00000020 | EndOfTransaction | Marks the end of a group of related changes |
Other bits have no documented meaning. The FSEvents Parser shows them in hex rather than guessing, and FSEventsParser labels them NOT_USED; seeing them in carved data is a hint that the record is damaged.
Reading combinations
A record carries every change fseventsd merged for that path (see coalescing):
Created;Modified;FileEvent: a file was written. The usual shape of a new document or download.Created;Modified;Removed;FileEvent: a short-lived file (temporary files, installer scratch data, a file created then deleted within the same flush). The order inside the record is not recorded.Renamed;FileEventtwice, same node ID: a rename or move; the lower event ID is usually the old path. On 1SLD there is no node ID and pairing relies on consecutive IDs.ExtendedAttrModifiedon a new download: typically the quarantine and where-from attributes being set.ExtendedAttrRemovedon extracted or downloaded items: an attribute was removed. Strippingcom.apple.quarantineis one reason, see quarantine attribute; many apps remove attributes routinely.InodeMetaModalone: achmod,touchor ownership change; making a downloaded helper executable often looks like this.Mount;FolderEventonVolumes/NAME: a volume attached at that mount point. The volume's own.fseventsdthen logs what was written to it.ItemCloned: an APFS clone, e.g. a Finder duplicate orcp -c. The clone and its source share data blocks.
API constants are different
Apple's documented FSEventStreamEventFlags (kFSEventStreamEventFlagItemCreated = 0x100, …ItemIsFile = 0x10000, and so on) describe what a running app receives from the FSEvents API. They do not match the bits written to .fseventsd, as noted by Nicole Ibrahim's research and mac_apt's source. A parser that applies the API table to log files produces wrong names.
How the parser shows flags
The FSEvents Parser shows change flags as labelled chips, the item type in its own column, the raw value (e.g. 0x00800011) and the FSEventsParser-style names in the record detail and in CSV exports. The change filter groups bits into Created, Removed, Renamed, Modified/cloned, metadata/attributes and mount/unmount.
FAQ
Are FSEvents log flags the same as the FSEventStream API flags?
No. The bits stored in .fseventsd logs differ from Apple's public kFSEventStreamEventFlag constants. Use a table built for the on-disk format.
What does ExtendedAttrRemoved mean?
An extended attribute was removed from the item. FSEvents does not say which one; removing com.apple.quarantine is one possibility among many.