An object that coordinates the reading and writing of files and directories among file presenters.


@interface NSFileCoordinator : NSObject


The NSFileCoordinator class coordinates the reading and writing of files and directories among multiple processes and objects in the same process. You use instances of this class as is to read from, write to, modify the attributes of, change the location of, or delete a file or directory, but before your code to perform those actions executes, the file coordinator lets registered file presenter objects perform any tasks that they might require to ensure their own integrity. For example, if you want to change the location of a file, other objects interested in that file need to know where you intend to move it so that they can update their references.

Objects that adopt the NSFilePresenter protocol must register themselves with the NSFileCoordinator class to be notified of any pending changes. They do this by calling the addFilePresenter: class method. A file presenter must balance calls to addFilePresenter: with a call to removeFilePresenter: before being released, even in a garbage-collected application. The file presenter class maintains a list of active file presenter objects in the current application and uses that list, plus the file coordinator classes in other processes, to deliver notifications to all of the objects interested in a particular item.

Instances of NSFileCoordinator are meant to be used on a per-file-operation basis, where a file operation is something like opening and reading the contents of a file or moving a batch of files and directories to a new location. There is no benefit to keeping a file coordinator object past the length of the planned operation. In fact, because file coordinators retain file presenter objects, keeping one around could prevent the file presenter objects from being released in a timely manner.

For information about implementing a file presenter object to receive file-related notifications, see NSFilePresenter.

File Presenters and iOS

If your app or extension enters the background with an active file presenter, it may be terminated by the system in order to prevent deadlock on that file. To prevent this situation, call removeFilePresenter: to remove the file presenter in the applicationDidEnterBackground: method or in response to a UIApplicationDidEnterBackgroundNotification notification. Call addFilePresenter: to add the file presenter again in the applicationWillEnterForeground: method or in response to a UIApplicationWillEnterForegroundNotification notification.

File Coordinators and iOS

A coordinated read or write will automatically begin a background task when granted, similar to one created with the beginBackgroundTaskWithExpirationHandler: method. This helps ensure that your app or extension has sufficient time to finish the read or write operation if it’s suspended, without creating a deadlock on access to that file by other processes. If a process is suspended while waiting for a coordinated read or write to be granted, the request is canceled, and an NSError object with the code NSUserCancelledError is produced. If the background task expires, the process is terminated.

Threading Considerations

Each file coordinator object you create should be used on a single thread only. If you need to coordinate file operations across multiple objects in different threads, each object should create its own file coordinator.


Initializing a File Coordinator

- initWithFilePresenter:

Initializes and returns a file coordinator object using the specified file presenter.

Managing File Presenters

+ addFilePresenter:

Registers the specified file presenter object so that it can receive notifications.

+ removeFilePresenter:

Unregisters the specified file presenter object.


Returns an array containing the currently registered file presenter objects.


A string that uniquely identifies the file access that was performed by this file coordinator.

Coordinating File Operations Asynchronously

- coordinateAccessWithIntents:queue:byAccessor:

Performs a number of coordinated-read or -write operations asynchronously.

Coordinating File Operations Synchronously

- coordinateReadingItemAtURL:options:error:byAccessor:

Initiates a read operation on a single file or directory using the specified options.

- coordinateWritingItemAtURL:options:error:byAccessor:

Initiates a write operation on a single file or directory using the specified options.

- coordinateReadingItemAtURL:options:writingItemAtURL:options:error:byAccessor:

Initiates a read operation that contains a follow-up write operation.

- coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor:

Initiates a write operation that involves a secondary write operation.

- prepareForReadingItemsAtURLs:options:writingItemsAtURLs:options:error:byAccessor:

Prepare to read or write from multiple files in a single batch operation.

- itemAtURL:willMoveToURL:

Announces that your app is moving a file to a new URL.

- itemAtURL:didMoveToURL:

Notifies relevant file presenters that the location of a file or directory changed.

- cancel

Cancels any active file coordination calls.



Options to use when reading the contents or attributes of a file or directory.


Options to use when changing the contents or attributes of a file or directory.

Ubiquity Change Notifications

- itemAtURL:didChangeUbiquityAttributes:

Tells observing file providers that the item's ubiquity attributes have changed.


Inherits From

See Also

Shared Files


The interface a file coordinator uses to inform an object presenting a file about changes to that file made elsewhere in the system.


The details of a coordinated-read or coordinated-write operation.