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

[edit]Example

#include <experimental/filesystem>#include <fstream>#include <iostream>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);}

[edit]See also