# std::experimental::filesystem::rename

> C++ Atlas: `cppatlas.com/w/cpp/experimental/fs/rename` | Source: https://en.cppreference.com/w/cpp/experimental/fs/rename | Domain: Technical specifications

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

## Official Specification Summary (cppreference)

```cpp
// 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_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

The overload that does not take an

`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 an

`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

```cpp
#include <experimental/filesystem>
#include <fstream>
#include <iostream>
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

- [`rename`](https://en.cppreference.com/w/cpp/io/c/rename): renames a file (function)
- [`remove`](https://en.cppreference.com/w/cpp/experimental/fs/remove), [`remove_all`](https://en.cppreference.com/w/cpp/experimental/fs/remove): removes a file or empty directory removes a file or directory and all its contents, recursively (function)

---
Attribution: content from https://en.cppreference.com/w/cpp/experimental/fs/rename (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.