FileUtils.jsm

The FileUtils.jsm JavaScript code module offers utility routines dealing with files. To use it, you first need to import the code module into your JavaScript scope:

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

The File constructor

(Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

If you have a path to a file (or directory) you want to obtain an nsIFile for, you can do so using the File constructor, like this:

var f = new FileUtils.File(mypath);

Method overview

nsIFile getFile(string key, array pathArray, bool followLinks);
nsIFile getDir(string key, array pathArray, bool shouldCreate, bool followLinks);
nsIFileOutputStream openFileOutputStream(nsIFile file, int modeFlags);
nsIFileOutputStream openAtomicFileOutputStream(nsIFile file, int modeFlags);
nsIFileOutputStream openSafeFileOutputStream(nsIFile file, int modeFlags);
void closeAtomicFileOutputStream(nsIFileOutputStream stream);
void closeSafeFileOutputStream(nsIFileOutputStream stream);

Constants

Constant Value Description
MODE_RDONLY 0x01 Corresponds to the PR_RDONLY parameter to PR_OPEN
MODE_WRONLY 0x02 Corresponds to the PR_WRONLY parameter to PR_OPEN
MODE_CREATE 0x08 Corresponds to the PR_CREATE_FILE parameter to PR_OPEN
MODE_APPEND 0x10 Corresponds to the PR_APPEND parameter to PR_OPEN
MODE_TRUNCATE 0x20 Corresponds to the PR_TRUNCATE parameter to PR_OPEN
PERMS_FILE 0644 Default permissions when creating files.
PERMS_DIRECTORY 0755 Default permissions when creating directories

Methods

getFile()

Gets a file at the specified hierarchy under a nsIDirectoryService key.

nsIFile getFile(
  string key,
  array pathArray,
  bool followLinks
);
Parameters
key
The nsIDirectoryService key to start from (see Getting special files for more info)
pathArray
An array of path components to locate beneath the directory specified by key. The last item in this array must be the leaf name of a file.
followLinks Optional
True if links should be followed, false otherwise.
Return value

Returns a nsIFile object for the file specified. The file is NOT created if it does not exist, however all required directories along the way are.

getDir()

Gets a directory at the specified hierarchy under a nsIDirectoryService key.

nsIFile getDir(
  string key,
  array pathArray,
  bool shouldCreate,
  bool followLInks
);
Parameters
key
The nsIDirectoryService key to start from (see Getting special files for more info)
pathArray
An array of path components to locate beneath the directory specified by key.
shouldCreate Optional
True if the directory hierarchy specified in pathArray should be created if it does not exist, false otherwise.
followLinks Optional
True if links should be followed, false otherwise location specified.
Return value

Returns a nsIFile object for the location specified. If the directory requested does not exist, it is created, along with any parent directories that need to be created.

Note: If you want to use the full path to get to the directory you cannot use getDir. Instead use the file constructor, so simply:

var dir = new FileUtils.File('C:\\blah\\blah');
if (dir.exists()) {
  //yes directory exists
}

openFileOutputStream()

Requires Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

Opens a file output stream for writing.

The stream is opened with the DEFER_OPEN nsIFileOutputStream.Behavior flag constants; this means the file is not actually opened until the first time it's accessed.

nsIFileOutputStream openFileOutputStream(
  nsIFile file,
  int modeFlags
);
Parameters
file
The file to write to.
modeFlags Optional
File open flags (see constants above)
Return value

Returns nsIFileOutputStream (the non-safe variant) to write to.

openAtomicFileOutputStream()

Opens an atomic file output stream for writing.

Note: 'safe' and 'atomic' file output streams will never append; they will always overwrite an existing file.

Starting in Gecko 38.0, passing MODE_APPEND without MODE_TRUNCATE will throw an exception.

nsIFileOutputStream openAtomicFileOutputStream(
  nsIFile file,
  int modeFlags
);
Parameters
file
The file to write to.
modeFlags Optional
File open flags (see constants above)
Return value

Returns nsIFileOutputStream (the safe variant) to write to.

Note: openAtomicFileOutputStream() is generally better than openSafeFileOutputStream() because flushing is not needed in most of the issues.

closeAtomicFileOutputStream()

Closes an atomic file output stream.

void closeAtomicFileOutputStream(
  nsIFileOutputStream stream
);
Parameters
stream
The stream to close.

openSafeFileOutputStream()

Opens a safe file output stream for writing.

Note: 'safe' and 'atomic' file output streams will never append; they will always overwrite an existing file.

Starting in Gecko 38.0, passing MODE_APPEND without MODE_TRUNCATE will throw an exception.

nsIFileOutputStream openSafeFileOutputStream(
  nsIFile file,
  int modeFlags
);
Parameters
file
The file to write to.
modeFlags Optional
File open flags (see constants above)
Return value

Returns nsIFileOutputStream (the safe variant) to write to.

Remarks

Note: Starting in Gecko 6.0, the stream is opened with the DEFER_OPEN nsIFileOutputStream.Behavior flag constants; this means the file is not actually opened until the first time it's accessed.

closeSafeFileOutputStream()

Closes a safe file output stream.

void closeSafeFileOutputStream(
  nsIFileOutputStream stream
);
Parameters
stream
The stream to close.

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, Jez9999, bgrins, Noitidart, lpy, kscarfone, sachin.hosmani, teoli, Sheppy, trevorh, philikon
 Last updated by: arai,