# Titanium.Filesystem.File

> Object representing a path to a file or directory in the device's persistent storage.

- Source: https://titaniumsdk.com/docs/sdk/12.7.0/Titanium.Filesystem.File
- Titanium SDK version: 12.7.0
- Kind: proxy
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.1
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

Use the [Titanium.Filesystem.getFile](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#getFile) method to get a handle to a `File` object,
which represents a given path.  There does not need to be an existing file or directory
does not need to exist before `getFile` is called. If the file doesn't exist, and
the file path identifies a file in a writable directory, writing to the file
creates the file implicitly.

See [Titanium.Filesystem](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md) for constants identifying commonly-used device directories.

Use the [exists](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#exists) method to test whether the file exists.

A file object can point to an ordinary file, a directory or a symbolic link.
Use [createDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#createDirectory) to create a directory.
Use the [getDirectoryListing](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#getDirectoryListing) method to
retrieve a list of the directory's contents.

The `File` object doesn't provide methods for random access into the file.
The `read` method reads the file's entire contents into a `Blob` object.
The `write` method can either overwrite the entire file or append to an
existing file.

For random access to a file, such as accessing a small portion of a larger file,
you can open a file as a [FileStream](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.FileStream.md) object. Use the
[open](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#open) method to get a `FileStream` for an
existing `File` object, or use the [Titanium.Filesystem.openStream](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#openStream) method
to get a `FileStream` directly without calling `getFile` first.

The [Titanium.Filesystem](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md) module defines a number of properties and methods related to
filesystem access, including properties that specify paths for application-specific
directories, and methods for creating temporary files and directories.

On Android, files may be stored on external storage (that is, removable media such as
SD Cards).

Note that once created with `getFile`, the path associated with a file object is
immutable. If you move the underlying file using [move](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#move)
or [rename](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#rename), you can no longer access it with the
original `File` object. You must use `getFile` to get a handle to the new path.

#### Resource Files

The `Resources` directory and all the files in it are read-only. On Android, resource
files are stored in the resource bundle and do not have all of the properties of
normal files. In particular, they do not have creation or modification timestamps.

## Example: Reading a File

Data files shipped with the application are stored in the resources directory.

This example reads string data from a text file.

``` js
// resourcesDirectory is actually the default location, so the first
// argument could be omitted here.
file = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, "textfile.txt");
var blob = file.read();
var readText = blob.text;
// dispose of file handle & blob.
file = null;
blob = null;
```

## Example: Creating a Subdirectory

Files that the application writes to need to be stored outside of the
resources directory, since that directory is read-only.

This example creates a subdirectory to store downloaded images.
The example assumes that two variables are defined elsewhere in the code:
myImageID, a string containing some kind of ID for the downloaded image,
and myImageData, a `Blob` containing JPEG image data.

``` js
var imageDir = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory,
    'downloaded_images');
if (! imageDir.exists()) {
    imageDir.createDirectory();
}

// .resolve() provides the resolved native path for the directory.
var imageFile  = Ti.Filesystem.getFile(imageDir.resolve(), myImageID + '.jpg');
Ti.API.info("ImageFile path is: " + imageFile.resolve());
if (imageFile.write(myImageData)===false) {
    // handle write error
}
// dispose of file handles
imageFile = null;
imageDir = null;
```

## Properties

### executable

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

`true` if the file is executable.

On iOS, this property exists but is always `false`.

### hidden

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS

Set to `true` if the file is hidden.

On iOS, this property exists but is always `false`.

### name

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Name of the file.

### nativePath

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Native path associated with this file object, as a file URL.

On iOS, use the [resolve](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#resolve)
method to obtain a plain file path for use with native modules.

### parent

- Type: Titanium.Filesystem.File
- Platforms: Android
- Permission: read-only

A `File` object representing the parent directory of the file identified by this object.

iOS platform-note: Prior to Titanium SDK 7.0.0, this method returned the
path of the parent directory as a String. Since Titanium SDK 7.0.0 it
returnes a [Titanium.Filesystem.File](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md) reference for parity wih Android and Windows.

### readonly

- Type: Boolean
- Platforms: Android
- Permission: read-only

`true` if the file identified by this object is read-only.

### remoteBackup

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 1.8.0
- Default: `true`

Value indicating whether or not to back up to a cloud service.

Some apps may be rejected by Apple for backing up specific files; if this
is the case, ensure that this value is set to `false` for them. This
value should only need to be set once by your app, but setting it
multiple times will not cause problems. For files distributed with your
app, this will need to be set on boot. This flag will only affect iOS
versions 5.0.1 and later, but is safe to set on earlier versions.

Note that setting this property to `false` will also prevent the
file identified by this object from being backed up to iTunes.

### size

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Size, in bytes, of the file identified by this object.

### symbolicLink

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

`true` if the file identified by this object is a symbolic link.

### writable

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

`true` if the file identified by this object is writable.

## Methods

### append

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 0.9.0, iPad 0.9.0, Android 7.3.0

Appends data to the file identified by this file object.

Data to append can be specified as a String, `Blob`, or `File`.

If the `data` argument is a `File` object, the file's contents
are appended to this file.

Returns `true` if the operation succeeds.

Parameters:

- `data` (String | Titanium.Blob | Titanium.Filesystem.File): Data to append.

Returns: Boolean

### copy

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 7.3.0, iPad 7.3.0, Android 0.9.0

Copies the file identified by this file object to a new path.

Returns `true` if the copy succeeds.

Parameters:

- `destinationPath` (String): Destination path to copy to.

Returns: Boolean

### createdAt

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 7.3.0

Returns the creation Date for the file identified by this file object.

On Android, returns a Date whose `getTime()` value is 0 for resource files.

**Important**: When developing for the Apple ecosystem, using this API requires the `NSPrivacyAccessedAPICategoryFileTimestamp`
property set in the privacy manifest that was introduced in iOS 17. You can learn more about it [here](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api).

Returns: Date

### createDirectory

- Platforms: Android, iPhone, iPad, macOS

Creates a directory at the path identified by this file object.

Returns `true` if the directory was created successfully.

Parameters:

- `recursive` (Boolean, optional): Toggles whether to recursively create the directory structure (like mkdir -p). Pass `false` to avoid recursively creating the directory. Defaults to true on SDK 7.3.0+, defaults to false on older SDK versions. Default: `true`.

Returns: Boolean

### createFile

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 0.9.0, iPad 0.9.0, Android 6.1.0

Creates a file at the path identified by this file object.

Note that if you write to a file that doesn't exist, the file is created automatically,
so it is not necessary to call this method unless you want to explicitly create the file
(for example, to create an empty file).

Returns `true` if the file was created successfully. Returns `false` if the
file already exists, or if the file couldn't be created for some other reason.

Returns: Boolean

### createTimestamp

- Platforms: Android, iPhone, iPad, macOS
- DEPRECATED since 7.3.0. Use [createdAt](Titanium.Filesystem.File.createdAt) instead.

Returns the creation timestamp for the file identified by this file object.

On Android, returns 0 for resource files.

Returns: Number

### deleteDirectory

- Platforms: Android, iPhone, iPad, macOS

Deletes the directory identified by this file object.

Returns `true` if the operation was successful. Does nothing if the file
object does not identify a directory.

Parameters:

- `recursive` (Boolean, optional): Pass `true` to recursively delete any directory contents. Default: `false`.

Returns: Boolean

### deleteFile

- Platforms: Android, iPhone, iPad, macOS

Deletes the file identified by this file object.

Returns `true` if the operation was successful.

Returns: Boolean

### exists

- Platforms: Android, iPhone, iPad, macOS

Returns `true` if the file or directory identified by this file object exists on the device.

Returns: Boolean

### extension

- Platforms: Android, iPhone, iPad, macOS

Returns the extension for the file identified by this file object.

Returns: String

### getDirectoryListing

- Platforms: Android, iPhone, iPad, macOS

Returns a listing of the directory identified by this file object, or `null`
if this object doesn't identify a directory.

Returns: Array<String>

### getParent

- Platforms: Android, iPhone, iPad, macOS
- DEPRECATED since 7.0.0. Use the [Titanium.Filesystem.File.parent](Titanium.Filesystem.File.parent) property to receive a `File` reference instead. If you wish to receive the path, use the `nativePath` property of that reference instead.

Returns the path of the parent directory holding the file identified by this
file object, as a String (deprecated) **or** as a `File` object.

Prior to Titanium SDK 7.0.0, on iOS this method returned the path of the parent
directory as a String. Since Titanium SDK 7.0.0, this method has been deprecated
in favor of the [parent](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#parent) property and will return
a [File](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md) reference in the future as well.

Returns: String | Titanium.Filesystem.File - Returns a String on iOS, a `Titanium.Filesystem.File` on Android

### getProtectionKey

- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 4.1.0

Returns the protection key value of this file object.
Returns `null` if there's an error.

Returns: String

### isDirectory

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0

Returns `true` if this file object represents a directory.

Returns: Boolean

### isFile

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.1.0

Returns `true` if this file object represents an ordinary file.

Returns: Boolean

### modificationTimestamp

- Platforms: Android, iPhone, iPad, macOS
- DEPRECATED since 7.3.0. Use [Titanium.Filesystem.File.modifiedAt](Titanium.Filesystem.File.modifiedAt) instead.

Returns the last modification time for this file.

On Android, returns 0 for resource files.

Returns: Number

### modifiedAt

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 7.3.0

Returns the last modification Date for the file identified by this file object.

On Android, returns a Date whose `getTime()` value is 0 for resource files.

**Important**: When developing for the Apple ecosystem, using this API requires the `NSPrivacyAccessedAPICategoryFileTimestamp`
property set in the privacy manifest that was introduced in iOS 17. You can learn more about it [here](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api).

Returns: Date

### move

- Platforms: Android, iPhone, iPad, macOS

Moves the file identified by this file object to another path.

Note that this method moves the stored file, but doesn't update this
file object to point to the new path. To access the file after moving it,
you must call [getFile](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#getFile) using the destination
path to obtain a new file handle.

Parameters:

- `newpath` (String): New location for the file.

Returns: Boolean

### open

- Platforms: Android, iPhone, iPad, macOS

Opens the file identified by this file object for random access.

You can open the file for reading, writing, or appending by specifying one of the
`MODE` constants from [Titanium.Filesystem](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md):
[MODE_READ](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#MODE_READ), [MODE_WRITE](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#MODE_WRITE),
or [MODE_APPEND](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#MODE_APPEND).

The `FileStream` object returned by this call can be used to read from, write to, or
append to the file, depending on what mode the file is opened in.

Parameters:

- `mode` (Number): Mode to open the file in: `MODE_READ`, `MODE_WRITE`, or `MODE_APPEND`.

Returns: Titanium.Filesystem.FileStream

### read

- Platforms: Android, iPhone, iPad, macOS

Returns the contents of the file identified by this file object as a `Blob`.

Returns: Titanium.Blob

### rename

- Platforms: Android, iPhone, iPad, macOS

Renames the file identified by this file object.

Returns `true` if the file was successfully renamed.

Fails if the destination is in a different directory than the current file.
Use [move](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#move) to move a file to a different directory.

Note that this method renames the stored file, but doesn't update this
file object to point to the new path. To access the file after renaming it,
you must call [getFile](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#getFile) using the destination
path to obtain a new file handle.

Parameters:

- `newname` (String): New name for the file.

Returns: Boolean

### resolve

- Platforms: Android, iPhone, iPad, macOS

Returns the fully-resolved native path associated with this file object.

On iOS, the path returned by this method is a plain file path, not a URL. It is suitable
for use in native modules that need to access the file using native APIs.

On Android, the return value of `resolve` is a `file://` URL, identical to the
[nativePath](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#nativePath) property.

Returns: String

### setProtectionKey

- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 4.1.0

Sets the protection key as an attribute to the file identified by this file object.

Returns `true` if successfully set. Returns `false` if failed.

Parameters:

- `fileProtectionType` (String): File protection type.

Returns: Boolean

### spaceAvailable

- Platforms: Android, iPhone, iPad, macOS

Returns the amount of free space available on the device where the file identified by this file object is stored.

Free space is returned in bytes.

**Important**: When developing for the Apple ecosystem, using this API requires the `NSPrivacyAccessedAPICategoryDiskSpace`
property set in the privacy manifest that was introduced in iOS 17. You can learn more about it [here](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api).

Returns: Number

### write

- Platforms: Android, iPhone, iPad, macOS

Writes the specified data to the file identified by this file object.

If the `append` parameter is `false` or not specified, any existing data in
the file is overwritten.

If `append` is `true`, the specified data is appended to the end of the file.

Parameters:

- `data` (String | Titanium.Filesystem.File | Titanium.Blob): Data to write, as a String, `Blob` or `File` object.
- `append` (Boolean, optional): If `true`, append the data to the end of the file. Default: `false`.

Returns: Boolean

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.7.0/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`.