Technical Note TN2406

Changes To App Containers In iOS 8

Beginning in iOS 8, the Documents and Library directories are no longer siblings of your application's bundle. This document describes how to ensure your app is not affected by these changes.

iOS 8 changes the locations of the standard directories used for storing user and app data (e.g. Documents, Library). While the locations of these directories have always been an implementation detail, some applications improperly assume that the Documents and Library directories reside in the same directory as the application's bundle. iOS 8 splits the data of an application from the application bundle. Code which attempts to derive the path to the Documents or Library directories will return an invalid path on iOS 8. Attempting to access this path will fail, and may terminate your app.

If your application or framework accesses the Documents directory, the Library directory, or any of the other standard directories, follow the recommendations listed under Locating The Standard Directories when building a URL or path to your data.

Locating The Standard Directories
Further Reading
Document Revision History

Locating The Standard Directories

Applications should always call the system to get the locations of the standard directories.

Listing 1  Using NSFileManager to retrieve the location of the Documents directory.

// Returns the URL to the application's Documents directory.
- (NSURL *)applicationDocumentsDirectory
    return [[[NSFileManager defaultManager] URLsForDirectory:NSDocumentDirectory inDomains:NSUserDomainMask] lastObject];

The NSFileManager class provides the -URLsForDirectory:inDomains: and -URLForDirectory:inDomain:appropriateForURL:create:error: methods to retrieve the url of the given standard directory. Refer to the values listed under NSSearchPathDirectory in the Foundation Constants Reference for the complete list of standard directories that can be located using these APIs. Note that not all of the listed values are relevant on iOS.

While URLs are the preferred format for referencing locations on disk, your application may require a path when interfacing with C-based APIs. If you have a file system URL (that is, -isFileURL returns YES), you can call -path to extract the path from the URL. The resulting path is guaranteed to be compatible with path-based APIs.

Further Reading

Accessing Files and Directories in the "File System Programming Guide".

Document Revision History


New document that describes how to locate the standard directories in iOS 8.