---
title: "path_rename()"
description: "The path_rename() function renames a file or directory specified by the given path. It requires the PATH_RENAME_SOURCE right on the source directory and the PATH_RENAME_TARGET right on the target directory."
url: "https://wasix.org/docs/api-reference/wasi/path_rename/"
markdown: "https://wasix.org/docs/api-reference/wasi/path_rename.md"
---

# `path_rename()`

Rename a file or directory.

## Description

The `path_rename()` function renames a file or directory specified by the given path. It requires the `PATH_RENAME_SOURCE` right on the source directory and the `PATH_RENAME_TARGET` right on the target directory.

On POSIX systems, a similar functionality is provided by the `rename()` function. It renames a file or directory with the specified source and target paths. The `rename()` function is part of the POSIX standard and is widely supported across different platforms.

## Syntax

```ebnf
  ;;; Note: This is similar to `renameat` in POSIX.
  ;;; Rename a file or directory.
  (@interface func (export "path_rename")
    (param $fd $fd)
    ;;; The source path of the file or directory to rename.
    (param $old_path string)
    ;;; The working directory at which the resolution of the new path starts.
    (param $new_fd $fd)
    ;;; The destination path to which to rename the file or directory.
    (param $new_path string)
    (result $error (expected (error $errno)))
  )
```

## Parameters

- `ctx`: A mutable reference to the function environment.
- `old_fd`: The file descriptor representing the base directory for the source path.
- `old_path`: A wasm pointer to a null-terminated string containing the source path of the file or directory to be renamed.
- `old_path_len`: The length of the `old_path` string.
- `new_fd`: The file descriptor representing the base directory for the target path.
- `new_path`: A wasm pointer to a null-terminated string containing the target path with the new name for the file or directory.
- `new_path_len`: The length of the `new_path` string.

## Return Value

The function returns an `Errno` value indicating the success or failure of the operation. If the operation is successful, it returns `Errno::Success`. Otherwise, it returns an appropriate `Errno` value.

## Logging

This function has been instrumented with debug-level logging. It will log the following information:

- `%old_fd`: The file descriptor representing the base directory for the source path.
- `%new_fd`: The file descriptor representing the base directory for the target path.
- `old_path`: The source path string.
- `new_path`: The target path string.

## Note

The `path_rename()` function renames a file or directory specified by the given source path to the target path. It checks the necessary rights on both the source and target directories. On POSIX systems, a similar functionality is provided by the `rename()` function.

---

[Documentation index](https://wasix.org/llms.txt) · [HTML version](https://wasix.org/docs/api-reference/wasi/path_rename/)