Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.readv() and writev() methods

Reference for fs.readv() and fs.writev() in Node.js: read into or write from several buffers in one call, position handling, return values and pitfalls.

fs.readv() reads from a file and spreads the bytes over a list of buffers, filling the first buffer, then the second, and so on. fs.writev() does the opposite: it writes several buffers to a file one after another as a single operation. This is called vectored (or scatter/gather) I/O.

It is useful when your data already lives in separate pieces, such as a fixed-size header plus a body, and you do not want to copy them into one big buffer first. One system call replaces several, and the pieces land contiguously in the file.

NODE
import fs from "node:fs";

const fd = fs.openSync("out.bin", "w");
const written = fs.writevSync(fd, [Buffer.from("head-"), Buffer.from("body")]);
fs.closeSync(fd);

Try it

Node.js Gather-write, then scatter-read

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Promise form with positions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
fs.readv(fd, buffers[, position], callback)      // callback(err, bytesRead, buffers)
fs.readvSync(fd, buffers[, position]): number
fs.writev(fd, buffers[, position], callback)     // callback(err, bytesWritten, buffers)
fs.writevSync(fd, buffers[, position]): number

// fs/promises
filehandle.readv(buffers[, position]): Promise<{ bytesRead, buffers }>
filehandle.writev(buffers[, position]): Promise<{ bytesWritten, buffers }>
Name Description
fd An integer file descriptor.
buffers An array of ArrayBufferView objects (Buffer, Uint8Array, DataView, ...). For readv they are filled in order; for writev they are written in order.
position Byte offset in the file. If it is not a number (omitted or null), the current file position is used and advanced.
callback Receives the error, the byte count and the same buffers array you passed.

Returns: the sync forms return the number of bytes read or written. The promise forms resolve with an object holding the count and the buffers.

Errors: EBADF for a bad descriptor or one opened with the wrong mode, ERR_INVALID_ARG_TYPE if buffers is not an array of views.

Usage notes

  • Strings are not accepted. Wrap them with Buffer.from() first.
  • Partial transfers are normal. writev may write fewer bytes than the total, and readv returns fewer at end of file. Compare the count with the sum of buffer.byteLength and loop if you need everything. Buffers beyond the data stay untouched.
  • With a numeric position, the file's own position does not move, which makes concurrent use safe. Without one, calls share a moving position, so do not interleave them on the same descriptor.
  • Appending: on a file opened with the a flag, Linux ignores position for writes and always appends.
  • Limits: operating systems cap how many buffers one call may take (often 1024). Split very long lists.
  • Gain is small for small data. Vectored I/O saves copies and system calls; for a few short strings, one Buffer.concat() is just as good.