renameFile old new changes the name of an existing
file system object from
old to
new. If the
new
object already exists, it is replaced by the
old object.
Neither path may refer to an existing directory.
A conformant implementation need not support renaming files in all
situations (e.g. renaming across different physical devices), but the
constraints must be documented. On Windows, this does not support
renaming across different physical devices; if you are looking to do
so, consider using
copyFileWithMetadata and
removeFile.
On Windows, this calls
MoveFileEx with
MOVEFILE_REPLACE_EXISTING set, which is not guaranteed to be
atomic (
https://github.com/haskell/directory/issues/109).
On other platforms, this operation is atomic.
The operation may fail with:
- HardwareFault A physical I/O error has occurred.
[EIO]
- InvalidArgument Either operand is not a valid file name.
[ENAMETOOLONG, ELOOP]
- isDoesNotExistError The original file does not exist, or
there is no path to the target. [ENOENT, ENOTDIR]
- isPermissionError The process has insufficient privileges
to perform the operation. [EROFS, EACCES, EPERM]
- isFullError Insufficient resources are available to perform
the operation. [EDQUOT, ENOSPC, ENOMEM, EMLINK]
- UnsatisfiedConstraints Implementation-dependent
constraints are not satisfied. [EBUSY]
- UnsupportedOperation The implementation does not support
renaming in this situation. [EXDEV]
- InappropriateType Either path refers to an existing
directory. [ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]