Documentation
API Reference
WASI
fd_readdir

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

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

fd_readfd_renumber