Skip to main content

Visit Mozilla.org

nsIFile:moveTo

From MDC

« XPCOM API Reference

Contents

[edit] Summary

This method moves this file to a new location. 

 void moveTo(
   in nsIFile aParentDir,
   in AString aName
 );

[edit] Parameters

aParentDir
[in] 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.
aName
[in] This parameter specifies the new leaf name for the file. This parameter may be empty, in which case the current leaf name will be used.

[edit] 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 mvoe a directory to the location of an existing directory that is not writable.
NS_ERROR_FILE_DESTINATION_NOT_DIR
Indicates that aParentDir exists and is not a directory.

[edit] Remarks

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 moveTo 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.
Retrieved from "http://developer.mozilla.org/en/docs/nsIFile:moveTo"