nsIFile

nsIFile is the correct platform-agnostic way to specify a file; you should always use this instead of a string to ensure compatibility.

With an nsIFile you can navigate to ancestors or descendants without having to deal with the different path separators used on different platforms, query the state of any file or directory at the position represented by the nsIFile and create, move or copy items in the filesystem.

An nsIFile can be retrieved by either instantiating an nsILocalFile using a platform specific path string or by using cross-platform locations retrieved from the directory service.

All methods with string parameters have two forms. The preferred form operates on UTF-16 encoded characters strings. An alternate form operates on characters strings encoded in the "native" charset. A string containing characters encoded in the native charset cannot be safely passed to javascript via xpconnect. Therefore, the UTF-16 forms are scriptable, but the "native methods" are not. In addition, the native form cannot deal with files whose name contains characters outside the default system code page on Windows. Using the native form limits the ability of your code to deal with the full Unicode support on Windows 2000 or later where the OS itself does not have such a limitation. Therefore, you must not use the native form unless it is guaranteed that the path passed to a native form function is always ASCII.

To create an nsIFile from a path you can use:

var FileUtils = Cu.import("resource://gre/modules/FileUtils.jsm").FileUtils

var nsifile   = new FileUtils.File( fileName )

Method overview

Attributes

Constants

Methods

append()

This function is used for constructing a descendant of the current nsIFile.

void append(
  in AString node
);

Parameters

node

A string which is intended to be a child node of the nsIFile. This string must not contain a path separator character.

Exceptions thrown

NS_ERROR_FILE_UNRECOGNIZED_PATH

Indicates that aNode incorrectly contains a path separator character.

This method is used for constructing a descendant of the current nsIFile. [native character encoding variant]

void appendNative(
  in ACString node
);

Parameters

node

A string that is intended to be a child node of the current nsIFile. This string must not contain a path separator character. This string must be encoded using the native character encoding.

Exceptions thrown

NS_ERROR_FILE_UNRECOGNIZED_PATH

Indicates that aNode incorrectly contains a path separator character.

clone()

This method creates a clone of the nsIFile. (It does NOT clone the file itself; see the copy methods.)

nsIFile clone();

Parameters

None.

Return value

A new nsIFile instance that corresponds to the same file or directory as this nsIFile.

contains()

This method tests whether or not the path represented by the specified nsIFile instance is a descendant of the path represented by this nsIFile. This nsIFile should point to a directory, while the specified argument can point to a file or directory.

boolean contains(
  in nsIFile inFile
);

Parameters

inFile

The nsIFile to test.

Return value

true if inFile is a descendant of this nsIFile. inFile does not need to be a direct child of this nsIFile to be considered a descendant.

copyTo()

This method copies a source file to a new location if it does not already exist.

This method will NOT resolve aliases/shortcuts during the copy.

void copyTo(
  in nsIFile newParentDir,
  in AString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to copy the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used.

Exceptions thrown

NS_ERROR_FILE_DESTINATION_NOT_DIR

If the "newParentDir" is not a directory.

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.

NS_ERROR_FILE_ALREADY_EXISTS

Indicates that there is already a file named "newName" in the destination directory.

copyToFollowingLinks()

This method copies a source file to a new location if it does not already exist.

This method is identical to copyTo() except that any symbolic links will be followed as the name suggests.

void copyToFollowingLinks(
  in nsIFile newParentDir,
  in AString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to copy the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used.

Exceptions thrown

NS_ERROR_FILE_DESTINATION_NOT_DIR

If the "newParentDir" is not a directory.

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.

NS_ERROR_FILE_ALREADY_EXISTS

Indicates that there is already a file named "newName" in the destination directory.

This method copies this file to a new location. [native character encoding variant]

This method is identical to copyToNative() except that any symbolic links will be followed as the name suggests.

void copyToFollowingLinksNative(
  in nsIFile newParentDir,
  in ACString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to copy the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used. This string must be encoded using the native character encoding.

Exceptions thrown

NS_ERROR_FILE_DESTINATION_NOT_DIR

If the "newParentDir" is not a directory.

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.

NS_ERROR_FILE_ALREADY_EXISTS

Indicates that there is already a file named "newName" in the destination directory.

This method copies this file to a new location. [native character encoding variant]

void CopyToNative(
  in nsIFile newParentDir,
  in ACString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to copy the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used. This string must be encoded using the native character encoding.

Exceptions thrown

NS_ERROR_FILE_DESTINATION_NOT_DIR

If the "newParentDir" is not a directory.

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.

NS_ERROR_FILE_ALREADY_EXISTS

Indicates that there is already a file named "newName" in the destination directory.

create()

This method creates a new file or directory in the file system corresponding to the file path represented by this nsIFile. This method will create any path segments that do not already exist.

void create(
  in unsigned long type,
  in unsigned long permissions
);

Parameters

type

This specifies the type of file system object to be made. The only two types at this time are file and directory which are defined above.

permissions

A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.

Exceptions thrown

NS_ERROR_FILE_ALREADY_EXISTS

Indicates that the file or directory already exists.

NS_ERROR_FILE_UNKNOWN_TYPE

Indicates that the value of "type" does not correspond to a known type.

createUnique()

This function will create a new file or directory in the file system. Any nodes that have not been created or resolved, will be. If this file already exists, we try variations on the leaf name "suggestedName" until we find one that did not already exist. This method will create any path segments that do not already exist.

void createUnique(
  in unsigned long type,
  in unsigned long permissions
);

Parameters

type

This specifies the type of file system object to be made. The only two types at this time are file and directory which are defined above.

permissions

A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.

Exceptions thrown

NS_ERROR_FILE_UNKNOWN_TYPE

Indicates that the value of "type" does not correspond to a known type.

NS_ERROR_FILE_TOO_BIG

Indicates that the search for nonexistent files was unsuccessful because all of the attempted leaf name variants already exist.

equals()

This method tests whether or not two nsIFile instances correspond to the same file or directory.

boolean equals(
  in nsIFile inFile
);

Parameters

inFile

The nsIFile to compare this nsIFile against.

Return value

true if "inFile" is equivalent to this nsIFile.

exists()

This method tests whether or not this nsIFile exists.

boolean exists()

Parameters

None.

Return value

true if the file or directory exists. Otherwise it returns false.

isDirectory()

This method tests whether or not this nsIFile corresponds to a directory.

boolean isDirectory();

Parameters

None.

Return value

true if this nsIFile corresponds to a directory. Otherwise it returns false.

isExecutable()

This method tests whether or not this nsIFile corresponds to a file that may be executed.

boolean isExecutable();

Parameters

None.

Return value

true if the nsIFile may be executed by the user. Otherwise it returns false.

isFile()

This method tests whether or not this nsIFile corresponds to a normal file.

boolean isFile();

Parameters

None.

Return value

true if this nsIFile corresponds to a normal file. Otherwise it returns false.

isHidden()

This method tests whether or not this nsIFile corresponds to a file or directory that is hidden. In Unix, hidden files start with a period. On Mac and Windows, they have an attribute bit set.

boolean isHidden();

Parameters

None.

Return value

true if the file or directory is hidden. Otherwise it returns false.

isReadable()

This method tests whether or not this nsIFile corresponds to a file or directory that may be read by the user.

boolean isReadable();

Parameters

None.

Return value

true if the file or directory may be read by the user. Otherwise it returns false.

isSpecial()

This method tests whether or not this nsIFile corresponds to a special system file.

boolean isSpecial();

Parameters

None.

Return value

true if this nsIFile corresponds to a special system file. Otherwise it returns false.

isSymlink()

This method tests whether or not this nsIFile corresponds to a symbolic link, shortcut, or alias.

boolean isSymlink();

Parameters

None.

Return value

true if this nsIFile corresponds to a symbolic link. Otherwise it returns false.

isWritable()

This method tests whether or not this nsIFile corresponds to a file or directory that may be modified by the user.  As of Gecko 9, files on read only shares will return false.  Files that are exclusively opened on Win32 will return true if they are normally writable, and files that don't have write permissions will return false. For specific handling before Gecko 9 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6), please see bug 682571.

boolean isWritable();

Parameters

None.

Return value

true if the file or directory may be modified by the user. Otherwise it returns false.

moveTo()

This method moves this file to a new location.

If the current file path corresponds to a regular file (for storage of bytes), and if the new leaf name identifies a regular file that already exists, then this method will overwrite the destination file.

Usually, "move" means to relocate the file to a different directory without changing the file's contents or properties, or in fact the file's serial number (inode). That is a very fast operation because it just changes directory information. The actual data doesn't move.

Unfortunately, an actual "move" is impossible between different volumes (disks or partitions). This method attempts to do the "right thing" when moving files across volumes. That is, it will copy the old file to the new location, try to assign the file attributes as the old file had them, and then delete the old file. You should be aware of these possible problems:

• This process may take a long time if the file is large and/or the bandwidth is narrow.
• If the copyTo() method loses data, such as Mac resource data, then so will such a move.
• If attribute data cannot be recreated (like the file owner if you don't have enough privileges, or ACL data if moving to a non-ACL volume), then those attributes will be lost.
• The new file's serial number will almost certainly be different, because it is a different file, probably stored in a different physical location.

If you do not want to move file between different volumes, use renameTo instead.

void moveTo(
  in nsIFile newParentDir,
  in AString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to move the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be moved. This parameter may be empty, in which case the current leaf name will be used.

Exceptions thrown

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to move a file that does not exist.

NS_ERROR_FILE_DIR_NOT_EMPTY

Indicates that an attempt was made to move a directory to the location of an existing directory that is not empty.

NS_ERROR_FILE_ACCESS_DENIED

Indicates that an attempt was made to move a directory to the location of an existing directory that is not writable.

NS_ERROR_FILE_DESTINATION_NOT_DIR

Indicates that "newParentDir" exists and is not a directory.

This method moves this file to a new location. [native character encoding variant]

If the current file path corresponds to a regular file (for storage of bytes), and if the new leaf name identifies a regular file that already exists, then this method will overwrite the destination file.

Usually, "move" means to relocate the file to a different directory without changing the file's contents or properties, or in fact the file's serial number (inode). That is a very fast operation because it just changes directory information. The actual data doesn't move.

Unfortunately, an actual "move" is impossible between different volumes (disks or partitions). This method attempts to do the "right thing" when moving files across volumes. That is, it will copy the old file to the new location, try to assign the file attributes as the old file had them, and then delete the old file. You should be aware of these possible problems:

• This process may take a long time if the file is large and/or the bandwidth is narrow.
• If the copyTo() method loses data, such as Mac resource data, then so will such a move.
• If attribute data cannot be recreated (like the file owner if you don't have enough privileges, or ACL data if moving to a non-ACL volume), then those attributes will be lost.
• The new file's serial number will almost certainly be different, because it is a different file, probably stored in a different physical location.

void moveToNative(
  in nsIFile newParentDir,
  in ACString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to copy the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used. This string must be encoded using the native character encoding.

Exceptions thrown

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to move a file that does not exist.

NS_ERROR_FILE_DIR_NOT_EMPTY

Indicates that an attempt was made to move a directory to the location of an existing directory that is not empty.

NS_ERROR_FILE_ACCESS_DENIED

Indicates that an attempt was made to move a directory to the location of an existing directory that is not writable.

NS_ERROR_FILE_DESTINATION_NOT_DIR

Indicates that "newParentDir" exists and is not a directory.

normalize()

This method is used to canonicalize the path represented by this nsIFile. (for example removing .. and . components on Unix).

As of Gecko 1.7, this method is only implemented under UNIX builds (except for Mac OSX). This method will fail if the path does not exist.

void normalize();

Parameters

None.

Exceptions thrown

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the file path does not exist.

NS_ERROR_FILE_DESTINATION_NOT_DIR

Indicates that a component of the path prefix is not a directory.

NS_ERROR_FILE_ACCESS_DENIED

Read or search permission was denied for a component of the path prefix.

renameTo()

This method moves this file to a new location within the same volume.

This method is identical to moveTo except that if this file or directory is moved to a a different volume, it fails and if this method succeeds, this instance will not updated to point to the new file.

void renameTo(
  in nsIFile newParentDir,
  in AString newName
);

Parameters

newParentDir

This parameter specifies the parent directory to move the file into. If this parameter is null, then the parent directory of the file will be used.

newName

This parameter allows you to specify a new leaf name for the file to be moved. This parameter may be empty, in which case the current leaf name will be used.

Exceptions thrown

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to move a file that does not exist.

NS_ERROR_FILE_DIR_NOT_EMPTY

Indicates that an attempt was made to move a directory to the location of an existing directory that is not empty.

NS_ERROR_FILE_ACCESS_DENIED

Indicates that an attempt was made to move file across volumes, or to move a directory to the location of an existing directory that is not writable.

NS_ERROR_FILE_DESTINATION_NOT_DIR

Indicates that "newParentDir" exists and is not a directory.

remove()

This method removes the file or directory corresponding to the file path represented by this nsIFile.

This method will not resolve any symlinks.

void remove(
  in boolean recursive
);

Parameters

recursive

If this nsIFile corresponds to a directory that is not empty, then this parameter must be true in order for the directory to be deleted. Otherwise, this parameter is ignored.

Exceptions thrown

NS_ERROR_FILE_TARGET_DOES_NOT_EXIST

Indicates that the current file path does not exist. It is not possible to remove a file that does not exist.

NS_ERROR_FILE_DIR_NOT_EMPTY

Indicates that an attempt was made to remove a directory that is not empty.

NS_ERROR_FILE_ACCESS_DENIED

Indicates that an attempt was made to remove a file in a way that exceeded your permissions. Details depend on your file system and how its permissions work.

Remarks

All string-valued methods and attributes have two forms. The preferred form operates on UTF-16 (Unicode) encoded character strings. The alternate form operates on character strings encoded in the "native" multibyte character set. The native character encoding is defined as the single-byte character encoding used with the standard fopen function on the host system.

The native character encoding is determined using platform specific methods. As of Gecko 1.7, it is UTF-8 on Mac OS X. On Linux and other UNIX platforms, it is the value returned from nl_langinfo (CODESET), which usually corresponds to the value of the LC_ALL, LC_CTYPE and LANG environment variables (with the precedence the same as the order they're enumerated). On Win32 platforms, it is the currently selected ANSI codepage (specified by CP_ACP).

The word "Native" appears in the name of methods that operate on or return strings encoded in the native character set.

A string containing characters encoded in the native character set cannot be safely passed to JavaScript via XPConnect. Therefore, the "native" methods and attributes are not scriptable.

XPCOM provides the string conversion functions NS_CStringToUTF16 and NS_UTF16ToCString, which can be used to convert a string between UTF-16 and the native character encoding.

This interface was frozen for Gecko 1.0. See bug 129279 for details. From Gecko 2.0 interfaces are no longer frozen.

See also

• nsILocalFile
• NS_CStringToUTF16
• NS_UTF16ToCString