Moves or renames the filesystem object identified byold_p tonew_p as if by the POSIXrename:

• Ifold_p is a non-directory file, thennew_p must be one of:

• the same file asold_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 observenew_p as deleted, the pathnamenew_p is linked to the file andold_p is unlinked from the file. Write permissions are required to both the directory that containsold_p and the directory that containsnew_p.
• non-existing file in an existing directory: The pathnamenew_p is linked to the file andold_p is unlinked from the file. Write permissions are required to both the directory that containsold_p and the directory that containsnew_p.

• Ifold_p is a directory, thennew_p must be one of:

• the same directory asold_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, thennew_p is first deleted, then, without allowing other processes to observenew_p as deleted, the pathnamenew_p is linked to the directory andold_p is unlinked from the directory. Write permissions are required to both the directory that containsold_p and the directory that containsnew_p.
• non-existing directory, not ending with a directory separator, and whose parent directory exists: The pathnamenew_p is linked to the directory andold_p is unlinked from the directory. Write permissions are required to both the directory that containsold_p and the directory that containsnew_p.

• Symlinks are not followed: ifold_p is a symlink, it is itself renamed, not its target. Ifnew_p is an existing symlink, it is itself erased, not its target.

Rename fails if

• new_p ends withdot or withdot-dot.
• new_p names a non-existing directory ending with a directory separator.
• old_p is a directory which is an ancestor ofnew_p.

[edit]Parameters

[edit]Return value

(none)

[edit]Exceptions

Any overload not markednoexcept may throwstd::bad_alloc if memory allocation fails.

[edit]Example

#include <filesystem>#include <fstream>namespace fs= std::filesystem; int main(){std::filesystem::path p=std::filesystem::current_path()/"sandbox";std::filesystem::create_directories(p/"from");std::ofstream{ p/"from/file1.txt"}.put('a');std::filesystem::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 std::filesystem::remove_all(p);}

[edit]See also

• In other languages

• Español
• 日本語
• Русский
• 中文