Node.js Reference ยท fs and fs/promises
Node.js fs.read() method
Reference for fs.read() and fs.readSync() in Node.js: read a number of bytes from a file descriptor into a buffer, at the current or an explicit position.
fs.read(fd, buffer, offset, length, position, callback) reads up to length bytes from an open file descriptor into a Buffer you provide. It tells you how many bytes it actually read, which may be fewer than you asked for, and zero at the end of the file.
This is the low-level building block under readFile() and streams. You use it directly when you only need part of a file (a header, a record in the middle, the last few kilobytes of a log) without loading everything. The synchronous twin fs.readSync() returns the byte count instead of calling back.
import { openSync, readSync, closeSync } from 'node:fs'; const fd = openSync('data.bin', 'r'); const buf = Buffer.alloc(16); const count = readSync(fd, buf, 0, 16, 0); 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.read(fd, buffer, offset, length, position, callback) fs.read(fd, [options], callback) fs.readSync(fd, buffer, offset[, length[, position]]): number fs.readSync(fd, buffer[, options]): number // callback: (err: Error | null, bytesRead: number, buffer: Buffer) => void // options: { buffer?, offset?: number, length?: number, position?: number | bigint | null }
| Name | Description |
|---|---|
fd |
An open file descriptor from fs.open(). |
buffer |
Where the bytes go: a Buffer, TypedArray or DataView. In the options form it defaults to a 16 KiB zero-filled buffer. |
offset |
Index in buffer where writing starts (default 0). |
length |
Maximum bytes to read (default: buffer.byteLength - offset). |
position |
File position to read from. null or -1 means the current file position, which then advances. A number or bigint reads there and leaves the current position unchanged. |
Returns: readSync() returns bytesRead. The callback receives (err, bytesRead, buffer).
Errors: EBADF (invalid or write-only descriptor), EISDIR (descriptor of a directory), ERR_OUT_OF_RANGE (offset/length do not fit in the buffer), ERR_INVALID_ARG_TYPE.
Usage notes
- Short reads are normal.
bytesReadcan be smaller thanlengtheven before the end of a file (pipes, special files). For regular files a short read usually means end of file;0means nothing is left. - Only part of the buffer is valid. After a short read, use
buffer.subarray(0, bytesRead). The rest still holds old data. - Explicit position versus current position: reading with
nullmoves the shared file position; reading at a number does not. Mixing both on one descriptor is a common source of confusing results. - Text is not bytes. A multi-byte UTF-8 character can be split across two reads. Decode with
StringDecoderor read whole files when you need text. - Reuse the buffer in loops to avoid allocating a new one per call.
- Not for whole files. Use
fs.readFile()orcreateReadStream()when you want everything. - Promise version:
filehandle.read()returns{ bytesRead, buffer }.