std::experimental::filesystem::rename
From cppreference.com
< cpp | experimental | fs
| 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& ec); |
(filesystem TS) | |
Moves or renames the filesystem object identified by old_p to new_p as if by the POSIX rename:
- If
old_pis a non-directory file, thennew_pmust be one of:
- the same file as
old_por a hardlink to it: nothing is done in this case - existing non-directory file:
new_pis first deleted, then, without allowing other processes to observenew_pas deleted, the pathnamenew_pis linked to the file andold_pis unlinked from the file. Write permissions are required to both the directory that containsold_pand the directory that containsnew_p. - non-existing file in an existing directory: The pathname
new_pis linked to the file andold_pis unlinked from the file. Write permissions are required to both the directory that containsold_pand the directory that containsnew_p.
- the same file as
- If
old_pis a directory, thennew_pmust be one of:
- the same directory as
old_por a hardlink to it: nothing is done in this case - existing directory:
new_pis deleted if empty on POSIX systems, but this may be an error on other systems. If not an error, thennew_pis first deleted, then, without allowing other processes to observenew_pas deleted, the pathnamenew_pis linked to the directory andold_pis unlinked from the directory. Write permissions are required to both the directory that containsold_pand the directory that containsnew_p. - non-existing directory, not ending with a directory separator, and whose parent directory exists: The pathname
new_pis linked to the directory andold_pis unlinked from the directory. Write permissions are required to both the directory that containsold_pand the directory that containsnew_p.
- the same directory as
- Symlinks are not followed: if
old_pis a symlink, it is itself renamed, not its target. Ifnew_pis an existing symlink, it is itself erased, not its target.
Rename fails if
-
new_pends with dot or with dot-dot -
new_pnames a non-existing directory ending with a directory separator -
old_pis a directory which is an ancestor ofnew_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 aerror_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
| renames a file (function) | |
| removes a file or empty directory removes a file or directory and all its contents, recursively (function) |