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

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