---
title: "fd_readdir()"
description: "Read data from a directory specified by the file descriptor."
url: "https://wasix.org/docs/api-reference/wasi/fd_readdir/"
markdown: "https://wasix.org/docs/api-reference/wasi/fd_readdir.md"
---

# `fd_readdir()`

Read data from a directory specified by the file descriptor.

## Description

The `fd_readdir()` function reads directory entries from a directory identified by the provided file descriptor (`fd`). It stores the directory entries in the buffer specified by `buf` and returns the number of bytes stored in the buffer via the `bufused` pointer.

## Syntax

```ebnf
  ;;; sequence.
  ;;; Entries for the special `.` and `..` directory entries are included in the
  ;;;
  ;;; entry, or skip the oversized directory entry.
  ;;; read buffer size in case it's too small to fit a single large directory
  ;;; truncating the last directory entry. This allows the caller to grow its
  ;;; This function fills the output buffer as much as possible, potentially
  (@interface func (export "fd_readdir")
    (param $fd $fd)
    ;;; The buffer where directory entries are stored
    (param $buf (@witx pointer u8))
    (param $buf_len $size)
    ;;; The location within the directory to start reading
    (param $cookie $dircookie)
    ;;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached.
    (result $error (expected $size (error $errno)))
  )
```

## Parameters

- `ctx`: A mutable reference to the function environment.
- `fd`: The file descriptor of the directory to read from.
- `buf`: A pointer to the buffer where directory entries will be stored.
- `buf_len`: The length of the buffer in bytes.
- `cookie`: The directory cookie indicating the position to start reading from.
- `bufused`: A pointer to store the number of bytes stored in the buffer.

## Return Value

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

## Logging

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

- `%fd`: The file descriptor of the directory being read from.

## Note

The `fd_readdir()` function reads directory entries from a directory identified by the file descriptor `fd`. It takes the file descriptor, a buffer where the directory entries will be stored, the length of the buffer in bytes, the directory cookie indicating the position to start reading from, and a pointer to store the number of bytes stored in the buffer.

The function reads the directory entries and stores them in the buffer according to the specified format. The `bufused` pointer will be updated with the number of bytes stored in the buffer. If the entire directory has been read and there is no more data to read, the function will indicate this by storing a value less than `buf_len` in `bufused`.

The function returns an `Errno` value to indicate the success or failure of the operation. If the directory entries are successfully read and stored in the buffer, 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_readdir/)