# Titanium.Filesystem > The top level filesystem module, used to access files and directories on the device. - Source: https://titaniumsdk.com/docs/sdk/12.6.4/Titanium.Filesystem - Titanium SDK version: 12.6.4 - Kind: module - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.1 - Extends: Titanium.Module - Inheritance: Titanium.Module > Titanium.Proxy For examples of using the Filesystem APIs, refer to the [Filesystem Access and Storage guide](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/Working_with_Local_Data_Sources/Filesystem_Access_and_Storage.html) as well as the other Filesystem submodule API documentation. ## Example: Getting a directory for an application group (iOS) This example writes a string to a text file in a shared directory ``` js var suiteDir = Ti.Filesystem.directoryForSuite('group.appc.Sharing'); if (!suiteDir) { logInApp('Suite Directory not found, check Entitlements.'); return; } var f = Ti.Filesystem.getFile(suiteDir,'emptyfile.txt'); f.write('The file is no longer empty!'); ``` ## Properties ### applicationCacheDirectory - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 1.8.3 - Permission: read-only Path to the application's internal cache directory. Files stored in the cache directory remain after the application is closed but at the discretion of the operating system. On the Android platform, the cache is limited to 25 MB and the files remain for the lifetime of the application, that is, until the application is uninstalled. On the iOS platform, the cache does not have a size limit but the data remains until iOS cleans the directory to recover the disk space. ### applicationDataDirectory - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Path to the application's data directory. This is a writable directory that can be used to store applications-specific files. On iOS, this directory is specifically designated for user documents, and a separate directory, [applicationSupportDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#applicationSupportDirectory) is used for other application data. On iOS, files in this directory are backed up unless the [remoteBackup](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#remoteBackup) flag is set to false. ### applicationDirectory - Type: String - Platforms: iPhone, iPad, macOS - Permission: read-only Path to the iOS application directory. ### applicationSupportDirectory - Type: String - Platforms: iPhone, iPad, macOS - Permission: read-only Path to the application support directory. This is a writable directory used on iOS for application files that are *not* user documents--including settings files, caches, and so on. On iOS, files in this directory are backed up unless the [remoteBackup](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#remoteBackup) flag is set to false. ### externalCacheDirectory - Type: String - Platforms: Android - Since: Titanium SDK 9.3.0 - Permission: read-only Path to the app's sandboxed cache folder on removable storage, such as SD card. This directory is intended to be used to store large temporary files since external storage typically has a larger capacity than internal storage. This is a good place to store videos and large photos. The application should check [isExternalStoragePresent](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#isExternalStoragePresent) before accessing this location. This is because external storage is sometimes removable on same devices, such as an SD card. This directory does not require the `Manifest.permission.READ_EXTERNAL_STORAGE` and `Manifest.permission.WRITE_EXTERNAL_STORAGE` permissions. ### externalStorageDirectory - Type: String - Platforms: Android - Permission: read-only Path to the app's sandboxed folder on removable storage, such as SD card. This directory is intended to be used to store large files since external storage typically has a larger capacity than internal storage. This is a good place to store videos and large photos. The application should check [isExternalStoragePresent](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#isExternalStoragePresent) before accessing this location. This is because external storage is sometimes removable on same devices, such as an SD card. As of Titanium 9.3.0, this directory does not require the `Manifest.permission.READ_EXTERNAL_STORAGE` and `Manifest.permission.WRITE_EXTERNAL_STORAGE` permissions. For older Titanium SDK versions, these permission are required and you must call the [requestStoragePermissions()](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#requestStoragePermissions) method to request the end-user's permission to read/write to external storage. ### IOS_FILE_PROTECTION_COMPLETE - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 - Permission: read-only Constant used to set protection key to NSFileProtectionComplete in file attributes. File is stored in an encrypted format on disk. Cannot be read from or written to while the device is locked or booting. ### IOS_FILE_PROTECTION_COMPLETE_UNLESS_OPEN - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 - Permission: read-only Constant used to set protection key to NSFileProtectionCompleteUnlessOpen in file attributes. File is stored in an encrypted format on disk. Can be created while the device is locked, but once closed, cannot be opened again until the device is unlocked. If the file is opened when unlocked, you may continue to access the file normally, even if the user locks the device. ### IOS_FILE_PROTECTION_COMPLETE_UNTIL_FIRST_USER_AUTHENTICATION - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 - Permission: read-only Constant used to set protection key to NSFileProtectionCompleteUntilFirstUserAuthentication in file attributes. File is stored in an encrypted format on disk. Cannot be accessed until after the device has booted. After the user unlocks the device for the first time, your app can access the file and continue to access it even if the user subsequently locks the device. ### IOS_FILE_PROTECTION_NONE - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 - Permission: read-only Constant used to set protection key to NSFileProtectionNone in file attributes. File will have no special protection associated with it. Can be read from or written to at any time. ### lineEnding - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Platform-specific line ending constant. ### MODE_APPEND - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Constant for append mode for file operations. ### MODE_READ - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Constant for read mode for file operations. ### MODE_WRITE - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Constant for write mode for file operations. ### resourcesDirectory - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Path to the application's resource directory. This directory is read-only. If you need to modify any files in this directory, they must first be copied to another directory, such as [applicationDataDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#applicationDataDirectory) or [tempDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#tempDirectory). On iOS, writable files can also be placed in the [applicationSupportDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#applicationSupportDirectory). On Android, writable files can also be placed in the [externalStorageDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#externalStorageDirectory). Note that when running on the simulator, the resources directory may be writable, but it is not writable on device. ### resRawDirectory - Type: String - Platforms: Android - Since: Titanium SDK 3.0.2 - Permission: read-only Path to the application's raw resource directory. On Android, the raw resources directory can be used for resources that need to be accessed as individual files, not included in the Android resources bundle. For example, sound files placed in the raw resources directory can be accessed by notifications, which cannot access sound files from the resource directory. To use raw resources, place files in the `platform/android/res/raw` folder, where `platform` is at the top level of the project, not inside the `Resources` folder. You will need to create the `platform` folder and subfolders. This directory is read-only. If you need to modify any files in this directory, they must first be copied to another directory, such as [applicationDataDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#applicationDataDirectory) or [tempDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#tempDirectory). ### separator - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Platform-specific path separator constant. ### tempDirectory - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Path for the application's temporary directory. This directory can be used for storing temporary files. Files in this directory may not persist when the application is shut down and restarted. ## Methods ### createTempDirectory - Platforms: Android, iPhone, iPad, macOS Creates a temporary directory and returns a [File](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md) object representing the new directory. Returns: Titanium.Filesystem.File ### createTempFile - Platforms: Android, iPhone, iPad, macOS Creates a temporary file and returns a [File](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md) object representing the new file. Returns: Titanium.Filesystem.File ### directoryForSuite - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 4.0.0 Returns the path to the container directory associated with the specified security application group ID. This is a writable directory used on iOS. Groups of sandboxed apps that need to share files and other information can request a container directory as part of their entitlements. When called with a valid group identifier, this method returns the location of that directory as a string. Returns null if the group identifier is invalid; check the app's entitlements. Parameters: - `suiteName` (String): The name of the suite. Returns: String ### getAsset - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 Returns a `Blob` object representing the asset catalog image identified by the path arguments. This method is only applicable on images in assets catalogs for apps with app-thinning enabled on iOS. Since the bundled image has been reallocated into assets catalog, it is no longer accessible via the original file path. To obtain a `Blob` object representing this image, use the original file path as the parameter in this method instead of using it in [getFile](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#getFile) Similar to [getFile](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#getFile), this method takes a variable number of arguments, where each argument is treated as a path component. All of the arguments are joined together using the platform-specific path separator to make the final path. If a relative path is passed, the full path should be interpreted relative to the current file. For example, if the file `Resources/login/login.js` contains the following code: ``` js var icon = Titanium.Filesystem.getAsset('icon.png'); ``` The path is interpreted as `Resources/login/icon.png`. On iOS, all relative paths are currently interpreted as relative to the `Resources` directory, **not** to the current context. This is a known issue that will be addressed in a future release. Parameters: - `path` (String, repeatable): One or more path components. Path arguments are joined together using the platform specific path separator to form the full path. Returns: Titanium.Blob ### getFile - Platforms: Android, iPhone, iPad, macOS Returns a `File` object representing the file identified by the path arguments. Note that `getFile` does not create a file if one does not exist at the specified path. It returns a new `File` object referring to the specified file path. The application can create a file at that path by calling [write](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#write) or create a directory by calling [createDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#createDirectory) on the `File` object. This method takes a variable number of arguments, where each argument is treated as a path component. All of the arguments are joined together using the platform-specific path separator to make the final path. If a relative path is passed, the full path should be interpreted relative to the current file. For example, if the file `Resources/login/login.js` contains the following code: ``` js var icon = Titanium.Filesystem.getFile('icon.png'); ``` The path is interpreted as `Resources/login/icon.png`. On iOS, all relative paths are currently interpreted as relative to the `Resources` directory, **not** to the current context. This is a known issue that will be addressed in a future release. On iOS9, if app thinning is enabled, and the file of interest is an image file that was bundled with the app (not downloaded during runtime), this will not return the image file since it is already allocated inside the assets catalog. Please use [getAsset](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#getAsset) instead for this case. Parameters: - `path` (String | Array, repeatable): One or more path components. Path arguments are joined together using the platform specific path separator to form the full path. Returns: Titanium.Filesystem.File ### hasStoragePermissions - Platforms: Android - Since: Titanium SDK 5.4.0 Returns `true` if the app has storage permissions. Returns: Boolean ### isExternalStoragePresent - Platforms: Android, iPhone, iPad, macOS Returns `true` if the device supports external storage *and* the external storage device is mounted. Returns `true` on Android if an external storage device, such as an SD card, is available for reading and writing. Returns `false` on iOS. Returns: Boolean ### openStream - Platforms: Android, iPhone, iPad, macOS Opens file using the [Titanium.IOStream](https://titaniumsdk.com/docs/sdk/Titanium.IOStream.md) interface. Parameters: - `mode` (Number): Access mode. - `path` (String): One or more path components. Path arguments are joined together using the platform-specific path separator to form the full path. Returns: Titanium.Filesystem.FileStream ### requestStoragePermissions - Platforms: Android - Since: Titanium SDK 5.4.0 Requests for storage permissions On Android, the dialog will only appear if the permission is not accepted by the user and the user did not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again," the user has to manually enable the permission in device settings. This method requests `Manifest.permission.READ_EXTERNAL_STORAGE` and `Manifest.permission.WRITE_EXTERNAL_STORAGE`. If you require other permissions, you can also use [Titanium.Android.requestPermissions](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#requestPermissions). Parameters: - `callback` (Callback, optional): Function to call upon user decision to grant storage access. Optional on SDK 10, as this method will return a `Promise`, which may be used to handle the result. Returns: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument. ## Inherited members 7 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.4/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.