---
title: "fd_renumber()"
description: "The fd_renumber() function atomically copies a file descriptor from one location to another. It ensures that the copying operation is performed atomically and returns an Errno value indicating the success or failure of the operation."
url: "https://wasix.org/docs/api-reference/wasi/fd_renumber/"
markdown: "https://wasix.org/docs/api-reference/wasi/fd_renumber.md"
---

# `fd_renumber()`

Atomically copy a file descriptor.

## Description

The `fd_renumber()` function atomically copies a file descriptor from one location to another. It ensures that the copying operation is performed atomically and returns an `Errno` value indicating the success or failure of the operation.

## Syntax

```ebnf
  ;;; would disappear if `dup2()` were to be removed entirely.
  ;;; This function provides a way to atomically renumber file descriptors, which
  (@interface func (export "fd_renumber")
    (param $fd $fd)
    ;;; The file descriptor to overwrite.
    (param $to $fd)
    (result $error (expected (error $errno)))
  )
```

## Parameters

- `ctx`: A mutable reference to the function environment.
- `from`: The file descriptor to copy.
- `to`: The location to copy the file descriptor to.

## Return Value

The function returns an `Errno` value indicating the success or failure of the operation.

## Logging

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

- `%from`: The file descriptor being copied.
- `%to`: The location to which the file descriptor is being copied.

## Note

The `fd_renumber()` function atomically copies a file descriptor from one location to another. It takes the source file descriptor `from` and the destination file descriptor `to`. If the `from` and `to` file descriptors are the same, the function returns `Errno::Success` without performing any copying operation.

The function retrieves the file descriptor map from the WASI environment and attempts to find the file descriptor entry corresponding to `from`. If the entry is found, a new file descriptor entry is created with the same properties as the original entry, except for the file descriptor number, which is set to `to`. The new entry is then inserted into the file descriptor map with the `to` file descriptor number.

The function returns an `Errno` value to indicate the success or failure of the operation. If the file descriptor is successfully copied, it returns `Errno::Success`. Otherwise, it returns an appropriate error code.

---

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