OS.File for the main thread

  • Revision slug: JavaScript_OS.File/OS.File_for_the_main_thread
  • Revision title: OS.File for the main thread
  • Revision id: 372485
  • Created:
  • Creator: darkowlzz
  • Is current revision? No
  • Comment

Revision Content

This page details how to use File I/O from the main thread. For other uses of OS.File, please see the corresponding page.

Using OS.File from the main thread

To import OS.File your chrome code, add the following line at the start of your script:

Components.utils.import("resource://gre/modules/osfile.jsm")

Promises

Before using OS.File from the main thread, you need some understanding of the Promise library.

Example: Read the contents of a file as text

The following snippet opens a file "file.txt" and read its contents as a string, using the default encoding (utf-8).

The content is read asynchronously. The result is a promise.

let decoder = new TextDecoder();        // This decoder can be reused for several reads
let promise = OS.File.read("file.txt"); // Read the complete file as an array
promise = promise.then(
  function onSuccess(array) {
    return decoder.decode(array);        // Convert this array to a text
  }
);

This example requires Firefox 18 or a more recent version

Example: Write a string to a file

The following snippet writes the text "This is some text" to a string "file.txt", using the default encoding (utf-8). It uses an atomic write to ensure that the file is not modified if, for some reason, the write cannot complete (typically because the computer is turned off, the battery runs out or the application is stopped).

let encoder = new TextEncoder();                                   // This encoder can be reused for several writes
let array = encoder.encode("This is some text");                   // Convert the text to an array
let promise = OS.File.writeAtomic("file.txt", array,               // Write the array atomically to "file.txt", using as temporary
    {tmpPath: "file.txt.tmp"});                                    // buffer "file.txt.tmp".

The following variant does the same thing but will fail if "file.txt" already exists:

let encoder = new TextEncoder();                                   // This encoder can be reused for several writes
let array = encoder.encode("This is some text");                   // Convert the text to an array
let promise = OS.File.writeAtomic("file.txt", array,               // Write the array atomically to "file.txt", using as temporary
    {tmpPath: "file.txt.tmp", noOverwrite: true});                 // buffer "file.txt.tmp".

These examples require Firefox 19 or a more recent version

Example: Rename a file

The following snippet renames file "oldname.txt" to "newname.txt". Note that this is generally much faster than copying "oldname.txt" to "newname.txt" and then removing "oldname.txt".

let promise = OS.File.rename("oldname.txt", "newname.txt");

This example requires Firefox 16 or a more recent version

Example: Copy a file

The following snippet copies file "oldname.txt" to "newname.txt". On most operating systems, this operation is handled directly by the operating system itself, which makes it as fast as possible.

let promise = OS.File.copy("oldname.txt", "newname.txt");

This example requires Firefox 16 or a more recent version

Example: Path manipulation

The following snippet obtains the path to file "sessionstore.js", contained in the user's profile directory.

let sessionstore = OS.Path.join(OS.Constants.Path.profileDir, "sessionstore.js");
   // Under Linux, this is generally "$HOME/.firefox/Profiles/$PROFILENAME/sessionstore.js"
   // Under MacOS, this is generally "$HOME/Library/Application Support/Firefox/$PROFILENAME/sessionstore.js"
   // Under Windows, this is generally "C:\Users\%USERNAME%\AppData\Roaming\Mozilla\Firefox\Profiles\%PROFILENAME%"
   // etc.

Example: Determine if a file is a directory

The following snippet determines if some path represents a file or a directory:

let promise = OS.File.stat(somePath);
promise = promise.then(
  function onSuccess(stat) {
    if (stat.isDir) {
      // The path represents a directory
    } else {
      // The path represents a file, not a directory
    }
  },
  function onFailure(reason) {
    if (reason instanceof OS.File.Error && reason.becauseNoSuchFile) {
      // The file does not exist
    } else {
      // Some other error
      throw reason;
    }
  }
);

Example: copy a file by chunks

The following snippet writes a (presumably large) buffer by chunks. Note that this snippet is useful as demonstration of complex asynchronous programming with OS.File – in most cases, function OS.File.writeAtomic is a better choice.

let writeStream = function writeStream(data, outFile, chunkSize) {
  let view = new Uint8Array(data);

  let loop = function loop(pos) {                                         // Define a recursive asynchronous loop.
    if (pos <= view.byteLength) {  // Note: Should this be pos >= view.byteLength ?
      return Promise.resolve(true);                                       // Loop end.
    }
    let promise = file.write(view.subarray(pos, chunkSize));              // Write a subset of |data|
    return promise.then(function onSuccess(bytes) {
      return loop(pos + bytes);                                           // ... and loop.
    });
  };

  let promise = loop(0);                                                  // Enter the loop.

  promise = promise.then(function onSuccess() {                           // Once loop is complete, finalize.
    file.close();
  }, function onError(reason) {
    file.close();
    throw reason;
  });
  return promise;
}

Or a variant using Task.js (or at least the subset already present on mozilla-central):

let writeStream = function writeStream(data, outFile, chunkSize) {
  return Task.spawn(function() {
    let view = new Uint8Array(data);
    let pos = 0;
    while (pos < view.byteLength) {
      pos += yield outFile.write(view.subarray(pos, chunkSize));
    }
    outFile.close();
  }).then(
    null,
    function onFailure(reason) {
      outFile.close();
      throw reason;
    }
  );
}

Global object OS.File

Method overview

promise<File> open(in string path, [optional] in object mode, [optional] in object options);
promise<void> copy(in string sourcePath, in string destPath, [optional] in object options);
promise<bool> exists(in string path);
promise<string> getCurrentDirectory();
promise<void> makeDir(in string path, [optional] in object options);
promise<void> move(in string sourcePath, in string destPath);
promise<Uint8Array> read(in string path, [optional] in object options);
promise<void> remove(in string path);
promise<void> removeEmptyDir(in string path);
promise<void> setCurrentDirectory(in string path);
promise<File.Info> stat(in string path, [optional] in object options);
promise<void> writeAtomic(in string path, in ArrayView data, in object options);

Methods

OS.File.open()

Use method OS.File.open() to open a file.

promise<File> open(
  in string path,
  [optional] in object mode,
  [optional] in object options
)
Arguments
path
The full native name of the file to open.
mode
The opening mode for the file, as an object that may contain a subset of the following fields:
read
If true, the file will be opened for reading. Depending on other fields, it may also be opened for writing.
write
If true, the file will be opened for writing. Depending on other fields, it may also be opened for reading. Unless specified otherwise, the file will be opened for appending.
truncate
If true, the file will be opened for writing. If the file does not exist, it will be created. If the file exists, its contents will be removed. Cannot be used with create.
create
If true, file will be opened for writing. The file must not exist. If the file already exists, throw an error. Cannot be used with truncate or existing.
existing
If true, the file must already exist. If the file does not exist, throw an error. Cannot be used with create.
options
Platform-specific options for opening the file. For advanced users only. Most users will never have need of these options. To specify options, pass an object that may contain some of the following flags:
unixFlags
(ignored under non-Unix platforms) If specified, file opening flags, as per libc function open. If unspecified, build these flags from the contents of mode. You can build these flags from values OS.Constants.libc.O_*.
unixMode
(ignored under non-Unix platforms) If specified, file creation mode, as per libc function open. If unspecified, files are created with a default mode of 0600 (file is private to the user, the user can read and write). You can build this mode from values OS.Constants.libc.S_I*.
winShare
(ignored under non-Windows platforms) If specified, a sharing policy, as per Windows function CreateFile. If unspecified, files are opened with a default sharing policy (file is not protected against being read/written/removed by another process or another use in the same process). You can build this policy from constants OS.Constants.Win.FILE_SHARE_*.
winSecurity
(ignored under non-Windows platforms) If specified, a security policy, as per Windows function CreateFile. If unspecified, no security attributes.
winAccess
(ignored under non-Windows platforms) If specified, access mode, as per Windows function CreateFile. This also requires option winDisposition and this replaces argument mode. If unspecified, value is built from mode.
winDisposition
(ignored under non-Windows platforms) If specified, disposition mode, as per Windows function CreateFile. This also requires option winAccess and this replaces argument mode. If unspecified, value is built from mode.
Promise resolves to

An instance of OS.File representing the expected file.

Note that the operating system limits the number of files that can be opened simultaneously by one process, so do not forget to close that file once you have finished it, to ensure that you are not blocking the rest of the process.

The runtime will also do its best to eventually close files that are not used, but you should not rely upon this, as it can depend on many factors that you cannot control.

OS.File.copy()

Copy a file.

void copy(
  in string sourcePath,
  in string destPath
  [optional] in object options)
throws OS.File.Error
Arguments
sourcePath
The full path of the file to copy. At the time of this writing, this function does not copy directories.
destPath
The full path of the destination. Note that this is not a directory but a file.
options
An optional object used to control the behavior of this function. You may pass an object with a subset of the following fields:
noOverwrite
If destPath already exists, do not overwrite it, but rather launch an exception.
Promise can be rejected with
OS.File.Error
In case of any error, in particular if the file does not exist.
Performance notes
  • To avoid erasing the destination file, it is much faster to use option noOverwrite than to check manually whether the file exists.
  • This operation is OS-optimized under MacOS X (native operation copyfile), Linux/Android (native operation splice) and Windows (native operation CopyFile).

OS.File.exists()

Determine whether a file exists

promise<bool> exists(
  in string path
)
Arguments
path
The name of the file
Promise resolves to

true if the file exists, false otherwise

Performance note
 

For the sake of performance, you should avoid this function whenever possible. For instance, rather than calling exists() to determine if a directory should be created with makeDir, you should rather create the directory with makeDir and catch the error if the directory exists. This will ensure that you only need to perform one I/O operation rather than two.

OS.File.getCurrentDirectory()

Return the current directory

promise<string> getCurrentDirectory()
Promise resolves to

The path to the current directory.

OS.File.makeDir()

Create a new directory

promise<void> makeDir(
  in string path,
  [optional] in object options
) throws OS.File.Error
Arguments
path
The full name of the directory to create.
options
Platform-specific options for creating the directory. For advanced users only. Most users will never have need of these options. To specify options, pass an object that may contain some of the following flags:
unixMode
(ignored under non-Unix platforms) If specified, file creation mode, as per libc function mkdir. If unspecified, directories are created with a default mode of 0600 (file is private to the user, the user can read and write). You can build this mode from values OS.Constants.libc.S_I*.
winSecurity
(ignored under non-Windows platforms) If specified, a security policy, as per Windows function CreateDirectory. If unspecified, no security attributes.

OS.File.move()

Move a file.

promise<void> move(
  in string sourcePath,
  in string destPath
  [optional] in object options
)
Arguments
sourcePath
The full path of the file to move. At the time of this writing, the behavior of this function is unspecified if sourcePath is a directory.
destPath
The full path of the destination. At the time of this writing, the behavior of this function is unspecified if destPath is a directory.
options
An optional object used to control the behavior of this function. You may pass an object with a subset of the following fields:
noOverwrite
If destPath already exists, do not overwrite it, but rather launch an exception.
Promise can be rejected with
OS.File.Error
In case of any error, in particular if the file does not exist.
Performance note: This operation is OS-optimized under MacOS X, Linux/Android and Windows.

OS.File.read()

Read the contents of a file

promise<Uint8Array> read(
  in string path,
  [optional] in number bytes
)
Arguments
path
The full path to the file to read.
bytes
The number of bytes to read. If unspecified, read the complete file.
Promise resolves to

An array holding bytes bytes (or less if the file did not contain as many bytes).

Promise can be rejected with
OS.File.Error
In case of any error, in particular if the file does not exist or if the process does not have the authorization to read it.

OS.File.remove()

Remove an existing file.

promise<void> remove(
  in string path
  [optional] in object options
)
Arguments
path
A string representing the name of the file to remove. At the time of this writing, this function does not remove directories.
options
Ignored for the moment.
Promise can be rejected with
OS.File.Error
In case of any error, in particular if the file does not exist.

OS.File.removeEmptyDir()

Remove an empty directory

promise<void> removeEmptyDir(
  in string path
)
Arguments
path
The complete path to the directory.
Promise can be rejected with
OS.File.Error
In case of any error, in particular if the file does not exist.

OS.File.setCurrentDirectory()

Change the current directory of the process.

Use with extreme caution

This API may be useful for application developers but should be avoided by add-ons, as it changes the state of the complete application.

promise<void> setCurrentDirectory(
  in string path
)
Arguments
path
The complete path to use as current directory.
Promise can be rejected with
OS.File.Error
In case of any error, in particular if the path does not represent an existing directory.

OS.File.stat()

Obtain information about a file, such as size, creation date, etc.

promise<File.Info> stat(
  in string path
)
Arguments
path
The complete path to the file.
Promise resolves to

An instance of File.Info holding information about a file.

Promise can be rejected with
OS.File.Error
In case of any error, in particular if the path does not represent an existing file.
 

Performance note

If the file is already opened, calling method stat() is much faster than calling function OS.File.stat().

 

OS.File.writeAtomic()

Write data to a file. Data is first written to a temporary file, then flushed, then the temporary file is used to overwrite the destination file. This makes it extremely unlikely that the destination file can be corrupted during the call to this function by battery failure, the process being stopped or any other such incident. Note that it is generally not possible to provide a 100% guarantee of such properties.

promise<void> writeAtomic(
  in string path,
  in ArrayBufferView data,
  in object options
)
Arguments
path
The full path to the destination file.
data
An ArrayBufferView holding the data to write.
options
An object that may contain the following fields
tmpPath
The full path to a file that may be used as a temporary buffer. This file must be on the same device as path. In case of doubt, path + ".tmp" is generally a good value for tmpPath.
noOverwrite
If specified and true, and if path already exists, this function will throw an error without overwriting path.

At the time of this writing, option tmpPath is required. Future versions will ensure that the function may work even without this argument.

Use with caution

Modifying the contents of data before the operation is complete is a very bad idea.

Promise can be rejected with
OS.File.Error
In case of any error, in particular if the destination file cannot be overwritten, or if tmpPath is not on the same device as path.

Instances of OS.File

To obtain an instance of OS.File, use function OS.File.open.

Methods overview

promise<void> close()
promise<void> flush()
promise<number> getPosition()
promise<number> read([optional] in number bytes)
promise<number> readTo(out ArrayBufferView dest, [optional] in object options)
promise<void> setPosition(in number bytes)
promise<File.Info> stat()
promise<number> write(in ArrayBufferView source, [optional] in object options)
fd (platform-specific) (read-only) For advanced users only. A low-level opaque data structure holding the system handle for the file. Under Windows, this is a file HANDLE and under Unix, this is a file descriptor. Use this with the Platform-Specific Low-Level API.

Methods

close()

Close a file and release any associated resource.

Once the file is closed, any attempt to call methods of the file object will raise an error.

Note that the operating system limits the number of files that can be opened simultaneously by one process, so do not forget to close that file once you have finished it to make sure that you are not blocking the rest of the process.
promise<void> close()

flush()

Flushes the file's internal buffers, ensuring that all data still in these buffers is now written to disk.

promise<void> flush()

getPosition()

Return the current position in the file.

promise<number> getPosition()
Promise resolves to

The current position in the file, as a number of bytes from the start.

Promise can be rejected with
OS.File.Error
If the file is closed.

read()

Read bytes from this file to a new buffer. Bytes are read from the current position in the file and the position is advanced accordingly.

promise<UInt8Array> read(
  [optional] in number bytes
)
Arguments
bytes
If specified, read bytes bytes, or less if the file does not contain that many bytes. If unspecified, read all the remaining bytes from this file.
Promise resolves to

An array containing the bytes read.

If you need to convert the result of this function to a string, you may do so through by using the StringEncoding API.
Promise can be rejected with
OS.File.Error
In case of I/O error.

readTo()

Read bytes from the file to an existing array. Bytes are read from the current position in the file and the position is advanced accordingly.

promise<number> readTo(
  out ArrayBufferView dest,
  [optional] in object options
)
Arguments
dest
The buffer in which to store the bytes.
options
An object that may contain some of the following fields
bytes
An upper bound to the number of bytes to read from the file. If unspecified, read up to dest.byteLength bytes. If specified, this must be less than dest.byteLength.
Promise resolves to

The number of bytes effectively read from the file.

Promise can be rejected with
OS.File.Error
In case of any I/O error.
TypeError
If options.bytes is specified and is larger than dest.byteLength.

setPosition()

Change the current position in the file.

promise<void> setPosition(
  in number offset,
  in object origin
)
Arguments
  • OS.File.POS_START (bytes are counted from the start of the file);
  • OS.File.POS_CUR (bytes are counted from the current position in the file);
  • OS.File.POS_END (bytes are counted from the end of the file).
offset
The new position, as a number of bytes from the origin.
origin
One of the following:
Promise can be rejected with
OS.File.Error
In case of any error, in particular if the new position is before the start of the file, or if the file is closed.

stat()

Obtain information about the file, such as size, creation date, etc.

promise<File.Info> stat()
Promise resolves to

An instance of File.Info holding information about the file.

Promise can be rejected with
OS.File.Error
In case of any error, in particular if the file is closed.

write()

Write bytes from a buffer to this file.

Note that, by default, this function may perform several I/O operations to ensure that the buffer is fully written.

promise<number> write(
  in ArrayBufferView source
  [optional] in object options
)
Arguments
source
The array in which the the bytes are stored.
options
An object that may contain some of the following fields
bytes
An upper bound to the number of bytes to write to the file. If unspecified, write up to source.byteLength bytes. If specified, this must be less than source.byteLength.
Promise resolves to

The number of bytes effectively written to the file.

Promise can be rejected with
OS.File.Error
In case of any I/O error.
TypeError
If options.bytes is specified and is larger than source.byteLength.

Revision Source

<p>This page details how to use File I/O from the main thread. For other uses of OS.File, please see <a href="/en-US/docs/JavaScript_OS.File" title="/en-US/docs/JavaScript_OS.File">the corresponding page</a>.</p>
<h2 id="Using_OS.File_from_the_main_thread">Using OS.File from the main thread</h2>
<p>To import OS.File your chrome code, add the following line at the start of your script:</p>
<pre>
<code class="brush: js">Components.utils.import("<a href="resource://gre/modules/osfile.jsm" rel="freelink">resource://gre/modules/osfile.jsm"</a>)</code></pre>
<h3 id="Promises">Promises</h3>
<p>Before using OS.File from the main thread, you need some understanding of the <a href="https://addons.mozilla.org/en-US/developers/docs/sdk/1.9/packages/api-utils/promise.html" title="https://addons.mozilla.org/en-US/developers/docs/sdk/1.9/packages/api-utils/promise.html">Promise library</a>.</p>
<h3 id="Example.3A_Read_the_contents_of_a_file_as_text">Example: Read the contents of a file as text</h3>
<p>The following snippet opens a file "file.txt" and read its contents as a string, using the default encoding (utf-8).</p>
<p>The content is read asynchronously. The result is a <a href="https://addons.mozilla.org/en-US/developers/docs/sdk/1.9/packages/api-utils/promise.html" title="https://addons.mozilla.org/en-US/developers/docs/sdk/1.9/packages/api-utils/promise.html">promise</a>.</p>
<pre class="brush: js">
let decoder = new TextDecoder();        // This decoder can be reused for several reads
let promise = OS.File.read("file.txt"); // Read the complete file as an array
promise = promise.then(
  function onSuccess(array) {
    return decoder.decode(array);        // Convert this array to a text
  }
);
</pre>
<div class="note">
  <p>This example requires Firefox 18 or a more recent version</p>
</div>
<h3 id="Example.3A_Write_a_string_to_a_file">Example: Write a string to a file</h3>
<p>The following snippet writes the text "This is some text" to a string "file.txt", using the default encoding (utf-8). It uses an atomic write to ensure that the file is not modified if, for some reason, the write cannot complete (typically because the computer is turned off, the battery runs out or the application is stopped).</p>
<pre class="brush: js">
let encoder = new TextEncoder();                                   // This encoder can be reused for several writes
let array = encoder.encode("This is some text");                   // Convert the text to an array
let promise = OS.File.writeAtomic("file.txt", array,               // Write the array atomically to "file.txt", using as temporary
    {tmpPath: "file.txt.tmp"});                                    // buffer "file.txt.tmp".

</pre>
<p>The following variant does the same thing but will fail if "file.txt" already exists:</p>
<pre class="brush: js">
let encoder = new TextEncoder();                                   // This encoder can be reused for several writes
let array = encoder.encode("This is some text");                   // Convert the text to an array
let promise = OS.File.writeAtomic("file.txt", array,               // Write the array atomically to "file.txt", using as temporary
    {tmpPath: "file.txt.tmp", noOverwrite: true});                 // buffer "file.txt.tmp".

</pre>
<div class="note">
  <p>These examples require Firefox 19 or a more recent version</p>
</div>
<h3 id="Example.3A_Rename_a_file">Example: Rename a file</h3>
<p>The following snippet renames file "oldname.txt" to "newname.txt". Note that this is generally much faster than copying "oldname.txt" to "newname.txt" and then removing "oldname.txt".</p>
<pre class="brush: js">
let promise = OS.File.rename("oldname.txt", "newname.txt");</pre>
<div class="note">
  <p>This example requires Firefox 16 or a more recent version</p>
</div>
<h3 id="Example.3A_Copy_a_file">Example: Copy a file</h3>
<p>The following snippet copies file "oldname.txt" to "newname.txt". On most operating systems, this operation is handled directly by the operating system itself, which makes it as fast as possible.</p>
<pre class="brush: js">
let promise = OS.File.copy("oldname.txt", "newname.txt");</pre>
<div class="note">
  <p>This example requires Firefox 16 or a more recent version</p>
</div>
<h3 id="Example.3A_Path_manipulation">Example: Path manipulation</h3>
<p>The following snippet obtains the path to file "sessionstore.js", contained in the user's profile directory.</p>
<pre class="brush: js">
let sessionstore = OS.Path.join(OS.Constants.Path.profileDir, "sessionstore.js");
   // Under Linux, this is generally "$HOME/.firefox/Profiles/$PROFILENAME/sessionstore.js"
   // Under MacOS, this is generally "$HOME/Library/Application Support/Firefox/$PROFILENAME/sessionstore.js"
   // Under Windows, this is generally "C:\Users\%USERNAME%\AppData\Roaming\Mozilla\Firefox\Profiles\%PROFILENAME%"
   // etc.

</pre>
<h3 id="Example.3A_Determine_if_a_file_is_a_directory">Example: Determine if a file is a directory</h3>
<p>The following snippet determines if some path represents a file or a directory:</p>
<pre class="brush: js">
let promise = OS.File.stat(somePath);
promise = promise.then(
  function onSuccess(stat) {
    if (stat.isDir) {
      // The path represents a directory
    } else {
      // The path represents a file, not a directory
    }
  },
  function onFailure(reason) {
    if (reason instanceof OS.File.Error &amp;&amp; reason.becauseNoSuchFile) {
      // The file does not exist
    } else {
      // Some other error
      throw reason;
    }
  }
);
</pre>
<h3 id="Example.3A_copy_a_file_by_chunks">Example: copy a file by chunks</h3>
<p>The following snippet writes a (presumably large) buffer by chunks. Note that this snippet is useful as demonstration of complex asynchronous programming with OS.File – in most cases, function <code>OS.File.writeAtomic</code> is a better choice.</p>
<pre class="brush: js">
let writeStream = function writeStream(data, outFile, chunkSize) {
  let view = new Uint8Array(data);

  let loop = function loop(pos) {                                         // Define a recursive asynchronous loop.
    if (pos &lt;= view.byteLength) {  // Note: Should this be pos &gt;= view.byteLength ?
      return Promise.resolve(true);                                       // Loop end.
    }
    let promise = file.write(view.subarray(pos, chunkSize));              // Write a subset of |data|
    return promise.then(function onSuccess(bytes) {
      return loop(pos + bytes);                                           // ... and loop.
    });
  };

  let promise = loop(0);                                                  // Enter the loop.

  promise = promise.then(function onSuccess() {                           // Once loop is complete, finalize.
    file.close();
  }, function onError(reason) {
    file.close();
    throw reason;
  });
  return promise;
}
</pre>
<p>Or a variant using <a class="external" href="http://taskjs.org/" title="http://taskjs.org/">Task.js</a> (or at least <a class="external" href="http://dxr.mozilla.org/mozilla-central/toolkit/content/Task.jsm.html" title="http://dxr.mozilla.org/mozilla-central/toolkit/content/Task.jsm.html">the subset already present on mozilla-central</a>):</p>
<pre class="brush: js">
let writeStream = function writeStream(data, outFile, chunkSize) {
  return Task.spawn(function() {
    let view = new Uint8Array(data);
    let pos = 0;
    while (pos &lt; view.byteLength) {
      pos += yield outFile.write(view.subarray(pos, chunkSize));
    }
    outFile.close();
  }).then(
    null,
    function onFailure(reason) {
      outFile.close();
      throw reason;
    }
  );
}
</pre>
<h2 id="Global_object_OS.File">Global object OS.File</h2>
<h3 id="Method_overview">Method overview</h3>
<table>
  <tbody>
    <tr>
      <td>promise&lt;File&gt; <a href="#OS.File.open" title="#OS.File.open">open</a>(in string path, [optional] in object mode, [optional] in object options);</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.copy" title="#OS.File.copy">copy</a>(in string sourcePath, in string destPath, [optional] in object options);</td>
    </tr>
    <tr>
      <td>promise&lt;bool&gt; <a href="#OS.File.exists" title="#OS.File.exists">exists</a>(in string path);</td>
    </tr>
    <tr>
      <td>promise&lt;string&gt; <a href="#OS.File.getCurrentDirectory" title="#OS.File.getCurrentDirectory">getCurrentDirectory</a>();</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.makeDir" title="#OS.File.makeDir">makeDir</a>(in string path, [optional] in object options);</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.move" title="#OS.File.move">move</a>(in string sourcePath, in string destPath);</td>
    </tr>
    <tr>
      <td>promise&lt;Uint8Array&gt; <a href="#OS.File.read" title="#OS.File.read">read</a>(in string path, [optional] in object options);</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.remove" title="#OS.File.remove">remove</a>(in string path);</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.removeEmptyDir" title="#OS.File.removeEmptyDir">removeEmptyDir</a>(in string path);</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.setCurrentDirectory" title="#OS.File.setCurrentDirectory">setCurrentDirectory</a>(in string path);</td>
    </tr>
    <tr>
      <td>promise&lt;<a href="/en-US/docs/JavaScript_OS.File/OS.File.Info" title="/en-US/docs/JavaScript_OS.File/OS.File.Info">File.Info</a>&gt; <a href="#OS.File.stat" title="#OS.File.stat">stat</a>(in string path, [optional] in object options);</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.writeAtomic" title="#OS.File.writeAtomic">writeAtomic</a>(in string path, in ArrayView data, in object options);</td>
    </tr>
  </tbody>
</table>
<h3 id="Methods">Methods</h3>
<h4 id="OS.File.open()">OS.File.open()<a name="OS.File.open"></a></h4>
<p>Use method <code>OS.File.open()</code> to open a file.</p>
<pre class="brush:js;">
promise&lt;File&gt; open(
  in string path,
  [optional] in object mode,
  [optional] in object options
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The full native name of the file to open.</dd>
  <dt>
    mode</dt>
  <dd>
    The opening mode for the file, as an object that may contain a subset of the following fields:
    <dl>
      <dt>
        read</dt>
      <dd>
        If <code>true</code>, the file will be opened for reading. Depending on other fields, it may also be opened for writing.</dd>
      <dt>
        write</dt>
      <dd>
        If <code>true</code>, the file will be opened for writing. Depending on other fields, it may also be opened for reading. Unless specified otherwise, the file will be opened for appending.</dd>
      <dt>
        truncate</dt>
      <dd>
        If <code>true</code>, the file will be opened for writing. If the file does not exist, it will be created. If the file exists, its contents will be removed. Cannot be used with <code>create</code>.</dd>
      <dt>
        create</dt>
      <dd>
        If <code>true</code>, file will be opened for writing. The file must not exist. If the file already exists, throw an error. Cannot be used with <code>truncate</code> or <code>existing</code>.</dd>
      <dt>
        existing</dt>
      <dd>
        If <code>true</code>, the file must already exist. If the file does not exist, throw an error. Cannot be used with <code>create</code>.</dd>
    </dl>
  </dd>
  <dt>
    options</dt>
  <dd>
    Platform-specific options for opening the file. <strong>For advanced users only. Most users will never have need of these options.</strong> To specify options, pass an object that may contain some of the following flags:
    <dl>
      <dt>
        unixFlags</dt>
      <dd>
        (ignored under non-Unix platforms) If specified, file opening flags, as per libc function <code>open</code>. If unspecified, build these flags from the contents of <code>mode</code>. You can build these flags from values <a href="/en/JavaScript_OS.Constants#libc_opening_files" title="en/JavaScript_OS.Constants#libc_opening_files">OS.Constants.libc.O_*</a>.</dd>
      <dt>
        unixMode</dt>
      <dd>
        (ignored under non-Unix platforms) If specified, file creation mode, as per libc function <code>open</code>. If unspecified, files are created with a default mode of 0600 (file is private to the user, the user can read and write). You can build this mode from values <a href="/en/JavaScript_OS.Constants#libc_opening_files" title="en/JavaScript_OS.Constants#libc_opening_files"><code>OS.Constants.libc.S_I*</code></a>.</dd>
      <dt>
        winShare</dt>
      <dd>
        (ignored under non-Windows platforms) If specified, a sharing policy, as per Windows function <code>CreateFile</code>. If unspecified, files are opened with a default sharing policy (file is not protected against being read/written/removed by another process or another use in the same process). You can build this policy from constants OS.Constants.Win.FILE_SHARE_*.</dd>
      <dt>
        winSecurity</dt>
      <dd>
        (ignored under non-Windows platforms) If specified, a security policy, as per Windows function <code>CreateFile</code>. If unspecified, no security attributes.</dd>
      <dt>
        winAccess</dt>
      <dd>
        (ignored under non-Windows platforms) If specified, access mode, as per Windows function <code>CreateFile</code>. This also requires option <code>winDisposition</code> and this replaces argument <code>mode</code>. If unspecified, value is built from <code>mode</code>.</dd>
      <dt>
        winDisposition</dt>
      <dd>
        (ignored under non-Windows platforms) If specified, disposition mode, as per Windows function <code>CreateFile</code>. This also requires option <code>winAccess</code> and this replaces argument <code>mode</code>. If unspecified, value is built from <code>mode</code>.</dd>
    </dl>
  </dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>An instance of <code>OS.File</code> representing the expected file.</p>
<div class="warning">
  Note that the operating system limits the number of files that can be opened simultaneously by one process, so do not forget to <a href="/OS.File.prototype.close" title="OS.File.prototype.close"><code>close</code></a> that file once you have finished it, to ensure that you are not blocking the rest of the process.</div>
<p>The runtime will also do its best to eventually close files that are not used, but you should not rely upon this, as it can depend on many factors that you cannot control.</p>
<h4 id="OS.File.copy()">OS.File.copy()<a name="OS.File.copy"></a></h4>
<p>Copy a file.</p>
<pre>
void copy(
  in string sourcePath,
  in string destPath
  [optional] in object options)
throws <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a>
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    sourcePath</dt>
  <dd>
    The full path of the file to copy. At the time of this writing, this function does <strong>not</strong> copy directories.</dd>
  <dt>
    destPath</dt>
  <dd>
    The full path of the destination. Note that this is not a directory but a file.</dd>
  <dt>
    options</dt>
  <dd>
    An optional object used to control the behavior of this function. You may pass an object with a subset of the following fields:</dd>
  <dt style="margin-left: 40px;">
    noOverwrite</dt>
  <dd style="margin-left: 40px;">
    If <code>destPath</code> already exists, do not overwrite it, but rather launch an exception.</dd>
</dl>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the file does not exist.</dd>
</dl>
<div class="note">
  <strong>Performance notes</strong>
  <ul>
    <li>To avoid erasing the destination file, it is much faster to use option <code>noOverwrite</code> than to check manually whether the file exists.</li>
    <li>This operation is OS-optimized under MacOS X (native operation <code>copyfile</code>), Linux/Android (native operation <code>splice</code>) and Windows (native operation <code>CopyFile</code>).</li>
  </ul>
</div>
<h4 id="OS.File.exists()">OS.File.exists()<a name="OS.File.exists"></a></h4>
<p>Determine whether a file exists</p>
<pre class="brush: js">
promise&lt;bool&gt; exists(
  in string path
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The name of the file</dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>true if the file exists, false otherwise</p>
<div class="note">
  <p><strong>Performance note</strong><br />
    &nbsp;</p>
  <p>For the sake of performance, you should avoid this function whenever possible. For instance, rather than calling exists() to determine if a directory should be created with makeDir, you should rather create the directory with makeDir and catch the error if the directory exists. This will ensure that you only need to perform one I/O operation rather than two.</p>
</div>
<h4 id="OS.File.getCurrentDirectory()">OS.File.getCurrentDirectory()<a name="OS.File.getCurrentDirectory"></a></h4>
<p>Return the current directory</p>
<pre class="brush: js">
promise&lt;string&gt; getCurrentDirectory()</pre>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>The path to the current directory.</p>
<h4 id="OS.File.makeDir()">OS.File.makeDir()<a name="OS.File.makeDir"></a></h4>
<p>Create a new directory</p>
<pre class="brush: js">
promise&lt;void&gt; makeDir(
  in string path,
  [optional] in object options
) throws <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The full name of the directory to create.</dd>
  <dt>
    options</dt>
  <dd>
    Platform-specific options for creating the directory. <strong>For advanced users only. Most users will never have need of these options.</strong> To specify options, pass an object that may contain some of the following flags:</dd>
  <dt style="margin-left: 40px;">
    unixMode</dt>
  <dd style="margin-left: 40px;">
    (ignored under non-Unix platforms) If specified, file creation mode, as per libc function mkdir. If unspecified, directories are created with a default mode of 0600 (file is private to the user, the user can read and write). You can build this mode from values <a href="/en/JavaScript_OS.Constants#libc_opening_files" title="en/JavaScript_OS.Constants#libc_opening_files"><code>OS.Constants.libc.S_I*</code></a>.</dd>
  <dt style="margin-left: 40px;">
    winSecurity</dt>
  <dd style="margin-left: 40px;">
    (ignored under non-Windows platforms) If specified, a security policy, as per Windows function <code>CreateDirectory</code>. If unspecified, no security attributes.</dd>
</dl>
<h4 id="OS.File.move()">OS.File.move()<a name="OS.File.move"></a></h4>
<p>Move a file.</p>
<pre>
promise&lt;void&gt; move(
  in string sourcePath,
  in string destPath
  [optional] in object options
)</pre>
<h5 id="Arguments"><span>Arguments</span></h5>
<dl>
  <dt>
    sourcePath</dt>
  <dd>
    The full path of the file to move. At the time of this writing, the behavior of this function is unspecified if <code>sourcePath</code> is a directory.</dd>
  <dt>
    destPath</dt>
  <dd>
    The full path of the destination. At the time of this writing, the behavior of this function is unspecified if <code>destPath</code> is a directory.</dd>
  <dt>
    options</dt>
  <dd>
    An optional object used to control the behavior of this function. You may pass an object with a subset of the following fields:
    <dl>
      <dt>
        noOverwrite</dt>
      <dd>
        If <code>destPath</code> already exists, do not overwrite it, but rather launch an exception.</dd>
    </dl>
  </dd>
</dl>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the file does not exist.</dd>
</dl>
<div class="note">
  Performance note: This operation is OS-optimized under MacOS X, Linux/Android and Windows.</div>
<h4 id="OS.File.read()">OS.File.read()<a name="OS.File.read"></a></h4>
<p>Read the contents of a file</p>
<pre class="brush: js">
promise&lt;Uint8Array&gt; read(
  in string path,
  [optional] in number bytes
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The full path to the file to read.</dd>
  <dt>
    bytes</dt>
  <dd>
    The number of bytes to read. If unspecified, read the complete file.</dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>An array holding bytes bytes (or less if the file did not contain as many bytes).</p>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the file does not exist or if the process does not have the authorization to read it.</dd>
</dl>
<h4 id="OS.File.remove()">OS.File.remove()<a name="OS.File.remove"></a></h4>
<p>Remove an existing file.</p>
<pre>
promise&lt;void&gt; remove(
  in string path
  [optional] in object options
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    A string representing the name of the file to remove. At the time of this writing, this function does <strong>not</strong> remove directories.</dd>
  <dt>
    options</dt>
  <dd>
    Ignored for the moment.</dd>
</dl>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the file does not exist.</dd>
</dl>
<h4 id="OS.File.removeEmptyDir()">OS.File.removeEmptyDir()<a name="OS.File.removeEmptyDir"></a></h4>
<p>Remove an empty directory</p>
<pre class="brush: js">
promise&lt;void&gt; removeEmptyDir(
  in string path
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The complete path to the directory.</dd>
</dl>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the file does not exist.</dd>
</dl>
<h4 id="OS.File.setCurrentDirectory()">OS.File.setCurrentDirectory()<a name="OS.File.setCurrentDirectory"></a></h4>
<p>Change the current directory of the process.</p>
<div class="warning">
  <p><strong>Use with extreme caution</strong></p>
  <p>This API may be useful for application developers but should be avoided by add-ons, as it changes the state of the complete application.</p>
</div>
<pre class="brush: js">
promise&lt;void&gt; setCurrentDirectory(
  in string path
)</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The complete path to use as current directory.</dd>
</dl>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the path does not represent an existing directory.</dd>
</dl>
<h4 id="OS.File.stat()">OS.File.stat()<a name="OS.File.stat"></a></h4>
<p>Obtain information about a file, such as size, creation date, etc.</p>
<pre class="brush: js">
promise&lt;<a href="/en-US/docs/JavaScript_OS.File/OS.File.Info" title="/en-US/docs/JavaScript_OS.File/OS.File.Info">File.Info</a>&gt; stat(
  in string path
)</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The complete path to the file.</dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p class="brush: js">An instance of <a href="/en-US/docs/JavaScript_OS.File/OS.File.Info" title="/en-US/docs/JavaScript_OS.File/OS.File.Info">File.Info</a> holding information about a file.</p>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the path does not represent an existing file.</dd>
  <dt>
    &nbsp;</dt>
</dl>
<div class="note">
  <p><strong>Performance note</strong></p>
  <p>If the file is already opened, calling <em>method</em> <a href="#OS.File.prototype.stat" title="#OS.File.prototype.stat"><code>stat()</code></a> is much faster than calling <em>function</em> <a href="#OS.File.stat" title="#OS.File.stat">OS.File.stat()</a>.</p>
</div>
<p>&nbsp;</p>
<h4 id="OS.File.writeAtomic()">OS.File.writeAtomic()<a name="OS.File.writeAtomic"></a></h4>
<p>Write data to a file. Data is first written to a temporary file, then flushed, then the temporary file is used to overwrite the destination file. This makes it <em>extremely unlikely</em> that the destination file can be corrupted during the call to this function by battery failure, the process being stopped or any other such incident. Note that it is generally not possible to provide a 100% guarantee of such properties.</p>
<pre class="brush: js">
promise&lt;void&gt; writeAtomic(
  in string path,
  in <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a> data,
  in object options
)</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    The full path to the destination file.</dd>
  <dt>
    data</dt>
  <dd>
    An <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a> holding the data to write.</dd>
  <dt>
    options</dt>
  <dd>
    An object that may contain the following fields</dd>
  <dt style="margin-left: 40px;">
    tmpPath</dt>
  <dd style="margin-left: 40px;">
    The full path to a file that may be used as a temporary buffer. This file must be on the same device as path. In case of doubt, <code>path + ".tmp"</code> is generally a good value for <code>tmpPath</code>.</dd>
  <dt style="margin-left: 40px;">
    noOverwrite</dt>
  <dd style="margin-left: 40px;">
    If specified and true, and if <code>path</code> already exists, this function will throw an error without overwriting <code>path</code>.</dd>
</dl>
<div class="warning">
  <p>At the time of this writing, option tmpPath is required. Future versions will ensure that the function may work even without this argument.</p>
</div>
<div class="warning">
  <p><strong>Use with caution</strong></p>
  <p>Modifying the contents of data before the operation is complete is a <strong>very bad idea</strong>.</p>
</div>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the destination file cannot be overwritten, or if <code>tmpPath</code> is not on the same device as <code>path</code>.</dd>
</dl>
<h2 id="Instances_of_OS.File">Instances of OS.File</h2>
<p>To obtain an instance of OS.File, use function <a href="#OS.File.open" title="#OS.File.open">OS.File.open</a>.</p>
<h3 id="Methods_overview">Methods overview</h3>
<table>
  <tbody>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.prototype.close" title="#OS.File.prototype.close">close</a>()</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.prototype.flush" title="#OS.File.prototype.flush">flush</a>()</td>
    </tr>
    <tr>
      <td>promise&lt;number&gt; <a href="#OS.File.prototype.getPosition" title="#OS.File.prototype.getPosition">getPosition</a>()</td>
    </tr>
    <tr>
      <td>promise&lt;number&gt; <a href="#OS.File.prototype.read" title="#OS.File.prototype.read">read</a>([optional] in number bytes)</td>
    </tr>
    <tr>
      <td>promise&lt;number&gt; <a href="#OS.File.prototype.readTo" title="#OS.File.prototype.readTo">readTo</a>(out <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a> dest, [optional] in object options)</td>
    </tr>
    <tr>
      <td>promise&lt;void&gt; <a href="#OS.File.prototype.setPosition" title="#OS.File.prototype.setPosition">setPosition</a>(in number bytes)</td>
    </tr>
    <tr>
      <td>promise&lt;<a href="/en-US/docs/JavaScript_OS.File/OS.File.Info" title="/en-US/docs/JavaScript_OS.File/OS.File.Info">File.Info</a>&gt; <a href="#OS.File.prototype.stat" title="#OS.File.prototype.stat">stat</a>()</td>
    </tr>
    <tr>
      <td>promise&lt;number&gt; <a href="#OS.File.prototype.write" title="#OS.File.prototype.write">write</a>(in <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a> source, [optional] in object options)</td>
    </tr>
  </tbody>
</table>
<table>
  <tbody>
    <tr>
      <td>fd</td>
      <td>(platform-specific)</td>
      <td>(read-only) <strong>For advanced users only.</strong> A low-level opaque data structure holding the system handle for the file. Under Windows, this is a file <code>HANDLE</code> and under Unix, this is a file descriptor. Use this with the Platform-Specific Low-Level API.</td>
    </tr>
  </tbody>
</table>
<h3 id="Methods">Methods</h3>
<h4 id="close()">close()<a name="OS.File.prototype.close"></a></h4>
<p>Close a file and release any associated resource.</p>
<p>Once the file is closed, any attempt to call methods of the file object will raise an error.</p>
<div class="warning">
  Note that the operating system limits the number of files that can be opened simultaneously by one process, so do not forget to <a href="/#OS.File.prototype.close" title="#OS.File.prototype.close"><code>close</code></a> that file once you have finished it to make sure that you are not blocking the rest of the process.</div>
<pre class="brush: js">
promise&lt;void&gt; close()</pre>
<h4 id="flush()">flush()<a name="OS.File.prototype.flush"></a></h4>
<p>Flushes the file's internal buffers, ensuring that all data still in these buffers is now written to disk.</p>
<pre class="brush: js">
promise&lt;void&gt; flush()</pre>
<h4 id="getPosition()"><a name="OS.File.prototype.getPosition">getPosition</a>()</h4>
<p>Return the current position in the file.</p>
<pre>
promise&lt;number&gt; getPosition()
</pre>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>The current position in the file, as a number of bytes from the start.</p>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    If the file is closed.</dd>
</dl>
<h4 id="read()">read()<a name="OS.File.prototype.read"></a></h4>
<p>Read bytes from this file to a new buffer. Bytes are read from the current position in the file and the position is advanced accordingly.</p>
<pre>
promise&lt;UInt8Array&gt; read(
  [optional] in number bytes
)</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    bytes</dt>
  <dd>
    If specified, read <code>bytes</code> bytes, or less if the file does not contain that many bytes. If unspecified, read all the remaining bytes from this file.</dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>An array containing the bytes read.</p>
<div class="note">
  If you need to convert the result of this function to a string, you may do so through by using the <a href="http://wiki.whatwg.org/wiki/StringEncoding" title="http://wiki.whatwg.org/wiki/StringEncoding">StringEncoding API</a>.</div>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of I/O error.</dd>
</dl>
<h4 id="readTo()">readTo()<a name="OS.File.prototype.readTo"></a></h4>
<p>Read bytes from the file to an existing array. Bytes are read from the current position in the file and the position is advanced accordingly.</p>
<pre class="brush: js">
promise&lt;number&gt; <a href="#OS.File.prototype.readTo" title="#OS.File.prototype.readTo">readTo</a>(
  out <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a> dest,
  [optional] in object options
)</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    dest</dt>
  <dd>
    The buffer in which to store the bytes.</dd>
  <dt>
    options</dt>
  <dd>
    An object that may contain some of the following fields</dd>
  <dt style="margin-left: 40px;">
    bytes</dt>
  <dd style="margin-left: 40px;">
    An upper bound to the number of bytes to read from the file. If unspecified, read up to <code>dest.byteLength</code> bytes. If specified, this must be less than <code>dest.byteLength</code>.</dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>The number of bytes effectively read from the file.</p>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any I/O error.</dd>
  <dt>
    TypeError</dt>
  <dd>
    If <code>options.bytes</code> is specified and is larger than <code>dest.byteLength</code>.</dd>
</dl>
<h4 id="setPosition()">setPosition()<a name="OS.File.prototype.setPosition"></a></h4>
<p>Change the current position in the file.</p>
<pre>
promise&lt;void&gt; setPosition(
  in number offset,
  in object origin
)
</pre>
<h5 id="Arguments">Arguments</h5>
<ul>
  <li><code>OS.File.POS_START</code> (bytes are counted from the start of the file);</li>
  <li><code>OS.File.POS_CUR</code> (bytes are counted from the current position in the file);</li>
  <li><code>OS.File.POS_END</code> (bytes are counted from the end of the file).</li>
</ul>
<dl>
  <dt>
    offset</dt>
  <dd>
    The new position, as a number of bytes from the origin.</dd>
  <dt>
    origin</dt>
  <dd>
    One of the following:</dd>
</dl>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the new position is before the start of the file, or if the file is closed.</dd>
</dl>
<h4 id="stat()">stat()<a name="OS.File.prototype.stat"></a></h4>
<p>Obtain information about the file, such as size, creation date, etc.</p>
<pre class="brush: js">
promise&lt;<a href="/en-US/docs/JavaScript_OS.File/OS.File.Info" title="/en-US/docs/JavaScript_OS.File/OS.File.Info">File.Info</a>&gt; stat()</pre>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p class="brush: js">An instance of <a href="/en-US/docs/JavaScript_OS.File/OS.File.Info" title="/en-US/docs/JavaScript_OS.File/OS.File.Info">File.Info</a> holding information about the file.</p>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a a="" docs="" en-us="" href="/en-US/docs/JavaScript_OS.File/OS.File.Error" javascript_os.file="" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any error, in particular if the file is closed.</dd>
</dl>
<h4 id="write()">write()<a name="OS.File.prototype.write"></a></h4>
<p>Write bytes from a buffer to this file.</p>
<p>Note that, by default, this function may perform several I/O operations to ensure that the buffer is fully written.</p>
<pre>
promise&lt;number&gt; write(
  in <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a> source
  [optional] in object options
)</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    source</dt>
  <dd>
    The array in which the the bytes are stored.</dd>
  <dt>
    options</dt>
  <dd>
    An object that may contain some of the following fields</dd>
  <dt style="margin-left: 40px;">
    bytes</dt>
  <dd style="margin-left: 40px;">
    An upper bound to the number of bytes to write to the file. If unspecified, write up to <code>source.byteLength</code> bytes. If specified, this must be less than <code>source.byteLength</code>.</dd>
</dl>
<h5 id="Promise_resolves_to">Promise resolves to</h5>
<p>The number of bytes effectively written to the file.</p>
<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>
<dl>
  <dt>
    <a href="/en-US/docs/JavaScript_OS.File/OS.File.Error" title="/en-US/docs/JavaScript_OS.File/OS.File.Error">OS.File.Error</a></dt>
  <dd>
    In case of any I/O error.</dd>
  <dt>
    TypeError</dt>
  <dd>
    If <code>options.bytes</code> is specified and is larger than <code>source.byteLength</code>.</dd>
</dl>
Revert to this revision