File Directories

Commonly used directories of an iOS app

Directory	Description
<Application_Home>/AppName.app	This is the bundle directory containing the app itself.Do not write anything to this directory. To prevent tampering, the bundle directory is signed at installation time. Writing to this directory changes the signature and prevents your app from launching again. In iOS 2.1 and later, the contents of this directory are not backed up by iTunes. However, iTunes does perform an initial sync of any apps purchased from the App Store.
<Application_Home>/Documents/	Use this directory to store critical user documents and app data files.Critical data is any data that cannot be recreated by your app, such as user-generated content. The contents of this directory can be made available to the user through file sharing. The contents of this directory are backed up by iTunes.
<Application_Home>/Documents/Inbox	Use this directory to access files that your app was asked to open by outside entities. Specifically, the Mail program places email attachments associated with your app in this directory; document interaction controllers may also place files in it. Your app can read and delete files in this directory butcannot create new files or write to existing files. If the user tries to edit a file in this directory, your app must silently move it out of the directory before making any changes. The contents of this directory are backed up by iTunes.
<Application_Home>/Library/	This directory is the top-level directory for files that are not user data files. You typically put files in one of several standard subdirectories but you can also create custom subdirectories for files you want backed up but not exposed to the user. You should not use this directory for user data files. The contents of this directory (with the exception of the Caches subdirectory) are backed up by iTunes. For additional information about the Library directory, see “The Library Directory Stores App-Specific Files.”
<Application_Home>/tmp/	Use this directory to write temporary files that do not need to persist between launches of your app. Your app should remove files from this directory when it determines they are no longer needed. (The system may also purge lingering files from this directory when your app is not running.) In iOS 2.1 and later, the contents of this directory are not backed up by iTunes.

With this in mind, you should store app data according to the following guidelines:

• Put user data in the <Application_Home>/Documents/. User data is any data that cannot be recreated by your app, such as user documents and other user-generated content.

• Handle support files—files your application downloads or generates and can recreate as needed—in one of two ways:

  • In iOS 5.0 and earlier, put support files in the <Application_Home>/Library/Caches directory to prevent them from being backed up

  • In iOS 5.0.1 and later, put support files in the <Application_Home>/Library/Application Support directory and apply the com.apple.MobileBackup extended attribute to them. This attribute prevents the files from being backed up to iTunes or iCloud. If you have a large number of support files, you may store them in a custom subdirectory and apply the extended attribute to just the directory.

• Put data cache files in the <Application_Home>/Library/Caches directory. Examples of files you should put in this directory include (but are not limited to) database cache files and downloadable content, such as that used by magazine, newspaper, and map apps. Your app should be able to gracefully handle situations where cached data is deleted by the system to free up disk space.

• Put temporary data in the <Application_Home>/tmp directory. Temporary data comprises any data that you do not need to persist for an extended period of time. Remember to delete those files when you are done with them so that they do not continue to consume space on the user’s device.

 Key subdirectories of the  Library directory

Directory	Usage
Application Support	Use this directory to store all app data files except those associated with the user’s documents. For example, you might use this directory to store app-created data files, configuration files, templates, or other fixed or modifiable resources that are managed by the app. An app might use this directory to store a modifiable copy of resources contained initially in the app’s bundle. A game might use this directory to store new levels purchased by the user and downloaded from a server. All content in this directory should be placed in a custom subdirectory whose name is that of your app’s bundle identifier or your company. In iOS, the contents of this directory are backed up by iTunes.
Caches	Use this directory to write any app-specific support files that your app can re-create easily. Your app is generally responsible for managing the contents of this directory and for adding and deleting files as needed. In iOS 2.2 and later, the contents of this directory are not backed up by iTunes. In addition, iTunes removes files in this directory during a full restoration of the device. On iOS 5.0 and later, the system may delete the Caches directory on rare occasions when the system is very low on disk space. This will never occur while an app is running. However, you should be aware that iTunes restore is not necessarily the only condition under which the Caches directory can be erased.
Frameworks	In OS X, frameworks that must be shared by multiple apps can be installed in either the local or user domain. The Frameworks directory in the system domain stores the frameworks you use to create your OS X apps. In iOS, apps cannot install custom frameworks.
Preferences	This directory contains app-specific preference files. You should not create files in this directory yourself. Instead, use the NSUserDefaults class or CFPreferences API to get and set preference values for your app. In iOS, the contents of this directory are backed up by iTunes.

The iCloud File Storage Container

iCloud provides a structured system for storing files for apps that make use of iCloud:

• Apps have a primary iCloud container directory for storing their native files.  They can also access secondary iCloud container directories listed in their app entitlements.

• Inside each container directory, files are segregated into "documents" and data.  Every file or file package located in theDocuments subdirectory (or one of its subdirectories) is presented to the user (via the iCloud UI in OS X and iOS) as a separate document that can be deleted individually.   Anything not in Documents or one of its subdirectories is treated as data and shown as a single entry in the iCloud UI.

Documents that the user creates and sees in an app's user interface—for example the document browsers in Pages, Numbers, and Keynote should be stored in the Documents directory. Another example of files that might go in the Documents directory are saved games, again because they are something that an app could potentially provide some sort of method for selecting.

Anything that the app does not want the user to see or modify directly should be placed outside of the Documents directory.  Apps can create any subdirectories inside the container directory, so they can arrange private files as desired.

Apps create files and directories in iCloud container directories in exactly the same way as they create local files and directories.  And all the file’s attributes are saved, if they add extended attributes to a file, those attributes are copied to iCloud and to the user's other devices too.

iCloud containers also allow the storage of key-value pairs that can be easily accessed without having to create a document format.

Working with Documents in iCloud

At the heart of the iCloud locking mechanism are file coordinators and file presenters. Whenever you need to read and write a file, you do so using a file coordinator, which is an instance of the NSFileCoordinator class. The job of a file coordinator is to coordinate the reads and writes performed by your app and the sync daemon on the same document. For example, your app and the daemon may both read the document at the same time but only one may write to the file at any single time. Also, if one process is reading the document, the other process is prevented from writing to the document until the reader is finished.

In addition to coordinating operations, file coordinators also work with file presenters to notify apps when changes are about to occur. A file presenter is any object that conforms to the NSFilePresenter protocol and takes responsibility for managing a specific file (or directory of files) in an app. The job of a file presenter is to protect the integrity of its own data structures. It does this by listening for messages from other file coordinators and using those messages to update its internal data structures. In most cases, a file presenter may not have to do anything. However, if a file coordinator declares that it is about to move a file to a new URL, the file presenter would need to replace its old URL with the new one provided to it by the file coordinator. TheNSDocument class is an example of a file presenter that tracks changes to its underlying file or file package.

Here is a checklist of the things your app must do to work with documents in iCloud:

• Manage each document in iCloud using a file presenter. The recommended way to do this is to use the NSDocument class, but you may define custom file presenters if you prefer. You can use a single file presenter to manage a file package or a directory of files.

• After creating a file presenter, register it by calling the addFilePresenter: class method of NSFileCoordinator. Registration is essential. The system can notify only registered presenter objects.

• Before deleting a file presenter, unregister it by calling the removeFilePresenter: method of NSFileCoordinator.

All file-related operations must be performed through a file coordinator object. To read or write a document, or move or delete it, follow these steps:

1. Create an instance of the NSFileCoordinator class and initialize it with the file presenter object that is about to perform the file operation.

2. Use the methods of the NSFileCoordinator object to read or write the file:

   • To read all or part of a single file, use the coordinateReadingItemAtURL:options:error:byAccessor: method

   • To write to a file or delete it, call the coordinateWritingItemAtURL:options:error:byAccessor: method.

   • To perform a sequence of read or write operations, use thecoordinateReadingItemAtURL:options:writingItemAtURL:options:error:byAccessor: method.

   • To write to multiple files, or to move a file to a new location, use thecoordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor: method.

   You perform the actual file-related operations in the block that you pass to these methods. You should perform operations as quickly as possible to avoid blocking other apps that might be trying to access the file at the same time.

3. When you are done with the operations, release the file coordinator object.