From cppreference.com
Defined in header
voidrename(conststd::filesystem::path&old_p,conststd::filesystem::path&new_p); (1) (since C++17)voidrename(conststd::filesystem::path&old_p,conststd::filesystem::path&new_p,std::error_code&ec)noexcept; (2) (since C++17)Moves or renames the filesystem object identified by old_p to new_p as if by the POSIX
:
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
Any overload not marked noexcept may throw
if memory allocation fails.
1) Throws
std::filesystem::filesystem_error
on underlying OS API errors, constructed with old_p as the first path argument, new_p as the second path argument, and the OS error code as the error code argument.
2) Sets a std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.
() if no errors occur.
Example
Run this code
#include<filesystem>#include<fstream>namespacefs=std::filesystem;intmain(){std::filesystem::pathp=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 directoryfs::rename(p/"from/file1.txt",p/"to/file2.txt");// OK// fs::rename(p / "from", p / "to"); // error: "to" is not emptyfs::rename(p/"from",p/"to/subdir");// OKstd::filesystem::remove_all(p);}See also
renames a file
(function)
(C++17)(C++17)
removes a file or empty directory
removes a file or directory and all its contents, recursively
(function)