【Node.js24.x】Object::readvSync()メソッドの使い方

readvSyncメソッドは、Node.jsのfsモジュールに属し、指定されたファイルディスクリプタからデータを複数のバッファへ同期的に読み込むメソッドです。このメソッドは、readSyncメソッドが単一のバッファにデータを読み込むのとは異なり、複数のBufferまたはTypedArrayオブジェクトの配列を引数として受け取ります。これにより、一度のシステムコールで非連続な複数のメモリ領域にデータを効率的に読み込む「ベクトルI/O（scatter-read）」という操作を実現します。

このメソッドは、読み込み操作が完了するまでプログラムの実行をブロックする同期的な処理を行います。そのため、ファイルI/Oの完了を待つ間、アプリケーション全体の処理が一時的に停止する可能性があります。引数としては、読み込み対象となるファイルのディスクリプタ、データを書き込むバッファの配列、そしてファイル内のどの位置から読み込みを開始するかを示すオフセット、読み込むバイトの合計長などを指定します。メソッドの実行後、実際に読み込まれたバイトの総数が戻り値として返されます。

ファイルのヘッダー情報と本体データをそれぞれ異なるバッファに直接格納したい場合など、複数のデータをファイルから効率的に一度に取得するシーンで特に有用です。エラーが発生した場合は例外がスローされるため、適切なエラーハンドリングを行う必要があります。

Copy
1const fs = require('node:fs');
2
3const fileDescriptor = 3; // 整数型（ファイル記述子）
4const arrayOfBuffers = [
5  Buffer.alloc(16), // Uint8Array
6  Buffer.alloc(32)  // Uint8Array
7];
8const startPosition = 0; // 整数型（ファイル内の読み込み開始位置、オプション）
9
10const totalBytesRead = fs.readvSync(fileDescriptor, arrayOfBuffers, startPosition);

fd, buffers, position

• fd: number: ファイルディスクリプタ。読み込み対象のファイルやソケットなど、オペレーティングシステムが管理するリソースを識別する番号です。
• buffers: Array<Uint8Array | string>: データを読み込むためのバッファの配列。各要素はUint8Arrayまたは文字列で、読み込まれたデータが格納されます。
• position: number: 読み込みを開始するファイル内のオフセット位置。省略した場合、現在のファイルポインタの位置から読み込みます。

number

このメソッドは、非同期I/O操作で読み込まれたバイト数を表す数値を返します。