FreeBSD Manual Pages
std::filesystem::rename(3) C++ Standard Libary std::filesystem::rename(3) NAME 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: * 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 path- name 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: noth- ing 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 direc- tory and old_p is unlinked from the directory. Write permissions are re- quired 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 over- load Return value (none) Exceptions The overload that does not take a std::error_code& parameter throws filesystem::filesystem_error on underlying OS API errors, con- structed 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& pa- rameter 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 di- rectory 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) remove removes a file or empty directory remove_all removes a file or directory and all its contents, recur- sively (C++17) (function) (C++17) http://cppreference.com 2022.07.31 std::filesystem::rename(3)
NAME | Synopsis | Parameters | Return value | Exceptions | Example | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::filesystem::rename&sektion=3&manpath=FreeBSD+Ports+15.0>