NAME¶

std::filesystem::rename - std::filesystem::rename

Synopsis¶

Defined in header <filesystem>
void rename( const std::filesystem::path& old_p, (1) (since C++17)
const std::filesystem::path& new_p );
void rename( const std::filesystem::path& old_p,

const std::filesystem::path& new_p, (2) (since C++17)

std::error_code& ec ) noexcept;

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.

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 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.

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);
}

See also¶

rename renames a file
(function)
remove removes a file or empty directory
remove_all removes a file or directory and all its contents, recursively
(C++17) (function)
(C++17)