Exemple: copier un fichier par morceaux

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

Exemple: Enregistrer un canvas sur le disque

This exmaple uses Image to load an image from a path (note: if your path is a file on disk you must use local file; this is accomplished with OS.Path.toFileURI, which accepts a string). After image loads it then draws it to canvas, makes it a blob, and uses FileReader to turn it into ArrayBuffer(View), then uses OS.File.writeAtomic to save to disk.

Exemple: Ajouter au fichier

This example shows how to use open, write, and close to append to a file. If the file does not exist, it is created. At the time of this writing, write does not support encoding option so the text to be written has to be encoded with TextEncoder. This example also shows the resolve value of open (an instance of OS.File, this is a file, so you can do any of the methods on it found here), write (a number indicating bytes written), and close (undefined, meaning there is no resolve value).

Arguments

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.

Prior to Gecko 27, unless create or truncate are set or explicit unixFlags are given, the file will be opened for appending on Unix/Linux. However, the file is not opened for appending on Windows. See bug 924858. Starting with Gecko 27, you may use the append flag instead. For an example using append see here.

truncate | trunc

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.

append

If true, the file will be opened for appending, meaning the equivalent of .setPosition(0, POS_END) is executed before each write. The default is true, i.e. opening a file for appending. Specify append: false to open the file in regular mode.

optionsFacultatif

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.

When opening files for writing, they will be opened for appending unless you specify append: false in Gecko 27 and later. In Gecko 26 and earlier, on platforms other than Windows, the files will be opened for appending unless you specify explicit unixFlags or open the file with either create or truncate flags. In Gecko 26 and earlier on Windows, files will never be opened for appending.

To open an existing file for writing without appending in a compatible way on all platforms in both Gecko 27 and later and Gecko 26 and earlier, you should specify both the append flag and unixFlags.

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.

Safety note: Recall that the current directory can change during the execution of the process. Therefore, the information returned by this function may be false by the time you receive it.

OS.File.makeDir()

Arguments

path

The full name of the directory to create.

optionsFacultatif

Options for creating the directory. To specify options, pass an object that may contain some of the following flags:

ignoreExisting

If true, succeed even if the directory already exists (default behavior). Otherwise, fail if the directory already exists. NOTE: If from is specified then even if ignoreExisting is specified as false, it will not fail due to pre-existence of directories, because the from option tells makeDir to make the folders if not found.

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.

from

If specified, the call to makeDir creates all the ancestors of path that are descendents of from. Note that from and its existing descendents must be user-writeable and that path must be a descendent of from.

Promise can be rejected with

In case of any error, in particular if the path does not represent an existing file.

OS.File.setPermissions()

Sets the file's access permission bits.

Promise<void> setPermissions(
in string path,
in object options
)

Arguments

path

The complete path to the file.

options

The new attributes to set

winAttributes

This is an object with following optional keys. Ignored under non-Windows platforms.

hidden

Boolean. Set to true to make the target hidden, or false to make it visible.

readOnly

Boolean. Set to true to make the target "read only".

system

Boolean. Toggles the "system" attribute, this is equivalent .

unixMode

Number. This is an number can be created with the constants available in OS.Constants.libc.S_I* or OS.Constants.libc.S_O*. Ignored under non-Unix platforms. To make a file hidden on Unix based platforms, including Mac, simply rename the file with OS.File.move to have "." at the start of the file name.

If null or unspecified, write the data directly to path. If specified, write the data to a temporary file called tmpPath and, once the write is complete, rename the file to replace path. Performing this operation is a little slower but also a little safer.

tmpPath is required in Firefox 24 or lower version, but optional in Firefox 25 or higher version

noOverwrite

If specified and true, and if path already exists, this function will throw an error without overwriting path.

flush

If false or unspecified, return immediately once the write is complete. If true, before writing, force the operating system to write its internal disk buffers to the disk. This is considerably slower (not just for the application but for the whole system) and more battery expensive but also safer: if the system shuts down improperly (typically due to a kernel freeze or a power failure) or if the device is disconnected before the buffer is flushed, the file has more chances of not being corrupted.

backupTo

Available since Firefox 30. If specified, backup the destination file as backupTo. Note that this function renames the destination file before overwriting it. If the process or the operating system freezes or crashes during the short window between these operations, the destination file will have been moved to its backup.

encoding

Available since Firefox 22. Instead of using TextEncoder, you can supply a string to this option. For example, instead of:

Limitations
In a few extreme cases (hardware failure during the write, user unplugging disk during the write, etc.), data may be corrupted. If your data is user-critical (e.g., preferences, application data), you may wish to consider adding options tmpPath and/or flush to reduce the likelihood of corruption, as detailed above. Note that no combination of options can be guaranteed to totally eliminate the risk of corruption.

Use with caution: Modifying the contents of data before the operation is complete is a very bad idea.

Methods

close()

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

An example is seen here. In this example the contents is not written to file until .close is called.

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.

Disk flushes are very expensive and therefore should be used carefully, sparingly, and only in scenarios where it is vital that data survives system crashes. Even though the function will be executed off the main-thread, it might still affect the overall performance of any running application.