W3C

File API: Directories and System

W3C Working Draft 17 April 2012

This version:
http://www.w3.org/TR/2012/WD-file-system-api-20120417/
Latest published version:
http://www.w3.org/TR/file-system-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/file-system/file-dir-sys.html
Previous version:
http://www.w3.org/TR/2011/WD-file-system-api-20110419/
Editor:
Eric Uhrhane, Google

Abstract

This specification defines an API to navigate file system hierarchies, and defines a means by which a user agent may expose sandboxed sections of a user's local filesystem to web applications. It builds on [FILE-WRITER-ED], which in turn built on [FILE-API-ED], each adding a different kind of functionality.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the WebApps Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: a user agent that implements the interfaces that it contains.

2. Introduction

This section is non-normative.

This API is intended to satisfy client-side-storage use cases not well served by databases. These are generally applications that involve large binary blobs and/or share data with applications outside of the browser.

It is intended to be minimal in extent, but sufficiently powerful that easy-to-use libraries may be built on top of it.

2.1 Use Cases

  1. Persistent uploader
    • When a file or directory is selected for upload, it copies it into a local sandbox and uploads a chunk at a time.
    • It can restart uploads after browser crashes, network interruptions, etc.
  2. Video game or other app with lots of media assets
    • It downloads one or several large tarballs, and expands them locally into a directory structure.
    • The same download should work on any operating system.
    • It can manage prefetching just the next-to-be-needed assets in the background, so going to the next game level or activating a new feature doesn't require waiting for a download.
    • It uses those assets directly from its local cache, by direct file reads or by handing local URLs to image or video tags, WebGL asset loaders, etc.
    • The files may be of arbitrary binary format.
    • On the server side, a compressed tarball will often be much smaller than a collection of separately-compressed files. Also, 1 tarball instead of 1000 little files will involve fewer seeks, all else being equal.
  3. Audio/Photo editor with offline access or local cache for speed
    • The data blobs are potentially quite large, and are read-write.
    • It may want to do partial writes to files (ovewriting just the ID3/EXIF tags, for example).
    • The ability to organize project files by creating directories would be useful.
    • Edited files should be accessable by client-side applications [iTunes, Picasa].
  4. Offline video viewer
    • It downloads large files (>1GB) for later viewing.
    • It needs efficient seek + streaming.
    • It must be able to hand a URL to the video tag.
    • It should enable access to partly-downloaded files e.g. to let you watch the first episode of the DVD even if your download didn't complete before you got on the plane.
    • It should be able to pull a single episode out of the middle of a download and give just that to the video tag.
  5. Offline Web Mail Client
    • Downloads attachments and stores them locally.
    • Caches user-selected attachments for later upload.
    • Needs to be able to refer to cached attachments and image thumbnails for display and upload.
    • Should be able to trigger the UA's download manager just as if talking to a server.
    • Should be able to upload an email with attachments as a multipart post, rather than sending a file at a time in an XHR.

2.2 Examples

// In the DOM or worker context:

function useAsyncFS(fs) {
  // see getAsText example in [FILE-API-ED].
  fs.root.getFile("already_there.txt", null, function (f) {
    getAsText(f.file());
  });

  // But now we can also write to the file; see [FILE-WRITER-ED].
  fs.root.getFile("logFile", {create: true}, function (f) {
    f.createWriter(writeDataToLogFile);
  });
}
requestFileSystem(TEMPORARY, 1024 * 1024, function(fs) {
  useAsyncFS(fs);
});

// In a worker:

var tempFS = requestFileSystem(TEMPORARY, 1024 * 1024);
var logFile = tempFS.root.getFile("logFile", {create: true});
var writer = logFile.createWriter();
writer.seek(writer.length);
writeDataToLogFile(writer);

3. Terminology

The term throw in this specification, as it pertains to exceptions, is used as defined in the DOM4 specification [DOM4].

DOMError is defined in the DOM4 specification [DOM4].

File is defined in the File API specification [FILE-API-ED].

FileWriter and FileWriterSync are defined in the FileWriter specification [FILE-WRITER-ED].

4. Data Persistence and accessing the API

4.1 Temporary vs. Persistent Storage

This section is non-normative.

An application can request temporary or persistent storage space. Temporary storage may be easier to get, at the UA's discretion [looser quota restrictions, available without prompting the user], but the data stored there may be deleted at the UA's convenience, e.g. to deal with a shortage of disk space.

Conversely, once persistent storage has been granted, data stored there by the application should not be deleted by the UA without user intervention. The application may of course delete it at will. The UA should require permission from the user before granting persistent storage space to the application.

This API specifies the standard origin isolation in a filesystem context, along with persistence of data across invocations. Applications will likely use temporary storage for caching, and if it's still around from a previous session, it is often useful. Persistent data, on the other hand, is useless if you can't access it again the next time you're invoked. However, even persistent data may be deleted manually by the user [either through the UA or via direct filesystem operations].

4.2 Restrictions

FileSystem and FileSystemSync objects returned by requestFileSystem must have the following properties:

4.3 Security Considerations

This section is non-normative.

Because this API may allow untrusted code to read and write parts of a user's hard drive, there are a number of security and privacy issues that must be dealt with. Risks to the user include:

As with any other client-side storage, filesystem access allows for cookie-resurrection attacks. UAs will likely wish to present the option of clearing it when the user clears any other origin-specific storage, blocking access to it when cookies are blocked, etc. This is especially important if temporary storage space is permitted by default without explicit user permission.

4.4 Obtaining access to file system entry points

There are several ways in which a file system entry point can be obtained. Not all user agents may in fact implement all of them. However, in order to avoid blocking UI actions while waiting on filesystem IO, we define only an asynchronous interface for Window, and restrict the synchronous API to the Worker context defined in [WEBWORKERS-ED].

4.4.1 Using LocalFileSystem

Window implements LocalFileSystem;

All instances of the Window type are defined to also implement the LocalFileSystem interface.

WorkerGlobalScope implements LocalFileSystem;

All instances of the WorkerGlobalScope type are defined to also implement the LocalFileSystem interface.

[Supplemental, NoInterfaceObject]
interface LocalFileSystem {
    const unsigned short TEMPORARY = 0;
    const unsigned short PERSISTENT = 1;
    void requestFileSystem (unsigned short type, unsigned long long size, FileSystemCallback successCallback, optional ErrorCallback errorCallback);
    void resolveLocalFileSystemURL (DOMString url, EntryCallback successCallback, optional ErrorCallback errorCallback);
};
4.4.1.1 Methods
requestFileSystem

Requests a filesystem in which to store application data.

If successful, this function must give access to an origin-private filesystem, as defined above.

ParameterTypeNullableOptionalDescription
typeunsigned short Whether the filesystem requested should be persistent, as defined above. Use one of TEMPORARY or PERSISTENT.
sizeunsigned long long This is an indicator of how much storage space, in bytes, the application expects to need.
successCallbackFileSystemCallback The callback that is called when the user agent provides a filesystem.
errorCallbackErrorCallback A callback that is called when errors happen, or when the request to obtain the filesystem is denied.
Return type: void
resolveLocalFileSystemURL

Allows the user to look up the Entry for a file or directory referred to by a local URL.

ParameterTypeNullableOptionalDescription
urlDOMString A URL referring to a local file in a filesystem accessable via this API.
successCallbackEntryCallback A callback that is called to report the Entry to which the supplied URL refers.
errorCallbackErrorCallback A callback that is called when errors happen, or when the request to obtain the Entry is denied.
Return type: void
4.4.1.2 Constants
PERSISTENT of type unsigned short
Used for storage that should not be removed by the user agent without application or user permission.
TEMPORARY of type unsigned short
Used for storage with no guarantee of persistence.

4.4.2 Using LocalFileSystemSync

WorkerGlobalScope implements LocalFileSystemSync;

All instances of the WorkerGlobalScope type are defined to also implement the LocalFileSystemSync interface.

[Supplemental, NoInterfaceObject]
interface LocalFileSystemSync {
    const unsigned short TEMPORARY = 0;
    const unsigned short PERSISTENT = 1;
    FileSystemSync requestFileSystemSync (unsigned short type, unsigned long long size);
    EntrySync      resolveLocalFileSystemSyncURL (DOMString url);
};
4.4.2.1 Methods
requestFileSystemSync

Requests a filesystem in which to store application data.

If successful, this function must give access to an origin-private filesystem, as defined above.

ParameterTypeNullableOptionalDescription
typeunsigned short Whether the filesystem requested should be persistent, as defined above. Use one of TEMPORARY or PERSISTENT.
sizeunsigned long long This is an indicator of how much storage space, in bytes, the application expects to need.
Return type: FileSystemSync
resolveLocalFileSystemSyncURL

Allows the user to look up the Entry for a file or directory referred to by a local URL.

ParameterTypeNullableOptionalDescription
urlDOMString A URL referring to a local file in a filesystem accessable via this API.
Return type: EntrySync
4.4.2.2 Constants
PERSISTENT of type unsigned short
Used for storage that should not be removed by the user agent without application or user permission.
TEMPORARY of type unsigned short
Used for storage with no guarantee of persistence.

5. Shared data types

5.1 The Metadata interface

This interface supplies information about the state of a file or directory.

interface Metadata {
    readonly attribute Date               modificationTime;
    readonly attribute unsigned long long size;
};

5.1.1 Attributes

modificationTime of type Date, readonly
This is the time at which the file or directory was last modified.
size of type unsigned long long, readonly
The size of the file, in bytes. This must return 0 for directories.

5.2 The Flags dictionary

This dictionary is used to supply arguments to methods that look up or create files or directories.

dictionary Flags {
    boolean create;
    boolean exclusive;
};

5.2.1 Dictionary Flags Members

create of type boolean
Used to indicate that the user wants to create a file or directory if it was not previously there.
exclusive of type boolean
By itself, exclusive must have no effect. Used with create, it must cause getFile and getDirectory to fail if the target path already exists.

5.2.2 Examples

This section is non-normative.

// Get the data directory, creating it if it doesn't exist.
dataDir = fsSync.root.getDirectory("data", {create: true});

// Create the lock file, if and only if it doesn't exist.
try {
  lockFile = dataDir.getFile("lockfile.txt",
                             {create: true, exclusive: true});
} catch (ex) {
  // It already exists, or something else went wrong.
  ...
}

6. The asynchronous filesystem interface

6.1 The FileSystem interface

This interface represents a file system.

interface FileSystem {
    readonly attribute DOMString      name;
    readonly attribute DirectoryEntry root;
};

6.1.1 Attributes

name of type DOMString, readonly
This is the name of the file system. The specifics of naming filesystems is unspecified, but a name must be unique across the list of exposed file systems.
root of type DirectoryEntry, readonly
The root directory of the file system.

6.2 The Entry interface

An abstract interface representing entries in a file system, each of which may be a File or DirectoryEntry.

interface Entry {
    readonly attribute boolean    isFile;
    readonly attribute boolean    isDirectory;
    void      getMetadata (MetadataCallback successCallback, optional ErrorCallback errorCallback);
    readonly attribute DOMString  name;
    readonly attribute DOMString  fullPath;
    readonly attribute FileSystem filesystem;
    void      moveTo (DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    void      copyTo (DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    DOMString toURL ();
    void      remove (VoidCallback successCallback, optional ErrorCallback errorCallback);
    void      getParent (EntryCallback successCallback, optional ErrorCallback errorCallback);
};

6.2.1 Attributes

filesystem of type FileSystem, readonly
The file system on which the entry resides.
fullPath of type DOMString, readonly
The full absolute path from the root to the entry.
isDirectory of type boolean, readonly
Entry is a directory.
isFile of type boolean, readonly
Entry is a file.
name of type DOMString, readonly
The name of the entry, excluding the path leading to it.

6.2.2 Methods

copyTo

Copy an entry to a different location on the file system. It is an error to try to:

  • copy a directory inside itself or to any child at any depth;
  • copy an entry into its parent if a name different from its current one isn't provided;
  • copy a file to a path occupied by a directory;
  • copy a directory to a path occupied by a file;
  • copy any element to a path occupied by a directory which is not empty.
A copy of a file on top of an existing file must attempt to delete and replace that file.
A copy of a directory on top of an existing empty directory must attempt to delete and replace that directory.
Directory copies are always recursive--that is, they copy all contents of the directory.

ParameterTypeNullableOptionalDescription
parentDirectoryEntry The directory to which to move the entry.
newNameDOMString The new name of the entry. Defaults to the Entry's current name if unspecified.
successCallbackEntryCallback A callback that is called with the Entry for the new object.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
getMetadata

Look up metadata about this entry.

ParameterTypeNullableOptionalDescription
successCallbackMetadataCallback A callback that is called with the time of the last modification.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
getParent
Look up the parent DirectoryEntry containing this Entry. If this Entry is the root of its filesystem, its parent is itself.
ParameterTypeNullableOptionalDescription
successCallbackEntryCallback A callback that is called to return the parent Entry.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
moveTo

Move an entry to a different location on the file system. It is an error to try to:

  • move a directory inside itself or to any child at any depth;
  • move an entry into its parent if a name different from its current one isn't provided;
  • move a file to a path occupied by a directory;
  • move a directory to a path occupied by a file;
  • move any element to a path occupied by a directory which is not empty.
A move of a file on top of an existing file must attempt to delete and replace that file.
A move of a directory on top of an existing empty directory must attempt to delete and replace that directory.

ParameterTypeNullableOptionalDescription
parentDirectoryEntry The directory to which to move the entry.
newNameDOMString The new name of the entry. Defaults to the Entry's current name if unspecified.
successCallbackEntryCallback A callback that is called with the Entry for the new location.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
remove

Deletes a file or directory. It is an error to attempt to delete a directory that is not empty. It is an error to attempt to delete the root directory of a filesystem.

ParameterTypeNullableOptionalDescription
successCallbackVoidCallback A callback that is called on success.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
toURL

Returns a URL that can be used to identify this entry. Unlike the URN defined in [FILE-API-ED], it has no specific expiration; as it describes a location on disk, it should be valid at least as long as that location exists.

Do we want to spec out the URL format/scheme? It would be quite nice if these could be edited and manipulated easily, as with normal filesystem paths.

How and where can these URLs be used? Can they be interchangeable with online URLs for the same domain?

Proposal currently under discussion:

  • Use a format such as filesystem:http://example.domain/persistent-or-temporary/path/to/file.html.
  • URLs should be usable for anything that online URLs can be used for, whether they appear in online or filesystem-resident web pages.
  • However, they can only be used by the origin that owns the filesystem. No other origin can e.g. reference another origin's filesystem in an IMG tag.

No parameters.
Return type: DOMString

6.3 The DirectoryEntry interface

This interface represents a directory on a file system.

interface DirectoryEntry : Entry {
    DirectoryReader createReader ();
    void            getFile (DOMString path, optional Flags options, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    void            getDirectory (DOMString path, optional Flags options, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    void            removeRecursively (VoidCallback successCallback, optional ErrorCallback errorCallback);
};

6.3.1 Methods

createReader

Creates a new DirectoryReader to read Entries from this Directory.

No parameters.
Return type: DirectoryReader
getDirectory

Creates or looks up a directory.

ParameterTypeNullableOptionalDescription
pathDOMString Either an absolute path or a relative path from this DirectoryEntry to the directory to be looked up or created. It is an error to attempt to create a directory whose immediate parent does not yet exist.
optionsFlags
  • If create and exclusive are both true and the path already exists, getDirectory must fail.
  • If create is true, the path doesn't exist, and no other error occurs, getDirectory must create and return a corresponding DirectoryEntry.
  • If create is not true and the path doesn't exist, getDirectory must fail.
  • If create is not true and the path exists, but is a file, getDirectory must fail.
  • Otherwise, if no other error occurs, getDirectory must return a DirectoryEntry corresponding to path.
successCallbackEntryCallback A callback that is called to return the DirectoryEntry selected or created.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
getFile

Creates or looks up a file.

ParameterTypeNullableOptionalDescription
pathDOMString Either an absolute path or a relative path from this DirectoryEntry to the file to be looked up or created. It is an error to attempt to create a file whose immediate parent does not yet exist.
optionsFlags
  • If create and exclusive are both true, and the path already exists, getFile must fail.
  • If create is true, the path doesn't exist, and no other error occurs, getFile must create it as a zero-length file and return a corresponding FileEntry.
  • If create is not true and the path doesn't exist, getFile must fail.
  • If create is not true and the path exists, but is a directory, getFile must fail.
  • Otherwise, if no other error occurs, getFile must return a FileEntry corresponding to path.
successCallbackEntryCallback A callback that is called to return the File selected or created.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
removeRecursively

Deletes a directory and all of its contents, if any. In the event of an error [e.g. trying to delete a directory that contains a file that cannot be removed], some of the contents of the directory may be deleted. It is an error to attempt to delete the root directory of a filesystem.

ParameterTypeNullableOptionalDescription
successCallbackVoidCallback A callback that is called on success.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void

6.4 The DirectoryReader interface

This interface lets a user list files and directories in a directory. If there are no additions to or deletions from a directory between the first and last call to readEntries, and no errors occur, then:

interface DirectoryReader {
    void readEntries (EntriesCallback successCallback, optional ErrorCallback errorCallback);
};

6.4.1 Methods

readEntries

Read the next block of entries from this directory.

ParameterTypeNullableOptionalDescription
successCallbackEntriesCallback Called once per successful call to readEntries to deliver the next previously-unreported set of Entries in the associated Directory. If all Entries have already been returned from previous invocations of readEntries, successCallback must be called with a zero-length array as an argument.
errorCallbackErrorCallback A callback indicating that there was an error reading from the Directory.
Return type: void

6.5 The FileEntry interface

This interface represents a file on a file system.

interface FileEntry : Entry {
    void createWriter (FileWriterCallback successCallback, optional ErrorCallback errorCallback);
    void file (FileCallback successCallback, optional ErrorCallback errorCallback);
};

6.5.1 Methods

createWriter

Creates a new FileWriter associated with the file that this FileEntry represents.

ParameterTypeNullableOptionalDescription
successCallbackFileWriterCallback A callback that is called with the new FileWriter.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void
file

Returns a File that represents the current state of the file that this FileEntry represents.

ParameterTypeNullableOptionalDescription
successCallbackFileCallback A callback that is called with the File.
errorCallbackErrorCallback A callback that is called when errors happen.
Return type: void

6.6 Callbacks

Several calls in this API are asynchronous, and use callbacks.

6.6.1 The FileSystemCallback interface

When requestFileSystem() succeeds, the following callback is made:

[Callback=FunctionOnly]
interface FileSystemCallback {
    void handleEvent (FileSystem filesystem);
};
6.6.1.1 Methods
handleEvent

The file system was successfully obtained.

ParameterTypeNullableOptionalDescription
filesystemFileSystem The file systems to which the app is granted access.
Return type: void

6.6.2 The EntryCallback interface

This interface is the callback used to look up Entry objects.

[Callback=FunctionOnly]
interface EntryCallback {
    void handleEvent (Entry entry);
};
6.6.2.1 Methods
handleEvent
Used to supply an Entry as a response to a user query.
ParameterTypeNullableOptionalDescription
entryEntry
Return type: void

6.6.3 The EntriesCallback interface

When readEntries() succeeds, the following callback is made.

[Callback=FunctionOnly]
interface EntriesCallback {
    void handleEvent (Entry[] entries);
};
6.6.3.1 Methods
handleEvent
Used to supply an array of Entries as a response to a user query.
ParameterTypeNullableOptionalDescription
entriesEntry[]
Return type: void

6.6.4 The MetadataCallback interface

This interface is the callback used to look up file and directory metadata.

[Callback=FunctionOnly]
interface MetadataCallback {
    void handleEvent (Metadata metadata);
};
6.6.4.1 Methods
handleEvent

Used to supply file or directory metadata as a response to a user query.

ParameterTypeNullableOptionalDescription
metadataMetadata
Return type: void

6.6.5 The FileWriterCallback interface

This interface is the callback used to create a FileWriter.

[Callback=FunctionOnly]
interface FileWriterCallback {
    void handleEvent (FileWriter fileWriter);
};
6.6.5.1 Methods
handleEvent

Used to supply a FileWriter as a response to a user query.

ParameterTypeNullableOptionalDescription
fileWriterFileWriter
Return type: void

6.6.6 The FileCallback interface

This interface is the callback used to obtain a File.

[Callback=FunctionOnly]
interface FileCallback {
    void handleEvent (File file);
};
6.6.6.1 Methods
handleEvent

Used to supply a File as a response to a user query.

ParameterTypeNullableOptionalDescription
fileFile
Return type: void

6.6.7 The VoidCallback interface

This interface is the generic callback used to indicate success of an asynchronous method.

[Callback=FunctionOnly]
interface VoidCallback {
    void handleEvent ();
};
6.6.7.1 Methods
handleEvent
No parameters.
Return type: void

6.6.8 The ErrorCallback interface

When an error occurs, the following callback is made:

[Callback=FunctionOnly]
interface ErrorCallback {
    void handleEvent (DOMError err);
};
6.6.8.1 Methods
handleEvent

There was an error with the request. Details are provided by the err parameter.

ParameterTypeNullableOptionalDescription
errDOMError The error that was generated.
Return type: void

7. The synchronous filesystem interface

7.1 The FileSystemSync interface

This interface represents a file system.

interface FileSystemSync {
    readonly attribute DOMString          name;
    readonly attribute DirectoryEntrySync root;
};

7.1.1 Attributes

name of type DOMString, readonly
This is the name of the file system. The specifics of naming filesystems is unspecified, but a name must be unique across the list of exposed file systems.
root of type DirectoryEntrySync, readonly
The root directory of the file system.

7.2 The EntrySync interface

An abstract interface representing entries in a file system, each of which may be a FileEntrySync or DirectoryEntrySync.

Some have requested support for archive files. I've not required that, but I've left space for it by not ruling out having both isFile and isDirectory be true. I welcome comments on this approach.

interface EntrySync {
    readonly attribute boolean        isFile;
    readonly attribute boolean        isDirectory;
    Metadata           getMetadata ();
    readonly attribute DOMString      name;
    readonly attribute DOMString      fullPath;
    readonly attribute FileSystemSync filesystem;
    EntrySync          moveTo (DirectoryEntrySync parent, optional DOMString newName);
    EntrySync          copyTo (DirectoryEntrySync parent, optional DOMString newName);
    DOMString          toURL ();
    void               remove ();
    DirectoryEntrySync getParent ();
};

7.2.1 Attributes

filesystem of type FileSystemSync, readonly
The file system on which the entry resides.
fullPath of type DOMString, readonly
The full absolute path from the root to the entry.
isDirectory of type boolean, readonly
EntrySync is a directory.
isFile of type boolean, readonly
EntrySync is a file.
name of type DOMString, readonly
The name of the entry, excluding the path leading to it.

7.2.2 Methods

copyTo

Copy an entry to a different location on the file system. It is an error to try to:

  • copy a directory inside itself or to any child at any depth;
  • copy an entry into its parent if a name different from its current one isn't provided;
  • copy a file to a path occupied by a directory;
  • copy a directory to a path occupied by a file;
  • copy any element to a path occupied by a directory which is not empty.
A copy of a file on top of an existing file must attempt to delete and replace that file.
A copy of a directory on top of an existing empty directory must attempt to delete and replace that directory.
Directory copies are always recursive--that is, they copy all contents of the directory.

ParameterTypeNullableOptionalDescription
parentDirectoryEntrySync The directory to which to move the entry.
newNameDOMString The new name of the entry. Defaults to the EntrySync's current name if unspecified.
Return type: EntrySync
getMetadata

Look up metadata about this entry.

No parameters.
Return type: Metadata
getParent
Look up the parent DirectoryEntrySync containing this Entry. If this EntrySync is the root of its filesystem, its parent is itself.
No parameters.
Return type: DirectoryEntrySync
moveTo

Move an entry to a different location on the file system. It is an error to try to:

  • move a directory inside itself or to any child at any depth;
  • move an entry into its parent if a name different from its current one isn't provided;
  • move a file to a path occupied by a directory;
  • move a directory to a path occupied by a file;
  • move any element to a path occupied by a directory which is not empty.
A move of a file on top of an existing file must attempt to delete and replace that file. A move of a directory on top of an existing empty directory must attempt to delete and replace that directory.

ParameterTypeNullableOptionalDescription
parentDirectoryEntrySync The directory to which to move the entry.
newNameDOMString The new name of the entry. Defaults to the EntrySync's current name if unspecified.
Return type: EntrySync
remove

Deletes a file or directory. It is an error to attempt to delete a directory that is not empty. It is an error to attempt to delete the root directory of a filesystem.

No parameters.
Return type: void
toURL

Returns a URL that can be used to identify this entry. Unlike the URN defined in [FILE-API-ED], it has no specific expiration; as it describes a location on disk, it should be valid at least as long as that location exists.

No parameters.
Return type: DOMString

7.3 The DirectoryEntrySync interface

This interface represents a directory on a file system.

interface DirectoryEntrySync : EntrySync {
    DirectoryReaderSync createReader ();
    FileEntrySync       getFile (DOMString path, optional Flags options);
    DirectoryEntrySync  getDirectory (DOMString path, optional Flags options);
    void                removeRecursively ();
};

7.3.1 Methods

createReader

Creates a new DirectoryReaderSync to read EntrySyncs from this DirectorySync.

No parameters.
Return type: DirectoryReaderSync
getDirectory

Creates or looks up a directory.

ParameterTypeNullableOptionalDescription
pathDOMString Either an absolute path or a relative path from this DirectoryEntrySync to the directory to be looked up or created. It is an error to attempt to create a directory whose immediate parent does not yet exist.
optionsFlags
  • If create and exclusive are both true and the path already exists, getDirectory must fail.
  • If create is true, the path doesn't exist, and no other error occurs, getDirectory must create and return a corresponding DirectoryEntry.
  • If create is not true and the path doesn't exist, getDirectory must fail.
  • If create is not true and the path exists, but is a file, getDirectory must fail.
  • Otherwise, if no other error occurs, getDirectory must return a DirectoryEntrySync corresponding to path.
Return type: DirectoryEntrySync
getFile

Creates or looks up a file.

ParameterTypeNullableOptionalDescription
pathDOMString Either an absolute path or a relative path from this DirectoryEntrySync to the file to be looked up or created. It is an error to attempt to create a file whose immediate parent does not yet exist.
optionsFlags
  • If create and exclusive are both true and the path already exists, getFile must fail.
  • If create is true, the path doesn't exist, and no other error occurs, getFile must create it as a zero-length file and return a corresponding FileEntry.
  • If create is not true and the path doesn't exist, getFile must fail.
  • If create is not true and the path exists, but is a directory, getFile must fail.
  • Otherwise, if no other error occurs, getFile must return a FileEntrySync corresponding to path.
Return type: FileEntrySync
removeRecursively

Deletes a directory and all of its contents, if any. In the event of an error [e.g. trying to delete a directory that contains a file that cannot be removed], some of the contents of the directory may be deleted. It is an error to attempt to delete the root directory of a filesystem.

No parameters.
Return type: void

7.4 The DirectoryReaderSync interface

This interface lets a user list files and directories in a directory. If there are no additions to or deletions from a directory between the first and last call to readEntries, and no errors occur, then:

interface DirectoryReaderSync {
    EntrySync[] readEntries ();
};

7.4.1 Methods

readEntries

Read the next block of entries from this directory.

No parameters.
Return type: EntrySync[]

7.5 The FileEntrySync interface

This interface represents a file on a file system.

interface FileEntrySync : EntrySync {
    FileWriterSync createWriter ();
    File           file ();
};

7.5.1 Methods

createWriter

Creates a new FileWriterSync associated with the file that this FileEntrySync represents.

No parameters.
Return type: FileWriterSync
file

Returns a File that represents the current state of the file that this FileEntrySync represents.

No parameters.
Return type: File

8. Errors and Exceptions

8.1 Occurrence

This section is non-normative.

Error conditions can occur when attempting to write files. The list below of potential error conditions is informative, with links to normative descriptions of errors:

An operation on a file may fail due to the file [or a parent directory] having been removed before the operation is attempted. See NotFoundError.

An operation on a file may not make sense, e.g. moving a directory into one of its own children. See InvalidModificationError.

An operation on a file may not make sense if the underlying filesystem has had changes made since the reference was obtained. See TypeMismatchError, InvalidStateError.

Users may accidentally attempt to create a file where another already exists. See PathExistsError.

8.2 Definitions

Synchronous methods must throw an exception of the most appropriate type in the table below if there has been an error with writing.

If an error occurs while processing an asynchronous method, the err argument to the ErrorCallback must be a DOMError object [DOM4] of the most appropriate type from the table below.

Error Descriptions

NameDescription
EncodingError A path or URL supplied to the API was malformed.
InvalidModificationError The modification requested was illegal. Examples of invalid modifications include moving a directory into its own child, moving a file into its parent directory without changing its name, or copying a directory to a path occupied by a file.
InvalidStateError An operation depended on state cached in an interface object, but that state that has changed since it was read from disk.
Which values will actually go stale? Modification time, name, more rarely type. If an atomic save [replacing a file with a new one of the same name] happens underneath, should we even be required to notice?
NotFoundError A required file or directory could not be found at the time an operation was processed.
NotReadableErr A required file or directory could be read.
NoModificationAllowedError The user attempted to write to a file or directory which could not be modified due to the state of the underlying filesystem.
PathExistsError The user agent failed to create a file or directory due to the existence of a file or directory with the same path.
QuotaExceededError The operation failed because it would cause the application to exceed its storage quota.
SecurityError
  • A required file was unsafe for access within a Web application
  • Too many calls are being made on filesystem resources
This is a security error code to be used in situations not covered by any other error codes.
TypeMismatchError The user has attempted to look up a file or directory, but the Entry found is of the wrong type [e.g. is a DirectoryEntry when the user requested a FileEntry].

9. Uniformity of interface

In order to make it easy for web app developers to write portable applications that work on all platforms, we enforce certain restrictions and make certain guarantees with respect to paths used in this API.

This section is non-normative.

The implementation must refuse to create any file or directory whose name or existence would violate these rules. The implementation must not accept a noncompliant path where it designates the new name of a file or directory to be moved, copied, or created.

9.1 Case-sensitivity

Paths in this filesystem must be case sensitive and case-preserving.

9.2 Encoding

Implementations must accept any valid UTF-8 sequence as a path segment, so long as it does not include any characters or sequences restricted below. When returning paths or path segments, implementations must return them in the same normalization in which they were presented.

9.3 Naming restrictions

File and directory names must not contain either of the following characters:

There's been discussion on whether backslash '\' (U+005c) should be disallowed or not. In favor of leaving it in is that it's a legal character on some filesystems, and it seems somewhat arbitrary to remove it. Opposed is that it may cause confusion, and in at least some cases complicates implementation.

9.4 Directories

The directory separator is '/' (U+002F).

The character '/', when it is the first character in a path, refers to the root directory.

All absolute paths begin with '/'; no relative paths begin with '/'.

A relative path describes how to get from a particular directory to a file or directory. All methods that accept paths are on DirectoryEntry or DirectoryEntrySync objects; the paths, if relative, are interpreted as being relative to the directories represented by these objects.

An absolute path is a relative path from the root directory, prepended with a '/'.

'.', when used where it is legal to use a directory name, refers to the currently-referenced directory. Thus 'foo/./bar' is equivalent to 'foo/bar', and './foo' is equivalent to 'foo'.

'..', when used where it is legal to use a directory name, refers to the parent of the currently-referenced directory. Thus, 'foo/..' refers to the directory containing 'foo', and '../foo' refers to an element named 'foo' in the parent of the directory on whose DirectoryEntry or DirectoryEntrySync the method receiving the path is being called.

What about path and path segment lengths? Should we limit them at all? It's hard to control the true length of a path, due to renames of parent directories, so we really just want to reject the obviously-too-long; they won't often really come up anyway. We should at least provide minimum lengths for paths and segments.

Should we limit the number of elements in a directory?

A. Acknowledgements

Thanks to Arun Ranganathan for his File API, Opera for theirs, and Robin Berjon both for his work on various file APIs and for ReSpec.

B. References

B.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. 5 January 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-dom-20120105/
[FILE-API-ED]
Arun Ranganathan; Jonas Sicking. File API. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2006/webapi/FileAPI/
[FILE-WRITER-ED]
Eric Uhrhane. File Writer API. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/file-system/file-writer.html
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBWORKERS-ED]
Ian Hickson. Web Workers. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/html5/workers/

B.2 Informative references

No informative references.