The iOS file system is geared toward apps running on their own. To keep the system simple, users of iOS devices do not have direct access to the file system and apps are expected to follow this convention.
Every App Is an Island[]
An iOS app’s interactions with the file system are limited mostly to the directories inside the app’s sandbox. During installation of a new app, the installer creates a number of containers for the app. Each container has a specific role. The bundle container holds the app’s bundle, whereas the data container holds data for both the application and the user. The data container is further divided into a number of directories that the app can use to sort and organize its data. The app may also request access to additional containers—for example, the iCloud container—at runtime.
These containers constitute the app’s primary view of the file system. Following figure shows a representation of the sandbox for an app.
Because it is in a sandbox, an app is generally prohibited from accessing or creating files outside its containers. One exception to this rule occurs when an app uses public system interfaces to access things such as the user’s contacts or music. In those cases, the system frameworks handle any file-related operations needed to read from or modify the appropriate data stores.
iOS Standard Directories: Where Files Reside[]
For security purposes, an iOS app has limited a number of places where it can write its data. When an app is installed on a device (either from iTunes or the App Store), the system creates a number of containers for the app. These containers represent the universe for that app and contain everything the app can access directly. This is the lists some of the important subdirectories inside these containers and describes their intended usage. This table also describes any additional access restrictions for each subdirectory and points out whether the directory’s contents are backed up by iTunes.
- AppName.app - This is the app’s bundle. This is livecode specialFolderPath("home"). This directory contains the app and all of its resources. You cannot write 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. You can, however, gain read-only access to any resources stored in the apps bundle. 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.
- Documents - This is livecode specialFolderPath("documents"). Use this directory to store user-generated content. The contents of this directory can be made available to the user through file sharing; therefore, his directory should only contain files that you may wish to expose to the user. The contents of this directory are backed up by iTunes.
- Documents/Inbox - This is livecode specialFolderPath("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 but cannot 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.
- Library/ - This is livecode specialFolderPath("library"). This is the top-level directory for any files that are not user data files. You typically put files in one of several standard subdirectories. iOS apps commonly use the Application Support and Caches ubdirectories; however, you can create custom subdirectories. Use the Library subdirectories for any files you don’t want exposed to the user. Your app should not use these directories for user data files. The contents of the Library directory (with the exception of the Caches subdirectory) are backed up by iTunes.
- tmp/ - This is livecode specialFolderPath("temporary"). 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 they are no longer needed; however, the system may purge this directory when your app is not running. The contents of this directory are not backed up by iTunes.
An iOS app may create additional directories in the Documents, Library, and tmp directories. You might do this to better organize the files in those locations.
For information about how to get references to the preceding directories from your iOS app, see Locating Items in the Standard Directories. For tips on where to put files, see Where You Should Put Your App’s Files.
Where You Should Put Your App’s Files[]
To prevent the syncing and backup processes on iOS devices from taking a long time, be selective about where you place files. Apps that store large files can slow down the process of backing up to iTunes or iCloud. These apps can also consume a large amount of a user's available storage, which may encourage the user to delete the app or disable backup of that app's data to iCloud. With this in mind, you should store app data according to the following guidelines:
Put user data in Documents/. User data generally includes any files you might want to expose to the user—anything you might want the user to create, import, delete or edit. For a drawing app, user data includes any graphic files the user might create. For a text editor, it includes the text files. Video and audio apps may even include files that the user has downloaded to watch or listen to later.
Put app-created support files in the Library/Application support/ directory. In general, this directory includes files that the app uses to run but that should remain hidden from the user. This directory can also include data files, configuration files, templates and modified versions of resources loaded from the app bundle.
Remember that files in Documents/ and Application Support/ are backed up by default. Any file that can be re-created or downloaded must be excluded from the backup. This is particularly important for large media files. If your application downloads video or audio files, make sure they are not included in the backup.
Put temporary data in the 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. The system will periodically purge these files when your app is not running; therefore, you cannot rely on these files persisting after your app terminates.
Put data cache files in the Library/Caches/ directory. Cache data can be used for any data that needs to persist longer than temporary data, but not as long as a support file. Generally speaking, the application does not require cache data to operate properly, but it can use cache data to improve performance. Examples of cache data include (but are not limited to) database cache files and transient, downloadable content. Note that the system may delete the Caches/ directory to free up disk space, so your app must be able to re-create or download these files as needed.