Revision 1124415 of File and Directory Entries API

<p>{{DefaultAPISidebar("File System API")}}{{Non-standard_header}}</p>

<p>The File and Directory Entries API simulates a local file system that web apps can navigate within and access files in. You can develop apps which read, write, and create files and/or directories in a virtual, sandboxed file system.</p>

<div class="note">
<p>Because this is a non-standard API, whose specification is not currently on a standards track, it's important to keep in mind that not all browsers implement it, and those that do may implement only small portions of it. Check the {{anch("Browser compatibility")}} section for details.</p>
</div>

<p>Two very similar APIs exist depending on whether you desire asynchronous or synchronous behavior. The synchronous API is indended to be used inside a {{domxref("Worker")}} and will return the values you desire. The asynchronous API will not block and functions and the API will not return values; instead, you will need to supply a callback function to handle the response whenever it arrives.</p>

<div class="warning">
<p>The Firefox implementation of the File and Directory Entries API is very limited; there is no support for creating files. Only for accessing files which are selected by the user in a file {{HTMLElement("input")}} element (see {{domxref("HTMLInputElement")}} as well) or when a file or directory is provided to the Web site or app using <a href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API">drag and drop</a>. Firefox also does not implement the synchronous API. Check the browser compatibility for any part of the API you use carefully, and see <a href="/en-US/docs/Web/API/File_and_Directory_Entries_API/Firefox_support">File and Directory Entries API support in Firefox</a> for more details.</p>
</div>

<h2>Getting access to a file system</h2>

<p>There are two ways to get access to file systems defined in the current specification draft:</p>

<ul>
 <li>When handling a {{event("drop")}} event for drag and drop, you can call {{domxref("DataTransferItem.webkitGetAsEntry()")}} to get the {{domxref("FileSystemEntry")}} for a dropped item. If the result isn't <code>null</code>, then it's a dropped file or directory, and you can use file system calls to work with it.</li>
 <li>The {{domxref("HTMLInputElement.webkitEntries")}} property lets you access the {{domxref("FileSystemFileEntry")}} objects for the currently selected files. If {{domxref("HTMLInputElement.webkitdirectory")}} is <code>true</code>, the {{HTMLElement("input")}} element is instead a directory picker, and you get {{domxref("FileSystemDirectoryEntry")}} objects for each selected directory.</li>
</ul>

<h2 id="Asynchronous_API">Asynchronous API</h2>

<p>The asynchronous API should be used for most operations, to prevent file system accesses from blocking the entire browser if used on the main thread. It includes the following interfaces:</p>

<dl>
 <dt>{{domxref("FileSystem")}}</dt>
 <dd>Represents a file system.</dd>
 <dt>{{domxref("FileSystemEntry")}}</dt>
 <dd>The basic interface representing a single entry in a file system. This is implemented by other interfaces which represent files or directories.</dd>
 <dt>{{domxref("FileSystemFileEntry")}}</dt>
 <dd>Represents a single file in a file system.</dd>
 <dt>{{domxref("FileSystemDirectoryEntry")}}</dt>
 <dd>Represents a single directory in a file system.</dd>
 <dt>{{domxref("FileSystemDirectoryReader")}}</dt>
 <dd>Created by calling {{domxref("FileSystemDirectoryEntry.createReader()")}}, this interface provides the functionality which lets you read the contents of a directory.</dd>
 <dt>{{domxref("FileError")}}</dt>
 <dd>Represents an error which is generated by asynchronous file system calls.</dd>
</dl>

<p>There are also two global functions (which are not part of the specification at this time and are implemented only by Google Chrome). They're available on the {{domxref("Window")}} object and implemented in {{domxref("LocalFileSystem")}}: <code>requestFileSystem()</code> and <code>resolveLocalFileSystemURL()</code>.</p>

<h2 id="Synchronous_API">Synchronous API</h2>

<p>The synchronous API is should only be used in {{domxref("Worker")}}s; these calls block until they're finished executing, and simply return the results instead of using callbacks. Using them on the main thread will block the browser, which is naughty. The interfaces below otherwise mirror the ones from the asynchronous API.</p>

<dl>
 <dt>{{domxref("FileSystemSync")}}</dt>
 <dd>Represents a file system.</dd>
 <dt>{{domxref("FileSystemEntrySync")}}</dt>
 <dd>The basic interface representing a single entry in a file system. This is implemented by other interfaces which represent files or directories.</dd>
 <dt>{{domxref("FileSystemFileEntrySync")}}</dt>
 <dd>Represents a single file in a file system.</dd>
 <dt>{{domxref("FileSystemDirectoryEntrySync")}}</dt>
 <dd>Represents a single directory in a file system.</dd>
 <dt>{{domxref("FileSystemDirectoryReaderSync")}}</dt>
 <dd>Created by calling {{domxref("FileSystemDirectoryEntrySync.createReader()")}}, this interface provides the functionality which lets you read the contents of a directory.</dd>
 <dt>{{domxref("FileException")}}</dt>
 <dd>Represents an error which is generated by synchronous file system calls.</dd>
</dl>

<p>There are also two global functions (which are not part of the specification at this time and are implemented only by Google Chrome). They're available on the {{domxref("Worker")}} object and implemented in {{domxref("LocalFileSystemSync")}}: <code>requestFileSystemSync()</code> and <code>resolveLocalFileSystemSyncURL()</code>.</p>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('File System API')}}</td>
   <td>{{Spec2('File System API')}}</td>
   <td>Draft of proposed API</td>
  </tr>
 </tbody>
</table>

<p>This API has no official W3C or WHATWG specification.</p>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Asynchronous API</td>
   <td>13 {{ property_prefix("webkit") }}</td>
   <td>{{ CompatGeckoDesktop(50) }}<sup>[1]</sup></td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
  <tr>
   <td>Synchronous API</td>
   <td>13 {{ property_prefix("webkit") }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Asynchronous API</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatVersionUnknown }} {{ property_prefix("webkit") }}</td>
   <td>{{ CompatGeckoMobile(50) }}<sup>[1]</sup></td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
  <tr>
   <td>Synchronous API</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatVersionUnknown }} {{ property_prefix("webkit") }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Firefox 50 introduces partial support for the File and Directory Entries API. Be sure to check the compatibility tables for individual interfaces and methods before using them, to ensure that they're supported, before you use them. The API can be disabled by setting the value of the preference <code>dom.webkitBlink.filesystem.enabled</code> to <code>false</code>.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/File_and_Directory_Entries_API/Introduction">Introduction to the File and Directory Entries API</a></li>
 <li><a href="/en-US/docs/Web/API/File_and_Directory_Entries_API/Firefox_support">File and DIrectory Entries API support in Firefox</a></li>
</ul>