About | ACP | Buy | Industry Watch | Learning Curve | News | Products | Search | Substack
Home » Industry Watch

Your Call is Being Connected

A first look at a new app.

Get It

Try It

FELIXSTOWE (Rixstep) — This is a first look at a new app, which in turn is a first look at a rather sophisticated technology: Apple's filesystem events module.

The app in question is called Changes, as it's based on change notifications of a sort. But this piece is more about the target technology than the app itself. For the app gives a fascinating look at the technology.

How many files need be modified to launch an application? How many files - and which files - are modified when saving a document? Where are these other files located? What on-disk procedure is used to save a document?

These questions and more can be answered by tapping into Apple's filesystem events module.

Change Notifications

Change notifications aren't new. They're used in a wide variety of scenarios. Take a client-server scenario where a server is open for incoming traffic and must respond by distributing this information to connected clients.

The server can hardly sit there and poll for activity - it necessarily cannot waste time (CPU). Deep down at kernel level, the modifications to target directories must activate sleeping threads that are waiting for news.

This type of object-based synchronisation was prevalent in Digital Equipment's VMS, as well as its bastard offspring, Microsoft's 'NT'. Doing the same on a Unix system such as Apple's requires looking at things in a different way.

The classic 'change notification' gets a major boost from Apple. Not only can the system signal changes to directories, it can signal changes to files, and it can get very specific about what exactly has transpired.


Although the underbody of Apple's OS has an alternate method, the more sophisticated approach seems to be Apple's own. FSEvents is the module that powers Spotlight. It uses a clever system of bitwise flags to tell clients precisely what's going on.

One begins by creating an event stream. One provides a callback function, an array of on-disk paths to monitor, and a point in time when the system should start reporting. (This can also be far in the past - 'since the beginning of (computer) time'.)

One sets the latency for the stream, a value in fractions of a second after which the system will release coalesced events. And of course one tells the system what precisely it should report on. And where.

Then one sits back and waits. And never too long. If there's one thing that impresses, it's the activity of the target system, something one may never have otherwise been aware of.

The Callback

Callbacks get essentially three chunks of interesting data: event IDs, bitwise flags associated with each event, and the on-disk path for the event. One can also know the number of events in a group of events.

Event Flags

Here's where things get nice. The flags are more than just a 'beep' saying a directory's been modified.

All flag macros begin with 'kFSEventStreamEventFlag'.

Value    Flag Name
-----    ---------
00000001 kFSEventStreamEventFlagMustScanSubDirs    /* Advising you do something */
00000002 kFSEventStreamEventFlagUserDropped        /* Who dropped it? */
00000004 kFSEventStreamEventFlagKernelDropped      /* Who dropped it?s */
00000008 kFSEventStreamEventFlagEventIdsWrapped    /* There's been an ID rollover */
00000010 kFSEventStreamEventFlagHistoryDone        /* Related to a specified interval */
00000020 kFSEventStreamEventFlagRootChanged        /* Something atop the hierarchy */
00000040 kFSEventStreamEventFlagMount              /* Something's been mounted */
00000080 kFSEventStreamEventFlagUnmount            /* Something's been unmounted */
00000100 kFSEventStreamEventFlagItemCreated        /* Something's been created */
00000200 kFSEventStreamEventFlagItemRemoved        /* Something's been removed */
00000400 kFSEventStreamEventFlagItemInodeMetaMod   /* Undocumented */
00000800 kFSEventStreamEventFlagItemRenamed        /* Something's been renamed */
00001000 kFSEventStreamEventFlagItemModified       /* Something's been modified */
00002000 kFSEventStreamEventFlagItemFinderInfoMod  /* Even Finder's involved */
00004000 kFSEventStreamEventFlagItemChangeOwner    /* Change in ownership */
00008000 kFSEventStreamEventFlagItemXattrMod       /* XA changed? (Undocumented) */
00010000 kFSEventStreamEventFlagItemIsFile         /* It's a file */
00020000 kFSEventStreamEventFlagItemIsDir          /* It's a directory */
00040000 kFSEventStreamEventFlagItemIsSymlink      /* It's a symlink */
00080000 kFSEventStreamEventFlagOwnEvent           /* Undocumented */
00100000 kFSEventStreamEventFlagItemIsHardlink     /* It's a hardlink */
00200000 kFSEventStreamEventFlagItemIsLastHardlink /* Final link before file is gone? */
00400000 kFSEventStreamEventFlagItemCloned         /* Undocumented */

The events, which can come in groups, can further clue you to what's going on.

For example: MustScanSubDirs is normally associated with either UserDropped or KernelDropped, in case you felt you needed to know who to blame. A grouping with ItemRemoved, ItemRenamed, and ChangeOwner might be a sign of an operation carried out by the system document controller.


Here's the app used to dig into FSEvents. It's called Changes.

Running Changes can be both a bewildering and a harrowing experience. On the one hand, one can be perplexed with the sheer number of transactions for what are supposedly simple and innocuous operations.

On the other hand, the sheer sophistication of this communication system can't help but impress.

About Rixstep

Stockholm/London-based Rixstep are a constellation of programmers and support staff from Radsoft Laboratories who tired of Windows vulnerabilities, Linux driver issues, and cursing x86 hardware all day long. Rixstep have many years of experience behind their efforts, with teaching and consulting credentials from the likes of British Aerospace, General Electric, Lockheed Martin, Lloyds TSB, SAAB Defence Systems, British Broadcasting Corporation, Barclays Bank, IBM, Microsoft, and Sony/Ericsson.

Rixstep and Radsoft products are or have been in use by Sweden's Royal Mail, Sony/Ericsson, the US Department of Defense, the offices of the US Supreme Court, the Government of Western Australia, the German Federal Police, Verizon Wireless, Los Alamos National Laboratory, Microsoft Corporation, the New York Times, Apple Inc, Oxford University, and hundreds of research institutes around the globe. See here.

All Content and Software Copyright © Rixstep. All Rights Reserved.

John Cattelin
Media Contact
ACP/Xfile licences
About | ACP | Buy | Industry Watch | Learning Curve | News | Products | Search | Substack
Copyright © Rixstep. All rights reserved.