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.
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
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.
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
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.
writevmay write fewer bytes than the total, andreadvreturns fewer at end of file. Compare the count with the sum ofbuffer.byteLengthand 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
aflag, Linux ignorespositionfor 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.