std::filesystem::rename
Defined in header <filesystem> | ? | ? |
---|---|---|
void rename(const std::filesystem::path& old_p, const std::filesystem::path& new_p); void rename(const std::filesystem::path& old_p, const std::filesystem::path& new_p, std::error_code& ec); | ? | (since C++17) |
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, thennew_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 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 pathname
new_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
.
- the same file as
- If
old_p
is a directory, thennew_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, 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 pathname
new_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
.
- the same directory as
- Symlinks are not followed: if
old_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 with dot or with dot-dotnew_p
names a non-existing directory ending with a directory separatorold_p
is 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 a std::error_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 std::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
#include <iostream>
#include <fstream>
#include <filesystem>
namespace fs = std::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
rename | renames a file (function) |
---|---|
removeremove_all (C++17)(C++17) | removes a file or empty directoryremoves a file or directory and all its contents, recursively (function) |
? cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
本文档系腾讯云开发者社区成员共同维护,如有问题请联系 cloudcommunity@tencent.com