SysTutorials

Linux Manual Pages › Section 3

stdfilesystemrename(3)

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

Synopsis

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, (since C++ 17)
                                                    const std::filesystem::path &new_p,
            std::error_code &ec) noexcept;

Moves or renames the filesystem object identified by old_p to new_p as if by the POSIX rename:

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 path argument, new_p as the second path argument, and the OS error code as the error code argument. 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. Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails.

Example

// Run this code

#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

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