Non-standard: This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
Deprecated: This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.
The DirectoryEntrySync interface represents a directory in a file system. It includes methods for creating, reading, looking up, and recursively removing files in a directory.
Warning: This interface is deprecated and is no more on the standard track. Do not use it anymore. Use the File and Directory Entries API instead.
Basic concepts
If you want to create subdirectories, you have to create each child directory in sequence. If you try to create a directory using a full path that includes parent directories that do not exist yet, you get an error. So create the hierarchy by recursively adding a new path after creating the parent directory.
Example
The getFile() method returns a FileEntrySync, which represents a file in the file system. The following creates an empty file called logs.txt in the root directory.
The getDirectory() method returns a DirectoryEntrySync, which represents a file in the file system. The following creates a new directory called project_dir in the root directory.
This method can raise a DOMException with the following codes:
Exception
Description
NOT_FOUND_ERR
The directory does not exist.
SECURITY_ERR
The browser determined that it was not safe to look up the metadata. [ todo: Explain why ]
getFile()
Depending on how you've set the options parameter, the method either creates a file or looks up an existing file.
Syntax
getFile(path)
getFile(path, options)
Parameter
path
Either an absolute path or a relative path from the directory to the file to be looked up or created. You cannot create a file whose immediate parent does not exist. Create the parent directory first.
options
(optional) An object literal describing the behavior of the method. If the file does not exist, it is created.
Object literal
Condition
Result
create: true exclusive: true
Path already exists
An error is thrown.
create: true exclusive: false
Path doesn't exist and no other error occurs
A file is created. If a file already exists, no error is thrown.
This method can raise a DOMException with the following codes:
Exception
Description
ENCODING_ERR
The path supplied is invalid.
NOT_FOUND_ERR
The path was structurally correct, but refers to a resource that does not exist.
NO_MODIFICATION_ALLOWED_ERR
This is a permission issue. The target directory or file is not writable.
PATH_EXISTS_ERR
The file already exists. You cannot create another one with the same path.
QUOTA_EXCEEDED_ERROR
The operation would cause the application to exceed its storage quota.
SECURITY_ERR
The application does not have permission to access the element referred to by path. [ todo: Explain why ]
TYPE_MISMATCH_ERR
The path supplied exists, but it is not a directory.
getDirectory()
Creates or looks up a directory. The method is similar to getFile() with DirectoryEntrySync being passed.
Syntax
getDirectory(path)
getDirectory(path, options)
Parameter
path
Either an absolute path or a relative path from the directory to the file to be looked up or created. You cannot create a file whose immediate parent does not exist. Create the parent directory first.
options
(optional) An object literal describing the behavior of the method if the file does not exist.
Object literal
Condition
Result
create: true exclusive: true
Path already exists
An error is thrown.
create: true exclusive: false
Path doesn't exist and no other error occurs
A directory is created. If a file already exists, no error is thrown.
This method can raise a DOMException with the following codes:
Exception
Description
ENCODING_ERR
The path supplied is invalid.
NOT_FOUND_ERR
The path was structurally correct, but refers to a resource that does not exist.
NO_MODIFICATION_ALLOWED_ERR
This is a permission issue. The target directory or file is not writable.
PATH_EXISTS_ERR
The file already exists. You cannot create another one with the same path.
QUOTA_EXCEEDED_ERROR
The operation would cause the application to exceed its storage quota.
SECURITY_ERR
The application does not have permission to access the element referred to by path. [ todo: Explain why ]
TYPE_MISMATCH_ERR
The path supplied exists, but it is not a directory.
removeRecursively()
Deletes a directory and all of its contents. You cannot delete the root directory of a file system.
If you delete a directory that contains a file that cannot be removed or if an error occurs while the deletion is in progress, some of the contents might not be deleted. Catch these cases with error callbacks and retry the deletion.