| Components | All | New | MacOS | Windows | Linux | iOS | ||||
| Examples | Mac & Win | Server | Client | Guides | Statistic | FMM | Blog | Deprecated | Old | |
FSEvents.NextEvent
Queries next event in queue.
| Component | Version | macOS | Windows | Linux | Server | iOS SDK |
| FSEvents | 5.4 | ✅ Yes | ❌ No | ❌ No | ✅ Yes, on macOS | ❌ No |
MBS( "FSEvents.NextEvent"; FSEventsRef ) More
Parameters
| Parameter | Description | Example |
|---|---|---|
| FSEventsRef | The reference number for this FSEvents object. | $fstream |
Result
Returns event data or error.
Description
Queries next event in queue.Returns a list of values. First entry is the path, second entry the ID number for this event. Third is the flags value as number and forth as text values. This allows you to check for some values like "ItemCreated".
Flags that are returned for file system events.
It is important to note that event flags are simply hints about the sort of operations that occurred at that path.
Furthermore, the FSEvent stream should NOT be treated as a form of historical log that could somehow be replayed to arrive at the current state of the file system.
The FSEvent stream simply indicates what paths changed; and clients need to reconcile what is really in the file system with their internal data model - and recognize that what is actually in the file system can change immediately after you check it.
MustScanSubDirs = 1
Your application must rescan not just the directory given in the event, but all its children, recursively. This can happen if there was a problem whereby events were coalesced hierarchically. For example, an event in /Users/jsmith/Music and an event in /Users/jsmith/Pictures might be coalesced into an event with this flag set and path=/Users/jsmith. If this flag is set you may be able to get an idea of whether the bottleneck happened in the kernel (less likely) or in your client (more likely) by checking for the presence of the informational flags UserDropped or KernelDropped.
UserDropped = 2
KernelDropped = 4
The UserDropped or KernelDropped flags may be set in addition to the MustScanSubDirs flag to indicate that a problem occurred in buffering the events (the particular flag set indicates where the problem occurred) and that the client must do a full scan of any directories (and their subdirectories, recursively) being monitored by this stream. If you asked to monitor multiple paths with this stream then you will be notified about all of them. Your code need only check for the MustScanSubDirs flag; these flags (if present) only provide information to help you diagnose the problem.
EventIdsWrapped = 8
If EventIdsWrapped is set, it means the 64-bit event ID counter wrapped around. As a result, previously-issued event ID's are no longer valid arguments for the sinceWhen parameter of the FSEvent.Create function.
HistoryDone = 16
Denotes a sentinel event sent to mark the end of the "historical" events sent as a result of specifying a sinceWhen value in the FSEvents.Create...() call that created this event stream. (It will not be sent if kFSEventStreamEventIdSinceNow was passed for sinceWhen.) After invoking the client's callback with all the "historical" events that occurred before now, the client's callback will be invoked with an event where the HistoryDone flag is set. The client should ignore the path supplied in this callback.
RootChanged = 32
Denotes a special event sent when there is a change to one of the directories along the path to one of the directories you asked to watch. When this flag is set, the event ID is zero and the path corresponds to one of the paths you asked to watch (specifically, the one that changed). The path may no longer exist because it or one of its parents was deleted or renamed. Events with this flag set will only be sent if you passed the flag kFSEvents.CreateFlagWatchRoot to FSEvents.Create when you created the stream.
Mount = 64
Denotes a special event sent when a volume is mounted underneath one of the paths being monitored. The path in the event is the path to the newly-mounted volume. You will receive one of these notifications for every volume mount event inside the kernel (independent of DiskArbitration). Beware that a newly-mounted volume could contain an arbitrarily large directory hierarchy. Avoid pitfalls like triggering a recursive scan of a non-local filesystem, which you can detect by checking for the absence of the MNT_LOCAL flag in the f_flags returned by statfs(). Also be aware of the MNT_DONTBROWSE flag that is set for volumes which should not be displayed by user interface elements.
Unmount = 128
Denotes a special event sent when a volume is unmounted underneath one of the paths being monitored. The path in the event is the path to the directory from which the volume was unmounted. You will receive one of these notifications for every volume unmount event inside the kernel. This is not a substitute for the notifications provided by the DiskArbitration framework; you only get notified after the unmount has occurred. Beware that unmounting a volume could uncover an arbitrarily large directory hierarchy, although macOS never does that.
ItemCreated = 256
A file system object was created at the specific path supplied in this event.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemRemoved = 512
A file system object was removed at the specific path supplied in this event.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemInodeMetaMod = 1024
A file system object at the specific path supplied in this event had its metadata modified.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemRenamed = 2048
A file system object was renamed at the specific path supplied in this event.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemModified = 4096
A file system object at the specific path supplied in this event had its data modified.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemFinderInfoMod = 8192
A file system object at the specific path supplied in this event had its FinderInfo data modified.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemChangeOwner = 16384
A file system object at the specific path supplied in this event had its ownership changed.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemXattrMod = 32768
A file system object at the specific path supplied in this event had its extended attributes modified.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemIsFile = 65536
The file system object at the specific path supplied in this event is a regular file.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemIsDir = 131072
The file system object at the specific path supplied in this event is a directory.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemIsSymlink = 262144
The file system object at the specific path supplied in this event is a symbolic link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
OwnEvent = 524288
Indicates the event was triggered by the current process.
(This flag is only ever set if you specified the MarkSelf flag when creating the stream.)
ItemIsHardlink = 1048576
Indicates the object at the specified path supplied in this event is a hard link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemIsLastHardlink = 2097152
Indicates the object at the specific path supplied in this event was the last hard link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
ItemCloned = 4194304
The file system object at the specific path supplied in this event is a clone or was cloned.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
See also
Example Databases
This function checks for a license.
Created 18th November 2015, last changed 10th August 2020
