fd_pread()

Read from the file at the given offset without updating the file cursor. This acts like a stateless version of Seek + Read.

Description

The fd_pread() function is used to read data from a file identified by the provided file descriptor (fd) at a specified offset (offset). Unlike regular reading operations, fd_pread() does not update the file cursor, making it a stateless operation. The function reads data into the provided buffers (iovs) and returns the number of bytes read.

In POSIX systems, file reading operations typically involve updating the file cursor, which determines the next position from which data will be read. However, fd_pread() allows reading data from a specific offset without modifying the file cursor's position. This can be useful in scenarios where applications need to read data from a file at a specific location without altering the cursor's state.

Syntax

  ;;; Note: This is similar to `preadv` in Linux (and other Unix-es).
  ;;; Read from a file descriptor, without using and updating the file descriptor's offset.
  (@interface func (export "fd_pread")
    (param $fd $fd)
    ;;; List of scatter/gather vectors in which to store data.
    (param $iovs $iovec_array)
    ;;; The offset within the file at which to read.
    (param $offset $filesize)
    ;;; The number of bytes read.
    (result $error (expected $size (error $errno)))
  )

Parameters

• ctx: A mutable reference to the function environment.
• fd: The file descriptor of the file to read from.
• iovs: A pointer to an array of __wasi_iovec_t structures describing the buffers where the data will be stored.
• iovs_len: The number of vectors (__wasi_iovec_t) in the iovs array.
• offset: The file cursor indicating the starting position from which data will be read.
• nread: A pointer to store the number of bytes read.

Return Value

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

Logging

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

• %fd: The file descriptor being read from.
• %offset: The file cursor indicating the starting position.
• ?nread: The number of bytes read.

Note

The fd_pread() function allows reading data from a file at a specified offset without updating the file cursor. It provides a stateless alternative to the traditional Seek + Read operations. The function takes the file descriptor, an array of buffers to store the data, the offset indicating the starting position, and a pointer to store the number of bytes read.