std::filesystem::rename
From cppreference.com
< cpp | filesystem
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Filesystem library
filesystem::rename
Defined in header
<filesystem>
void rename( const std::filesystem::path & old_p,
const std::filesystem::path & new_p );
(1)
(since C++17)
const std::filesystem::path & new_p );
void rename( const std::filesystem::path & old_p,
(2)
(since C++17)
const std::filesystem::path & new_p,
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.
[edit] 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
[edit] Return value
(none)
[edit] Exceptions
Any overload not marked noexcept
may throw std::bad_alloc 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.clear () if no errors occur.
[edit] Example
Run this code
#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
(C++17)(C++17)
removes a file or directory and all its contents, recursively
(function) [edit]