NAME

std::experimental::filesystem::rename - std::experimental::filesystem::rename

Synopsis

Defined in header <experimental/filesystem>
void rename(const path& old_p, const path& new_p);
void rename(const path& old_p, const path& new_p, std::error_code& (filesystem TS)
ec);

Moves or renames the filesystem object identified by old_p to new_p as if by the
POSIX rename:

* If old_p is a non-directory file, then new_p must be one of:

* the same file as old_p or a hardlink to it: nothing is done in this
case
* existing non-directory file: new_p is first deleted, then, without
allowing other processes to observe new_p as deleted, the pathname
new_p is linked to the file and old_p is unlinked from the file. Write
permissions are required to both the directory that contains old_p and
the directory that contains new_p.
* non-existing file in an existing directory: The pathname new_p is
linked to the file and old_p is unlinked from the file. Write
permissions are required to both the directory that contains old_p and
the directory that contains new_p.

* If old_p is a directory, then new_p must be one of:

* the same directory as old_p or a hardlink to it: nothing is done in
this case
* existing directory: new_p is deleted if empty on POSIX systems, but
this may be an error on other systems. If not an error, then new_p is
first deleted, then, without allowing other processes to observe new_p
as deleted, the pathname new_p is linked to the directory and old_p is
unlinked from the directory. Write permissions are required to both the
directory that contains old_p and the directory that contains new_p.
* non-existing directory, not ending with a directory separator, and
whose parent directory exists: The pathname new_p is linked to the
directory and old_p is unlinked from the directory. Write permissions
are required to both the directory that contains old_p and the
directory that contains new_p.

* Symlinks are not followed: if old_p is a symlink, it is itself renamed, not its
target. If new_p is an existing symlink, it is itself erased, not its target.

Rename fails if

* new_p ends with dot or with dot-dot
* new_p names a non-existing directory ending with a directory separator
* old_p is a directory which is an ancestor of new_p

Parameters

old_p - path to move or rename
new_p - target path for the move/rename operation
ec - out-parameter for error reporting in the non-throwing overload

Return value

(none)

Exceptions

The overload that does not take a error_code& parameter throws filesystem_error on
underlying OS API errors, constructed with old_p as the first argument, new_p as the
second argument, and the OS error code as the error code argument. std::bad_alloc
may be thrown if memory allocation fails. The overload taking a error_code&
parameter sets it to the OS API error code if an OS API call fails, and executes
ec.clear() if no errors occur. This overload has
noexcept specification:
noexcept

Example

// Run this code

#include <iostream>
#include <fstream>
#include <experimental/filesystem>
namespace fs = std::experimental::filesystem;
int main()
{
fs::path p = fs::current_path() / "sandbox";
fs::create_directories(p/"from");
std::ofstream(p/"from/file1.txt").put('a');
fs::create_directory(p/"to");

// fs::rename(p/"from/file1.txt", p/"to/"); // error: to is a directory
fs::rename(p/"from/file1.txt", p/"to/file2.txt"); // OK
// fs::rename(p/"from", p/"to"); // error: to is not empty
fs::rename(p/"from", p/"to/subdir"); // OK

fs::remove_all(p);
}

See also

rename renames a file
(function)
remove removes a file or empty directory
remove_all removes a file or directory and all its contents, recursively
(function)