Fun with FSCatalogSearch

FSCatalogSearch searches a volume for files matching search criteria. You can have it return any number of files in a single call, and you can call it repeatedly using the same iterator to continue searching the volume until all matches are found.

Now here’s the fun part. It’s possible that files can be added or deleted during the operation, and in that case, it will set a boolean flag and return a ‘catalog changed’ error. When that happens, the results it returns are completely bogus, including the number of items returned. The only thing you can do in that case is start from scratch with a new iterator or bail out.

I spent most of today fixing code that depends on it and making it bulletproof in all error conditions.