Node.js v21.7.2 ドキュメント

Promise の例#

Promise ベースの操作は、非同期操作が完了したときに履行される Promise を返します。

import { unlink } from 'node:fs/promises';

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}const { unlink } = require('node:fs/promises');

(async function(path) {
  try {
    await unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');copy

コールバックの例#

コールバック形式では、最後の引数として完了コールバック関数を受け取り、操作を非同期的に実行します。完了コールバックに渡される引数はメソッドによって異なりますが、最初の引数は常に例外用に予約されています。操作が正常に完了した場合、最初の引数はnullまたはundefinedになります。

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});const { unlink } = require('node:fs');

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});copy

最大パフォーマンス（実行時間とメモリ割り当ての両面で）が要求される場合は、promise APIを使用するよりも、node:fsモジュールAPIのコールバックベースのバージョンを使用する方が望ましいです。

同期的な例#

同期APIは、操作が完了するまでNode.jsのイベントループとJavaScriptの実行をブロックします。例外はすぐにスローされ、try...catchを使用して処理するか、バブルアップさせることができます。

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}const { unlinkSync } = require('node:fs');

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}copy

Promise API#

fs/promises APIは、promiseを返す非同期ファイルシステムメソッドを提供します。

promise APIは、基盤となるNode.jsのスレッドプールを使用して、イベントループスレッド外でファイルシステム操作を実行します。これらの操作は同期化されておらず、スレッドセーフではありません。同じファイルに対して複数の同時変更を実行する場合は注意が必要で、データ破損が発生する可能性があります。

クラス: FileHandle#

<FileHandle>オブジェクトは、数値ファイル記述子のオブジェクトラッパーです。

<FileHandle>オブジェクトのインスタンスは、fsPromises.open()メソッドによって作成されます。

すべての<FileHandle>オブジェクトは、<EventEmitter>です。

<FileHandle>がfilehandle.close()メソッドを使用して閉じられない場合、メモリリークを防ぐために、ファイル記述子を自動的に閉じようとし、プロセス警告を発します。これは信頼できない動作であり、ファイルが閉じられない可能性があるため、この動作に依存しないでください。代わりに、常に明示的に<FileHandle>を閉じてください。Node.jsは将来この動作を変更する可能性があります。

イベント: 'close'#

<FileHandle>が閉じられ、使用できなくなったときに、'close'イベントが発行されます。

filehandle.appendFile(data[, options])#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • flush <boolean> trueの場合、基盤となるファイル記述子が閉じられる前にフラッシュされます。デフォルト: false。
• 戻り値: <Promise> 成功時にundefinedで解決します。

filehandle.writeFile()のエイリアスです。

ファイルハンドルを操作する場合、モードはfsPromises.open()で設定されたものから変更できません。したがって、これはfilehandle.writeFile()と同等です。

filehandle.chmod(mode)#

• mode <integer> ファイルモードのビットマスク。
• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルの権限を変更します。chmod(2)を参照してください。

filehandle.chown(uid, gid)#

• uid <integer> ファイルの新しい所有者のユーザーID。
• gid <integer> ファイルの新しいグループのグループID。
• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルの所有権を変更します。chown(2)のラッパーです。

filehandle.close()#

• 戻り値: <Promise> 成功時にundefinedで解決します。

ハンドルに対する保留中の操作が完了するのを待ってから、ファイルハンドルを閉じます。

import { open } from 'node:fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
} copy

filehandle.createReadStream([options])#

• options <Object>
  • encoding <string> デフォルト: null
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024
• 戻り値: <fs.ReadStream>

<stream.Readable>のデフォルトのhighWaterMarkである16KiBとは異なり、このメソッドによって返されるストリームのデフォルトのhighWaterMarkは64KiBです。

optionsには、ファイル全体ではなく、ファイルから一定の範囲のバイトを読み取るためのstartとendの値を含めることができます。startとendの両方は包括的で、0から数え始め、許容される値は[0, Number.MAX_SAFE_INTEGER]の範囲です。startが省略されているか、undefinedの場合、filehandle.createReadStream()は現在のファイル位置から順番に読み取ります。encodingは、<Buffer>で受け入れられるもののいずれかになります。

FileHandleが、キーボードやサウンドカードのように、ブロッキング読み取りのみをサポートする文字デバイスを指している場合、データが利用可能になるまで読み取り操作は完了しません。これにより、プロセスの終了やストリームの自然な終了が妨げられる可能性があります。

デフォルトでは、ストリームは破棄された後に'close'イベントを発行します。この動作を変更するには、emitCloseオプションをfalseに設定します。

import { open } from 'node:fs/promises';

const fd = await open('/dev/input/event0');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

autoCloseがfalseの場合、エラーが発生した場合でもファイル記述子は閉じられません。それを閉じ、ファイル記述子のリークがないことを確認するのはアプリケーションの責任です。autoCloseがtrue（デフォルトの動作）に設定されている場合、'error'または'end'でファイル記述子が自動的に閉じられます。

100バイトのファイルの最後の10バイトを読み取る例

import { open } from 'node:fs/promises';

const fd = await open('sample.txt');
fd.createReadStream({ start: 90, end: 99 }); copy

filehandle.createWriteStream([options])#

• options <Object>
  • encoding <string> デフォルト: 'utf8'
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • highWaterMark <number> デフォルト: 16384
  • flush <boolean> trueの場合、基盤となるファイル記述子が閉じられる前にフラッシュされます。デフォルト: false。
• 戻り値: <fs.WriteStream>

optionsには、ファイルの先頭を過ぎた位置にデータを書き込むためのstartオプションを含めることもできます。許容される値は[0, Number.MAX_SAFE_INTEGER]の範囲です。ファイルを置き換えるのではなく変更するには、デフォルトのrではなくflags openオプションをr+に設定する必要があります。encodingは、<Buffer>で受け入れられるもののいずれかになります。

autoCloseがtrue（デフォルトの動作）に設定されている場合、'error'または'finish'でファイル記述子が自動的に閉じられます。autoCloseがfalseの場合、エラーが発生した場合でもファイル記述子は閉じられません。それを閉じ、ファイル記述子のリークがないことを確認するのはアプリケーションの責任です。

デフォルトでは、ストリームは破棄された後に'close'イベントを発行します。この動作を変更するには、emitCloseオプションをfalseに設定します。

filehandle.datasync()#

• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルに関連付けられている現在キューに入れられているすべてのI/O操作を、オペレーティングシステムの同期I/O完了状態に強制します。詳細については、POSIX fdatasync(2)ドキュメントを参照してください。

filehandle.syncとは異なり、このメソッドは変更されたメタデータをフラッシュしません。

filehandle.fd#

• <number> <FileHandle>オブジェクトによって管理される数値ファイル記述子。

filehandle.read(buffer, offset, length, position)#

• buffer <Buffer> | <TypedArray> | <DataView> 読み取られたファイルデータが入力されるバッファ。
• offset <integer> 入力を開始するバッファ内の位置。デフォルト: 0
• length <integer> 読み取るバイト数。デフォルト: buffer.byteLength - offset
• position <integer> | <bigint> | <null> ファイルからデータの読み込みを開始する位置。null または -1 の場合、現在のファイル位置からデータが読み込まれ、位置が更新されます。position が非負の整数の場合、現在のファイル位置は変更されません。デフォルト: null
• 戻り値: <Promise> 成功時に2つのプロパティを持つオブジェクトで解決されます。
  • bytesRead <integer> 読み込まれたバイト数
  • buffer <Buffer> | <TypedArray> | <DataView> 渡された buffer 引数への参照。

ファイルからデータを読み込み、指定されたバッファーに格納します。

ファイルが同時に変更されない場合、読み込まれたバイト数がゼロになったときにファイルの終わりに到達します。

filehandle.read([options])#

• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> 読み込まれたファイルデータで埋められるバッファー。デフォルト: Buffer.alloc(16384)
  • offset <integer> 入力を開始するバッファ内の位置。デフォルト: 0
  • length <integer> 読み取るバイト数。デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> ファイルからデータの読み込みを開始する位置。null または -1 の場合、現在のファイル位置からデータが読み込まれ、位置が更新されます。position が非負の整数の場合、現在のファイル位置は変更されません。デフォルト: null
• 戻り値: <Promise> 成功時に2つのプロパティを持つオブジェクトで解決されます。
  • bytesRead <integer> 読み込まれたバイト数
  • buffer <Buffer> | <TypedArray> | <DataView> 渡された buffer 引数への参照。

ファイルからデータを読み込み、指定されたバッファーに格納します。

ファイルが同時に変更されない場合、読み込まれたバイト数がゼロになったときにファイルの終わりに到達します。

filehandle.read(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> 読み取られたファイルデータが入力されるバッファ。
• options <Object>
  • offset <integer> 入力を開始するバッファ内の位置。デフォルト: 0
  • length <integer> 読み取るバイト数。デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> ファイルからデータの読み込みを開始する位置。null または -1 の場合、現在のファイル位置からデータが読み込まれ、位置が更新されます。position が非負の整数の場合、現在のファイル位置は変更されません。デフォルト: null
• 戻り値: <Promise> 成功時に2つのプロパティを持つオブジェクトで解決されます。
  • bytesRead <integer> 読み込まれたバイト数
  • buffer <Buffer> | <TypedArray> | <DataView> 渡された buffer 引数への参照。

ファイルからデータを読み込み、指定されたバッファーに格納します。

ファイルが同時に変更されない場合、読み込まれたバイト数がゼロになったときにファイルの終わりに到達します。

filehandle.readableWebStream([options])#

• options <Object>

  • type <string> | <undefined> 通常のストリームまたは 'bytes' ストリームを開くかどうか。デフォルト: undefined

• 戻り値: <ReadableStream>

ファイルのデータを読み込むために使用できる ReadableStream を返します。

このメソッドが複数回呼び出された場合、または FileHandle が閉じられた後または閉じている途中で呼び出された場合は、エラーがスローされます。

import {
  open,
} from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const chunk of file.readableWebStream())
  console.log(chunk);

await file.close();const {
  open,
} = require('node:fs/promises');

(async () => {
  const file = await open('./some/file/to/read');

  for await (const chunk of file.readableWebStream())
    console.log(chunk);

  await file.close();
})();copy

ReadableStream はファイルを最後まで読み込みますが、FileHandle を自動的に閉じません。ユーザーコードは、引き続き fileHandle.close() メソッドを呼び出す必要があります。

filehandle.readFile(options)#

• options <Object> | <string>
  • encoding <string> | <null> デフォルト: null
  • signal <AbortSignal> 進行中の readFile を中止できるようにします
• 戻り値: <Promise> ファイルの内容で正常に読み込みが完了すると解決されます。エンコーディングが指定されていない場合（options.encodingを使用）、データは <Buffer> オブジェクトとして返されます。それ以外の場合、データは文字列になります。

ファイルの全内容を非同期的に読み込みます。

options が文字列の場合、それは encoding を指定します。

<FileHandle> は読み取りをサポートしている必要があります。

1つ以上の filehandle.read() 呼び出しがファイルハンドルに対して行われ、その後 filehandle.readFile() 呼び出しが行われた場合、データは現在の位置からファイルの終わりまで読み込まれます。必ずしもファイルの先頭から読み込まれるわけではありません。

filehandle.readLines([options])#

• options <Object>
  • encoding <string> デフォルト: null
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024
• 戻り値: <readline.InterfaceConstructor>

readline インターフェースを作成し、ファイル全体をストリーム配信するための便利なメソッドです。オプションについては、filehandle.createReadStream() を参照してください。

import { open } from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const line of file.readLines()) {
  console.log(line);
}const { open } = require('node:fs/promises');

(async () => {
  const file = await open('./some/file/to/read');

  for await (const line of file.readLines()) {
    console.log(line);
  }
})();copy

filehandle.readv(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> データの読み取りを開始するファイルの先頭からのオフセット。position が number でない場合、データは現在の位置から読み込まれます。デフォルト: null
• 戻り値: <Promise> 成功時に、2つのプロパティを含むオブジェクトで解決されます。
  • bytesRead <integer> 読み込まれたバイト数
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers 入力への参照を含むプロパティ。

ファイルから読み取り、<ArrayBufferView> の配列に書き込みます。

filehandle.stat([options])#

• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。
• 戻り値: <Promise> ファイルの <fs.Stats> で解決されます。

filehandle.sync()#

• 戻り値: <Promise> 成功時にundefinedで解決します。

開いているファイル記述子のすべてのデータがストレージデバイスにフラッシュされるように要求します。具体的な実装は、オペレーティングシステムとデバイスに固有です。詳細については、POSIX fsync(2) ドキュメントを参照してください。

filehandle.truncate(len)#

• len <integer> デフォルト: 0
• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルを切り捨てます。

ファイルが len バイトより大きい場合、ファイルの最初の len バイトのみが保持されます。

次の例では、ファイルの最初の4バイトのみを保持します。

import { open } from 'node:fs/promises';

let filehandle = null;
try {
  filehandle = await open('temp.txt', 'r+');
  await filehandle.truncate(4);
} finally {
  await filehandle?.close();
} copy

ファイルが以前に len バイトより短かった場合は拡張され、拡張された部分はヌルバイト ('\0') で埋められます。

len が負の場合、0 が使用されます。

filehandle.utimes(atime, mtime)#

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise>

<FileHandle> で参照されるオブジェクトのファイルシステムのタイムスタンプを変更し、成功時に引数なしで Promise を解決します。

filehandle.write(buffer, offset[, length[, position]])#

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> 書き込むデータの開始位置が buffer 内のどこか。
• length <integer> buffer から書き込むバイト数。デフォルト: buffer.byteLength - offset
• position <integer> | <null> buffer からのデータを書き込むファイルの先頭からのオフセット。position が number でない場合、データは現在の位置に書き込まれます。詳細については、POSIX pwrite(2) ドキュメントを参照してください。デフォルト: null
• 戻り値: <Promise>

buffer をファイルに書き込みます。

Promise は、2つのプロパティを含むオブジェクトで解決されます。

• bytesWritten <integer> 書き込まれたバイト数
• buffer <Buffer> | <TypedArray> | <DataView> 書き込まれた buffer への参照。

Promise が解決 (または拒否) されるのを待たずに、同じファイルで filehandle.write() を複数回使用するのは安全ではありません。このシナリオでは、filehandle.createWriteStream() を使用してください。

Linux では、ファイルが追加モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にデータの最後にデータを追加します。

filehandle.write(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> デフォルト: null
• 戻り値: <Promise>

buffer をファイルに書き込みます。

上記の filehandle.write 関数と同様に、このバージョンではオプションの options オブジェクトを受け取ります。options オブジェクトが指定されていない場合、上記の値がデフォルトになります。

filehandle.write(string[, position[, encoding]])#

• string <string>
• position <整数> | <null> string からのデータを書き込むファイルの先頭からのオフセットです。position が number でない場合、データは現在の位置に書き込まれます。詳細については、POSIX の pwrite(2) ドキュメントを参照してください。デフォルト: null
• encoding <文字列> 予期される文字列エンコーディングです。デフォルト: 'utf8'
• 戻り値: <Promise>

string をファイルに書き込みます。string が文字列でない場合、Promise はエラーでリジェクトされます。

Promise は、2つのプロパティを含むオブジェクトで解決されます。

• bytesWritten <integer> 書き込まれたバイト数
• buffer <文字列> 書き込まれた string への参照です。

Promise が解決 (または拒否) されるのを待たずに、同じファイルで filehandle.write() を複数回使用するのは安全ではありません。このシナリオでは、filehandle.createWriteStream() を使用してください。

Linux では、ファイルが追加モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にデータの最後にデータを追加します。

filehandle.writeFile(data, options)#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <文字列> | <null> data が文字列の場合の予期される文字エンコーディングです。デフォルト: 'utf8'
• 戻り値: <Promise>

非同期的にデータをファイルに書き込みます。ファイルが既に存在する場合は上書きします。data は、文字列、バッファー、<AsyncIterable>、または <Iterable> オブジェクトにすることができます。Promise は成功時に引数なしで解決されます。

options が文字列の場合、それは encoding を指定します。

<FileHandle> は書き込みをサポートする必要があります。

Promise が解決 (またはリジェクト) されるのを待たずに、同じファイルに対して filehandle.writeFile() を複数回使用するのは安全ではありません。

ファイルハンドルに対して 1 回以上の filehandle.write() 呼び出しが行われた後で filehandle.writeFile() 呼び出しが行われた場合、データは現在の位置からファイルの最後まで書き込まれます。必ずしもファイルの先頭から書き込まれるとは限りません。

filehandle.writev(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <整数> | <null> buffers からのデータを書き込むファイルの先頭からのオフセットです。position が number でない場合、データは現在の位置に書き込まれます。デフォルト: null
• 戻り値: <Promise>

<ArrayBufferView> の配列をファイルに書き込みます。

Promise は、2 つのプロパティを含むオブジェクトで解決されます。

• bytesWritten <integer> 書き込まれたバイト数
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers 入力への参照です。

Promise が解決 (またはリジェクト) されるのを待たずに、同じファイルに対して writev() を複数回呼び出すのは安全ではありません。

Linux では、ファイルが追加モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にデータの末尾に追加します。

filehandle[Symbol.asyncDispose]()#

filehandle.close() のエイリアスです。

fsPromises.access(path[, mode])#

• path <文字列> | <Buffer> | <URL>
• mode <整数> デフォルト: fs.constants.F_OK
• 戻り値: <Promise> 成功時にundefinedで解決します。

path で指定されたファイルまたはディレクトリに対するユーザーのアクセス許可をテストします。mode 引数は、実行するアクセス可能性チェックを指定するオプションの整数です。mode は、fs.constants.F_OK の値または、fs.constants.R_OK、fs.constants.W_OK、および fs.constants.X_OK のいずれかのビット単位の OR で構成されるマスクのいずれかである必要があります (例: fs.constants.W_OK | fs.constants.R_OK)。mode の可能な値については、ファイルアクセス定数を確認してください。

アクセス可能性チェックが成功した場合、Promise は値なしで解決されます。アクセス可能性チェックのいずれかが失敗した場合、Promise は <エラー> オブジェクトでリジェクトされます。次の例では、ファイル /etc/passwd を現在のプロセスで読み取りおよび書き込みできるかどうかを確認します。

import { access, constants } from 'node:fs/promises';

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can access');
} catch {
  console.error('cannot access');
} copy

fsPromises.open() を呼び出す前にファイルのアクセス可能性を確認するために fsPromises.access() を使用することはお勧めしません。そうすると、他のプロセスが 2 回の呼び出しの間でファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードはファイルを直接開く/読み取り/書き込みし、ファイルにアクセスできない場合に発生するエラーを処理する必要があります。

fsPromises.appendFile(path, data[, options])#

• path <文字列> | <Buffer> | <URL> | <FileHandle> ファイル名または <FileHandle>
• data <文字列> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <整数> デフォルト: 0o666
  • flag <文字列> ファイルシステムの flags のサポートを参照してください。デフォルト: 'a'.
  • flush <boolean> trueの場合、基盤となるファイル記述子が閉じられる前にフラッシュされます。デフォルト: false。
• 戻り値: <Promise> 成功時にundefinedで解決します。

非同期的にデータをファイルに追加し、ファイルが存在しない場合は作成します。data は、文字列または <Buffer> にすることができます。

options が文字列の場合、それは encoding を指定します。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

path は、追加用に開かれた (fsPromises.open() を使用) <FileHandle> として指定できます。

fsPromises.chmod(path, mode)#

• path <文字列> | <Buffer> | <URL>
• mode <文字列> | <整数>
• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルの権限を変更します。

fsPromises.chown(path, uid, gid)#

• path <文字列> | <Buffer> | <URL>
• uid <整数>
• gid <整数>
• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルの所有権を変更します。

fsPromises.copyFile(src, dest[, mode])#

• src <文字列> | <Buffer> | <URL> コピー元のファイル名
• dest <文字列> | <Buffer> | <URL> コピー操作のコピー先のファイル名
• mode <整数> コピー操作の動作を指定するオプションの修飾子。2 つ以上の値のビット単位の OR で構成されるマスクを作成できます (例: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE)。デフォルト: 0。
  • fs.constants.COPYFILE_EXCL: dest が既に存在する場合、コピー操作は失敗します。
  • fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトの reflink を作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合は、フォールバックコピーメカニズムが使用されます。
  • fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトの reflink を作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。
• 戻り値: <Promise> 成功時にundefinedで解決します。

非同期的に src を dest にコピーします。デフォルトでは、dest が既に存在する場合は上書きされます。

コピー操作のアトミシティについては保証されていません。コピー先のファイルが書き込みのために開かれた後でエラーが発生した場合は、コピー先の削除が試行されます。

import { copyFile, constants } from 'node:fs/promises';

try {
  await copyFile('source.txt', 'destination.txt');
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
}

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
} copy

fsPromises.cp(src, dest[, options])#

• src <文字列> | <URL> コピー元のパス。
• dest <文字列> | <URL> コピー先のパス。
• options <Object>
  • dereference <真偽値> シンボリックリンクを非参照化します。デフォルト: false。
  • errorOnExist <真偽値> force が false で、コピー先が存在する場合、エラーをスローします。デフォルト: false。
  • filter <関数> コピーされたファイル/ディレクトリをフィルタリングする関数。項目をコピーする場合は true を返し、無視する場合は false を返します。ディレクトリを無視すると、そのすべての内容もスキップされます。true または false に解決される Promise を返すこともできます。デフォルト: undefined。
    • src <文字列> コピー元のパス。
    • dest <文字列> コピー先のパス。
    • 戻り値: <真偽値> | <Promise>
  • force <真偽値> 既存のファイルまたはディレクトリを上書きします。この値を false に設定し、コピー先が存在する場合、コピー操作はエラーを無視します。この動作を変更するには、errorOnExist オプションを使用します。デフォルト: true。
  • mode <整数> コピー操作の修飾子。デフォルト: 0。fsPromises.copyFile() の mode フラグを参照してください。
  • preserveTimestamps <真偽値> true の場合、src からのタイムスタンプが保持されます。デフォルト: false。
  • recursive <boolean> ディレクトリを再帰的にコピーします。デフォルト: false
  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決をスキップします。デフォルト: false
• 戻り値: <Promise> 成功時にundefinedで解決します。

src から dest へ、サブディレクトリやファイルを含むディレクトリ構造全体を非同期にコピーします。

あるディレクトリを別のディレクトリへコピーする場合、glob はサポートされず、cp dir1/ dir2/ と同様の動作になります。

fsPromises.lchmod(path, mode)#

• path <文字列> | <Buffer> | <URL>
• mode <integer>
• 戻り値: <Promise> 成功時にundefinedで解決します。

シンボリックリンクのパーミッションを変更します。

このメソッドは macOS でのみ実装されています。

fsPromises.lchown(path, uid, gid)#

• path <文字列> | <Buffer> | <URL>
• uid <整数>
• gid <整数>
• 戻り値: <Promise> 成功時にundefinedで解決します。

シンボリックリンクの所有権を変更します。

fsPromises.lutimes(path, atime, mtime)#

• path <文字列> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise> 成功時にundefinedで解決します。

fsPromises.utimes() と同様にファイルのアクセス時間と変更時間を変更しますが、パスがシンボリックリンクを参照する場合、リンクは間接参照されません。代わりに、シンボリックリンク自体のタイムスタンプが変更されます。

fsPromises.link(existingPath, newPath)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功時にundefinedで解決します。

existingPath から newPath への新しいリンクを作成します。詳細については、POSIX の link(2) ドキュメントを参照してください。

fsPromises.lstat(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。
• 戻り値: <Promise> 指定されたシンボリックリンクの path に対する <fs.Stats> オブジェクトで解決されます。

path がシンボリックリンクを参照する場合を除き、fsPromises.stat() と同等です。その場合、参照先のファイルではなくリンク自体が stat されます。詳細については、POSIX の lstat(2) ドキュメントを参照してください。

fsPromises.mkdir(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。デフォルト: 0o777。
• 戻り値: <Promise> 成功した場合、recursive が false の場合は undefined で解決され、recursive が true の場合は最初に作成されたディレクトリパスで解決されます。

非同期的にディレクトリを作成します。

オプションの options 引数には、mode (パーミッションとスティッキービット) を指定する整数、または親ディレクトリを作成するかどうかを示す mode プロパティと recursive プロパティを持つオブジェクトを指定できます。path が存在するディレクトリであるときに fsPromises.mkdir() を呼び出すと、recursive が false の場合にのみ拒否されます。

import { mkdir } from 'node:fs/promises';

try {
  const projectFolder = new URL('./test/project/', import.meta.url);
  const createDir = await mkdir(projectFolder, { recursive: true });

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}const { mkdir } = require('node:fs/promises');
const { join } = require('node:path');

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project');
  const dirCreation = await mkdir(projectFolder, { recursive: true });

  console.log(dirCreation);
  return dirCreation;
}

makeDirectory().catch(console.error);copy

fsPromises.mkdtemp(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 新しく作成された一時ディレクトリのファイルシステムパスを含む文字列で解決されます。

一意の一時ディレクトリを作成します。一意のディレクトリ名は、指定された prefix の末尾に 6 つのランダムな文字を追加することで生成されます。プラットフォームの不整合のため、prefix の末尾に X 文字を使用しないでください。一部のプラットフォーム (特に BSD) では、6 つ以上のランダムな文字を返し、prefix の末尾の X 文字をランダムな文字に置き換えることができます。

オプションの options 引数には、エンコーディングを指定する文字列、または使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。

import { mkdtemp } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

try {
  await mkdtemp(join(tmpdir(), 'foo-'));
} catch (err) {
  console.error(err);
} copy

fsPromises.mkdtemp() メソッドは、6 つのランダムに選択された文字を prefix 文字列に直接追加します。たとえば、ディレクトリ /tmp がある場合、/tmp *内* に一時ディレクトリを作成するつもりである場合、prefix は末尾にプラットフォーム固有のパス区切り文字 (require('node:path').sep) を付ける必要があります。

fsPromises.open(path, flags[, mode])#

• path <文字列> | <Buffer> | <URL>
• flags <string> | <number> ファイルシステムの flags のサポート を参照してください。デフォルト: 'r'。
• mode <string> | <integer> ファイルが作成される場合、ファイルモード（パーミッションとスティッキービット）を設定します。デフォルト: 0o666 (読み取りおよび書き込み可能)
• 戻り値: <Promise> <FileHandle> オブジェクトで解決されます。

<FileHandle> を開きます。

詳細については、POSIX の open(2) ドキュメントを参照してください。

一部の文字 (< > : " / \ | ? *) は、ファイル、パス、名前空間の命名 に記載されているように、Windows で予約されています。NTFS では、ファイル名にコロンが含まれている場合、Node.js は この MSDN ページ に記載されているように、ファイルシステムストリームを開きます。

fsPromises.opendir(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取るときに内部的にバッファリングされるディレクトリエントリの数。値を大きくするとパフォーマンスは向上しますが、メモリ使用量も増加します。デフォルト: 32
  • recursive <boolean> 解決された Dir は、すべてのサブファイルとディレクトリを含む <AsyncIterable> になります。デフォルト: false
• 戻り値: <Promise> <fs.Dir> で解決されます。

反復スキャン用にディレクトリを非同期に開きます。詳細については、POSIX の opendir(3) ドキュメントを参照してください。

<fs.Dir> を作成します。これには、ディレクトリからの読み取りとクリーンアップのすべての追加機能が含まれています。

encoding オプションは、ディレクトリを開く際と、後続の読み取り操作時の path のエンコーディングを設定します。

非同期イテレーションを使用する例

import { opendir } from 'node:fs/promises';

try {
  const dir = await opendir('./');
  for await (const dirent of dir)
    console.log(dirent.name);
} catch (err) {
  console.error(err);
} copy

非同期イテレータを使用する場合、イテレータが終了した後、<fs.Dir> オブジェクトは自動的に閉じられます。

fsPromises.readdir(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
  • withFileTypes <boolean> デフォルト: false
  • recursive <boolean> true の場合、ディレクトリの内容を再帰的に読み取ります。再帰モードでは、すべてのファイル、サブファイル、およびディレクトリがリストされます。デフォルト: false。
• 戻り値: <Promise> ディレクトリ内のファイルの名前の配列（'.' および '..' を除く）で解決されます。

ディレクトリの内容を読み取ります。

オプションの options 引数には、エンコーディングを指定する文字列、またはファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるファイル名は <Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、返される配列には <fs.Dirent> オブジェクトが含まれます。

import { readdir } from 'node:fs/promises';

try {
  const files = await readdir(path);
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
} copy

fsPromises.readFile(path[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> ファイル名または FileHandle
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: null
  • flag <string> ファイルシステムの flags のサポート を参照してください。デフォルト: 'r'。
  • signal <AbortSignal> 進行中の readFile を中止できるようにします
• 戻り値: <Promise> ファイルの内容で解決されます。

ファイルの全内容を非同期的に読み込みます。

エンコーディングが指定されていない場合 (options.encoding を使用)、データは <Buffer> オブジェクトとして返されます。それ以外の場合、データは文字列になります。

options が文字列の場合、それはエンコーディングを指定します。

path がディレクトリの場合、fsPromises.readFile() の動作はプラットフォームに依存します。macOS、Linux、および Windows では、Promise はエラーで拒否されます。FreeBSD では、ディレクトリの内容の表現が返されます。

実行中のコードと同じディレクトリにある package.json ファイルを読み込む例

import { readFile } from 'node:fs/promises';
try {
  const filePath = new URL('./package.json', import.meta.url);
  const contents = await readFile(filePath, { encoding: 'utf8' });
  console.log(contents);
} catch (err) {
  console.error(err.message);
}const { readFile } = require('node:fs/promises');
const { resolve } = require('node:path');
async function logFile() {
  try {
    const filePath = resolve('./package.json');
    const contents = await readFile(filePath, { encoding: 'utf8' });
    console.log(contents);
  } catch (err) {
    console.error(err.message);
  }
}
logFile();copy

<AbortSignal> を使用して、進行中の readFile を中止することができます。リクエストが中止された場合、返される Promise は AbortError で拒否されます。

import { readFile } from 'node:fs/promises';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const promise = readFile(fileName, { signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
} copy

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるのではなく、内部バッファリングである fs.readFile の実行が中止されます。

指定された <FileHandle> は、読み取りをサポートしている必要があります。

fsPromises.readlink(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 成功時に linkString で解決します。

path で参照されるシンボリックリンクの内容を読み取ります。詳細については、POSIX の readlink(2) ドキュメントを参照してください。Promise は、成功時に linkString で解決します。

オプションの options 引数には、エンコーディングを指定する文字列、または、返されるリンクパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるリンクパスは <Buffer> オブジェクトとして渡されます。

fsPromises.realpath(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• 戻り値: <Promise> 成功時に解決されたパスで解決します。

fs.realpath.native() 関数と同じセマンティクスを使用して、path の実際の場所を決定します。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数には、エンコーディングを指定する文字列、または、パスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

Linux では、Node.js が musl libc にリンクされている場合、この関数が動作するためには、procfs ファイルシステムが /proc にマウントされている必要があります。Glibc にはこの制限はありません。

fsPromises.rename(oldPath, newPath)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功時にundefinedで解決します。

oldPath を newPath に名前変更します。

fsPromises.rmdir(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は、試行ごとに retryDelay ミリ秒ずつ長く線形バックオフ待機で操作を再試行します。このオプションは、再試行の回数を表します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 0。
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。デフォルト: false。非推奨。
  • retryDelay <integer> 再試行の間隔をミリ秒単位で指定します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 100。
• 戻り値: <Promise> 成功時にundefinedで解決します。

path で識別されるディレクトリを削除します。

ファイル (ディレクトリではない) に対して fsPromises.rmdir() を使用すると、Windows では ENOENT エラー、POSIX では ENOTDIR エラーが発生して Promise が拒否されます。

rm -rf Unix コマンドと同様の動作を実現するには、{ recursive: true, force: true } オプションを指定して fsPromises.rm() を使用します。

fsPromises.rm(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • force <boolean> true の場合、path が存在しない場合は例外が無視されます。デフォルト: false。
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は、試行ごとに retryDelay ミリ秒ずつ長く線形バックオフ待機で操作を再試行します。このオプションは、再試行の回数を表します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 0。
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。デフォルト: false。
  • retryDelay <integer> 再試行の間隔をミリ秒単位で指定します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 100。
• 戻り値: <Promise> 成功時にundefinedで解決します。

ファイルとディレクトリを削除します (標準 POSIX rm ユーティリティをモデルにしています)。

fsPromises.stat(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。
• 戻り値: <Promise> 指定された path の <fs.Stats> オブジェクトで解決します。

fsPromises.statfs(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.StatFs> オブジェクトの数値が bigint であるかどうか。デフォルト: false。
• 戻り値: <Promise> 指定された path の <fs.StatFs> オブジェクトで解決します。

fsPromises.symlink(target, path[, type])#

• target <string> | <Buffer> | <URL>
• path <文字列> | <Buffer> | <URL>
• type <string> | <null> デフォルト: null
• 戻り値: <Promise> 成功時にundefinedで解決します。

シンボリックリンクを作成します。

type 引数は、Windows プラットフォームでのみ使用され、'dir'、'file'、または 'junction' のいずれかになります。type 引数が文字列でない場合、Node.js は target のタイプを自動検出し、'file' または 'dir' を使用します。target が存在しない場合は、'file' が使用されます。Windows のジャンクションポイントには、絶対パスの宛先パスが必要です。'junction' を使用する場合、target 引数は自動的に絶対パスに正規化されます。NTFS ボリュームのジャンクションポイントは、ディレクトリのみを指すことができます。

fsPromises.truncate(path[, len])#

• path <文字列> | <Buffer> | <URL>
• len <integer> デフォルト: 0
• 戻り値: <Promise> 成功時にundefinedで解決します。

path のコンテンツを len バイトに切り詰めます (短縮または延長)。

fsPromises.unlink(path)#

• path <文字列> | <Buffer> | <URL>
• 戻り値: <Promise> 成功時にundefinedで解決します。

path がシンボリックリンクを参照している場合、リンクが参照しているファイルまたはディレクトリに影響を与えることなくリンクが削除されます。path がシンボリックリンクではないファイルパスを参照している場合、ファイルは削除されます。詳細については、POSIX の unlink(2) ドキュメントを参照してください。

fsPromises.utimes(path, atime, mtime)#

• path <文字列> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise> 成功時にundefinedで解決します。

path で参照されるオブジェクトのファイルシステムタイムスタンプを変更します。

atime および mtime 引数は、次のルールに従います。

• 値には、Unix エポック時間を表す数値、Date、または '123456789.0' のような数値文字列を使用できます。
• 値を数値に変換できない場合、または NaN、Infinity、または -Infinity の場合は、Error がスローされます。

fsPromises.watch(filename[, options])#

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> ファイルが監視されている間、プロセスを実行し続けるかどうかを示します。デフォルト: true。
  • recursive <boolean> すべてのサブディレクトリを監視するか、現在のディレクトリのみを監視するかを示します。これは、ディレクトリが指定されている場合に適用され、サポートされているプラットフォームでのみ適用されます（注意点を参照）。デフォルト: false。
  • encoding <string> リスナーに渡されるファイル名に使用する文字エンコーディングを指定します。デフォルト: 'utf8'。
  • signal <AbortSignal> ウォッチャーを停止するタイミングを通知するために使用される<AbortSignal>。
• 戻り値: プロパティを持つオブジェクトの<AsyncIterator>
  • eventType <string> 変更の種類
  • filename <string> | <Buffer> | <null> 変更されたファイルの名前。

filename（ファイルまたはディレクトリ）の変更を監視する非同期イテレータを返します。

const { watch } = require('node:fs/promises');

const ac = new AbortController();
const { signal } = ac;
setTimeout(() => ac.abort(), 10000);

(async () => {
  try {
    const watcher = watch(__filename, { signal });
    for await (const event of watcher)
      console.log(event);
  } catch (err) {
    if (err.name === 'AbortError')
      return;
    throw err;
  }
})(); copy

ほとんどのプラットフォームでは、ディレクトリ内でファイル名が表示または非表示になるたびに、'rename'が発行されます。

fs.watch()の注意点はすべてfsPromises.watch()にも適用されます。

fsPromises.writeFile(file, data[, options])#

• file <string> | <Buffer> | <URL> | <FileHandle> ファイル名またはFileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <整数> デフォルト: 0o666
  • flag <string> ファイルシステムのflagsのサポートを参照してください。デフォルト: 'w'。
  • flush <boolean> すべてのデータがファイルに正常に書き込まれ、flushがtrueの場合、filehandle.sync()がデータのフラッシュに使用されます。デフォルト: false。
  • signal <AbortSignal> 進行中のwriteFileを中止できます。
• 戻り値: <Promise> 成功時にundefinedで解決します。

非同期的にデータをファイルに書き込み、ファイルが存在する場合は置き換えます。dataには、文字列、バッファー、<AsyncIterable>、または<Iterable>オブジェクトを指定できます。

dataがバッファーの場合、encodingオプションは無視されます。

options が文字列の場合、それはエンコーディングを指定します。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

指定された<FileHandle>は、書き込みをサポートしている必要があります。

プロミスが解決されるのを待たずに、同じファイルに対してfsPromises.writeFile()を複数回使用することは安全ではありません。

fsPromises.readFileと同様に、fsPromises.writeFileは、渡されたバッファーを書き込むために内部で複数のwrite呼び出しを実行する便利なメソッドです。パフォーマンスが重要なコードの場合は、fs.createWriteStream()またはfilehandle.createWriteStream()の使用を検討してください。

<AbortSignal>を使用してfsPromises.writeFile()をキャンセルできます。キャンセルは「ベストエフォート」であり、ある程度のデータは書き込まれる可能性があります。

import { writeFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const data = new Uint8Array(Buffer.from('Hello Node.js'));
  const promise = writeFile('message.txt', data, { signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
} copy

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストは中止されず、fs.writeFileが実行する内部バッファリングが中止されます。

fsPromises.constants#

• <Object>

ファイルシステム操作で一般的に使用される定数を含むオブジェクトを返します。オブジェクトはfs.constantsと同じです。詳細については、FS定数を参照してください。

コールバックAPI#

コールバックAPIは、イベントループをブロックせずにすべて非同期的に操作を実行し、完了またはエラー時にコールバック関数を呼び出します。

コールバックAPIは、基盤となるNode.jsスレッドプールを使用して、イベントループスレッドから離れた場所でファイルシステム操作を実行します。これらの操作は同期されておらず、スレッドセーフではありません。同じファイルに対して複数の同時変更を実行する場合は、データが破損する可能性があるため、注意が必要です。

fs.access(path[, mode], callback)#

• path <文字列> | <Buffer> | <URL>
• mode <整数> デフォルト: fs.constants.F_OK
• callback <Function>
  • err <Error>

path で指定されたファイルまたはディレクトリに対するユーザーのアクセス許可をテストします。mode 引数は、実行するアクセス可能性チェックを指定するオプションの整数です。mode は、fs.constants.F_OK の値または、fs.constants.R_OK、fs.constants.W_OK、および fs.constants.X_OK のいずれかのビット単位の OR で構成されるマスクのいずれかである必要があります (例: fs.constants.W_OK | fs.constants.R_OK)。mode の可能な値については、ファイルアクセス定数を確認してください。

最後の引数callbackは、発生した可能性のあるエラー引数とともに呼び出されるコールバック関数です。アクセシビリティチェックのいずれかが失敗した場合、エラー引数はErrorオブジェクトになります。次の例では、package.jsonが存在するかどうか、および読み取り可能か書き込み可能かどうかをチェックします。

import { access, constants } from 'node:fs';

const file = 'package.json';

// Check if the file exists in the current directory.
access(file, constants.F_OK, (err) => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});

// Check if the file is readable.
access(file, constants.R_OK, (err) => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`);
});

// Check if the file is writable.
access(file, constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});

// Check if the file is readable and writable.
access(file, constants.R_OK | constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
}); copy

fs.access()を使用して、fs.open()、fs.readFile()、またはfs.writeFile()を呼び出す前にファイルのアクセシビリティをチェックしないでください。そうすると、他のプロセスが2つの呼び出しの間にファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードはファイルを直接開く/読み取り/書き込みし、ファイルにアクセスできない場合に発生するエラーを処理する必要があります。

書き込み（非推奨）

import { access, open, close } from 'node:fs';

access('myfile', (err) => {
  if (!err) {
    console.error('myfile already exists');
    return;
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err;

    try {
      writeMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
}); copy

書き込み（推奨）

import { open, close } from 'node:fs';

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

読み取り（非推奨）

import { access, open, close } from 'node:fs';
access('myfile', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err;

    try {
      readMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
}); copy

読み取り（推奨）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

上記の「非推奨」の例では、アクセシビリティをチェックしてからファイルを使用しています。「推奨」の例の方が、ファイルを直接使用してエラー（ある場合）を処理するため、より適切です。

一般に、ファイルを使用しない場合、たとえば、そのアクセシビリティが別のプロセスからの信号である場合にのみ、ファイルのアクセシビリティをチェックしてください。

Windowsでは、ディレクトリのアクセス制御ポリシー（ACL）によって、ファイルまたはディレクトリへのアクセスが制限される場合があります。ただし、fs.access()関数はACLをチェックしないため、ACLによってユーザーが読み取りまたは書き込みを制限されている場合でも、パスにアクセス可能であると報告する場合があります。

fs.appendFile(path, data[, options], callback)#

• path <string> | <Buffer> | <URL> | <number> ファイル名またはファイルディスクリプター
• data <文字列> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <整数> デフォルト: 0o666
  • flag <文字列> ファイルシステムの flags のサポートを参照してください。デフォルト: 'a'.
  • flush <boolean> trueの場合、基盤となるファイル記述子が閉じられる前にフラッシュされます。デフォルト: false。
• callback <Function>
  • err <Error>

非同期的にデータをファイルに追加し、ファイルが存在しない場合は作成します。data は、文字列または <Buffer> にすることができます。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', (err) => {
  if (err) throw err;
  console.log('The "data to append" was appended to file!');
}); copy

optionsが文字列の場合、エンコーディングを指定します。

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', 'utf8', callback); copy

pathは、（fs.open()またはfs.openSync()を使用して）追加用に開かれている数値ファイルディスクリプターとして指定できます。ファイルディスクリプターは自動的に閉じられません。

import { open, close, appendFile } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err;

  try {
    appendFile(fd, 'data to append', 'utf8', (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    throw err;
  }
}); copy

fs.chmod(path, mode, callback)#

• path <文字列> | <Buffer> | <URL>
• mode <文字列> | <整数>
• callback <Function>
  • err <Error>

ファイルの権限を非同期的に変更します。完了コールバックには、発生する可能性のある例外以外の引数は渡されません。

詳細については、POSIX chmod(2)のドキュメントを参照してください。

import { chmod } from 'node:fs';

chmod('my_file.txt', 0o775, (err) => {
  if (err) throw err;
  console.log('The permissions for file "my_file.txt" have been changed!');
}); copy

ファイルモード#

fs.chmod()メソッドとfs.chmodSync()メソッドの両方で使用されるmode引数は、次の定数の論理ORを使用して作成された数値ビットマスクです。

modeを構築する簡単な方法は、3つの8進数（例：765）のシーケンスを使用することです。左端の数字（例では7）は、ファイルの所有者の権限を指定します。中央の数字（例では6）は、グループの権限を指定します。右端の数字（例では5）は、他のユーザーの権限を指定します。

たとえば、8進数値0o765は次のことを意味します。

• 所有者はファイルの読み取り、書き込み、および実行ができます。
• グループはファイルの読み取りと書き込みができます。
• 他のユーザーはファイルの読み取りと実行ができます。

ファイルモードが予期される場所で生の数値を使用する場合、0o777より大きい値を使用すると、一貫して機能するようにサポートされていないプラットフォーム固有の動作が発生する可能性があります。したがって、S_ISVTX、S_ISGID、またはS_ISUIDのような定数はfs.constantsで公開されていません。

注意点: Windowsでは、書き込み権限のみを変更でき、グループ、所有者、または他のユーザーの権限の区別は実装されていません。

fs.chown(path, uid, gid, callback)#

• path <文字列> | <Buffer> | <URL>
• uid <整数>
• gid <整数>
• callback <Function>
  • err <Error>

ファイルの所有者とグループを非同期的に変更します。完了コールバックには、起こりうる例外以外の引数は渡されません。

詳細については、POSIX の chown(2) のドキュメントを参照してください。

fs.close(fd[, callback])#

• fd <整数>
• callback <Function>
  • err <Error>

ファイル記述子を閉じます。完了コールバックには、起こりうる例外以外の引数は渡されません。

他の fs 操作で現在使用中のファイル記述子 (fd) に対して fs.close() を呼び出すと、未定義の動作につながる可能性があります。

詳細については、POSIX の close(2) のドキュメントを参照してください。

fs.copyFile(src, dest[, mode], callback)#

• src <文字列> | <Buffer> | <URL> コピー元のファイル名
• dest <文字列> | <Buffer> | <URL> コピー操作のコピー先のファイル名
• mode <整数> コピー操作の修飾子。デフォルト: 0。
• callback <Function>

src を非同期的に dest にコピーします。デフォルトでは、dest がすでに存在する場合は上書きされます。コールバック関数には、起こりうる例外以外の引数は渡されません。Node.js は、コピー操作のアトミシティについては保証しません。コピー先のファイルが書き込み用に開かれた後にエラーが発生した場合、Node.js はコピー先の削除を試みます。

mode は、コピー操作の動作を指定するオプションの整数です。2 つ以上の値のビット単位の OR で構成されるマスクを作成できます (例: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE)。

• fs.constants.COPYFILE_EXCL: dest が既に存在する場合、コピー操作は失敗します。
• fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトの reflink を作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合は、フォールバックコピーメカニズムが使用されます。
• fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトの reflink を作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。

import { copyFile, constants } from 'node:fs';

function callback(err) {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
}

// destination.txt will be created or overwritten by default.
copyFile('source.txt', 'destination.txt', callback);

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback); copy

fs.cp(src, dest[, options], callback)#

• src <文字列> | <URL> コピー元のパス。
• dest <文字列> | <URL> コピー先のパス。
• options <Object>
  • dereference <真偽値> シンボリックリンクを非参照化します。デフォルト: false。
  • errorOnExist <真偽値> force が false で、コピー先が存在する場合、エラーをスローします。デフォルト: false。
  • filter <関数> コピーされたファイル/ディレクトリをフィルタリングする関数。項目をコピーする場合は true を返し、無視する場合は false を返します。ディレクトリを無視すると、そのすべての内容もスキップされます。true または false に解決される Promise を返すこともできます。デフォルト: undefined。
    • src <文字列> コピー元のパス。
    • dest <文字列> コピー先のパス。
    • 戻り値: <真偽値> | <Promise>
  • force <真偽値> 既存のファイルまたはディレクトリを上書きします。この値を false に設定し、コピー先が存在する場合、コピー操作はエラーを無視します。この動作を変更するには、errorOnExist オプションを使用します。デフォルト: true。
  • mode <整数> コピー操作の修飾子。デフォルト: 0。 fs.copyFile() の mode フラグを参照してください。
  • preserveTimestamps <真偽値> true の場合、src からのタイムスタンプが保持されます。デフォルト: false。
  • recursive <boolean> ディレクトリを再帰的にコピーします。デフォルト: false
  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決をスキップします。デフォルト: false
• callback <Function>

src から dest へ、サブディレクトリやファイルを含むディレクトリ構造全体を非同期にコピーします。

あるディレクトリを別のディレクトリへコピーする場合、glob はサポートされず、cp dir1/ dir2/ と同様の動作になります。

fs.createReadStream(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <文字列> ファイルシステムの flags のサポート を参照してください。デフォルト: 'r'。
  • encoding <string> デフォルト: null
  • fd <整数> | <FileHandle> デフォルト: null
  • mode <整数> デフォルト: 0o666
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024
  • fs <オブジェクト> | <null> デフォルト: null
  • signal <AbortSignal> | <null> デフォルト: null
• 戻り値: <fs.ReadStream>

<stream.Readable>のデフォルトのhighWaterMarkである16KiBとは異なり、このメソッドによって返されるストリームのデフォルトのhighWaterMarkは64KiBです。

options には、ファイル全体ではなく、ファイルのバイト範囲を読み取るための start および end の値を含めることができます。start と end は両方とも包括的であり、0 から数え始め、許容値は [0, Number.MAX_SAFE_INTEGER] の範囲です。fd が指定され、start が省略または undefined の場合、fs.createReadStream() は現在のファイル位置から順次読み取ります。encoding は、<Buffer> が受け入れる任意のものを指定できます。

fd が指定されている場合、ReadStream は path 引数を無視し、指定されたファイル記述子を使用します。これは、'open' イベントが発行されないことを意味します。fd はブロッキングである必要があります。非ブロッキングの fd は、<net.Socket> に渡す必要があります。

fd が (キーボードやサウンドカードなどの) ブロッキング読み取りのみをサポートする文字デバイスを指している場合、データが利用可能になるまで読み取り操作は完了しません。これにより、プロセスが終了できなくなり、ストリームが自然に閉じられない可能性があります。

デフォルトでは、ストリームは破棄された後に'close'イベントを発行します。この動作を変更するには、emitCloseオプションをfalseに設定します。

fs オプションを提供することにより、open、read、および close の対応する fs 実装を上書きすることができます。fs オプションを提供する場合、read の上書きが必要です。fd が提供されていない場合は、open の上書きも必要です。autoClose が true の場合は、close の上書きも必要です。

import { createReadStream } from 'node:fs';

// Create a stream from some character device.
const stream = createReadStream('/dev/input/event0');
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

autoCloseがfalseの場合、エラーが発生した場合でもファイル記述子は閉じられません。それを閉じ、ファイル記述子のリークがないことを確認するのはアプリケーションの責任です。autoCloseがtrue（デフォルトの動作）に設定されている場合、'error'または'end'でファイル記述子が自動的に閉じられます。

mode はファイル モード (パーミッションとスティッキー ビット) を設定しますが、ファイルが作成された場合に限ります。

100バイトのファイルの最後の10バイトを読み取る例

import { createReadStream } from 'node:fs';

createReadStream('sample.txt', { start: 90, end: 99 }); copy

options が文字列の場合、それはエンコーディングを指定します。

fs.createWriteStream(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <文字列> ファイルシステムの flags のサポート を参照してください。デフォルト: 'w'。
  • encoding <string> デフォルト: 'utf8'
  • fd <整数> | <FileHandle> デフォルト: null
  • mode <整数> デフォルト: 0o666
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • fs <オブジェクト> | <null> デフォルト: null
  • signal <AbortSignal> | <null> デフォルト: null
  • highWaterMark <number> デフォルト: 16384
  • flush <boolean> trueの場合、基盤となるファイル記述子が閉じられる前にフラッシュされます。デフォルト: false。
• 戻り値: <fs.WriteStream>

options には、ファイルの先頭より後の位置にデータを書き込むことができる start オプションを含めることもできます。許容値は [0, Number.MAX_SAFE_INTEGER] の範囲です。ファイルを置換するのではなく変更する場合は、flags オプションをデフォルトの w ではなく r+ に設定する必要がある場合があります。encoding は、<Buffer> が受け入れる任意のものを指定できます。

autoCloseがtrue（デフォルトの動作）に設定されている場合、'error'または'finish'でファイル記述子が自動的に閉じられます。autoCloseがfalseの場合、エラーが発生した場合でもファイル記述子は閉じられません。それを閉じ、ファイル記述子のリークがないことを確認するのはアプリケーションの責任です。

デフォルトでは、ストリームは破棄された後に'close'イベントを発行します。この動作を変更するには、emitCloseオプションをfalseに設定します。

fs オプションを提供することにより、open、write、writev、および close の対応する fs 実装を上書きすることができます。writev() なしで write() を上書きすると、一部の最適化 (_writev()) が無効になるため、パフォーマンスが低下する可能性があります。fs オプションを提供する場合、少なくとも write と writev のどちらかの上書きが必要です。fd オプションが提供されていない場合は、open の上書きも必要です。autoClose が true の場合は、close の上書きも必要です。

<fs.ReadStream> と同様に、fd が指定されている場合、<fs.WriteStream> は path 引数を無視し、指定されたファイル記述子を使用します。これは、'open' イベントが発行されないことを意味します。fd はブロッキングである必要があります。非ブロッキングの fd は、<net.Socket> に渡す必要があります。

options が文字列の場合、それはエンコーディングを指定します。

fs.exists(path, callback)#

• path <文字列> | <Buffer> | <URL>
• callback <Function>
  • exists <真偽値>

ファイルシステムで確認することにより、指定されたパスが存在するかどうかをテストします。その後、callback 引数を true または false のどちらかで呼び出します。

import { exists } from 'node:fs';

exists('/etc/passwd', (e) => {
  console.log(e ? 'it exists' : 'no passwd!');
}); copy

このコールバックのパラメーターは、他の Node.js コールバックと一致していません。 通常、Node.js コールバックの最初のパラメーターは err パラメーターで、オプションで他のパラメーターが続きます。fs.exists() コールバックには、真偽値のパラメーターが 1 つだけあります。これが、fs.exists() の代わりに fs.access() を推奨する理由の 1 つです。

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前に、fs.exists() を使用してファイルの存在を確認することは推奨されません。そうすると、他のプロセスが 2 回の呼び出しの間でファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードはファイルを直接開く/読み取る/書き込み、ファイルが存在しない場合に発生するエラーを処理する必要があります。

書き込み（非推奨）

import { exists, open, close } from 'node:fs';

exists('myfile', (e) => {
  if (e) {
    console.error('myfile already exists');
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err;

      try {
        writeMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  }
}); copy

書き込み（推奨）

import { open, close } from 'node:fs';
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

読み取り（非推奨）

import { open, close, exists } from 'node:fs';

exists('myfile', (e) => {
  if (e) {
    open('myfile', 'r', (err, fd) => {
      if (err) throw err;

      try {
        readMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  } else {
    console.error('myfile does not exist');
  }
}); copy

読み取り（推奨）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

上記の「推奨されない」例では、存在を確認してからファイルを使用します。一方、「推奨される」例は、ファイルを直接使用し、エラー (存在する場合) を処理するため、より優れています。

一般的に、ファイルの存在を確認するのは、ファイルが直接使用されない場合 (たとえば、その存在が別のプロセスからのシグナルである場合) のみです。

fs.fchmod(fd, mode, callback)#

• fd <整数>
• mode <文字列> | <整数>
• callback <Function>
  • err <Error>

ファイルに対する権限を設定します。完了コールバックには、起こりうる例外以外の引数は渡されません。

詳細については、POSIX の fchmod(2) のドキュメントを参照してください。

fs.fchown(fd, uid, gid, callback)#

• fd <整数>
• uid <整数>
• gid <整数>
• callback <Function>
  • err <Error>

ファイルの所有者を設定します。完了コールバックには、起こりうる例外以外の引数は渡されません。

詳細については、POSIX の fchown(2) のドキュメントを参照してください。

fs.fdatasync(fd, callback)#

• fd <整数>
• callback <Function>
  • err <Error>

ファイルに関連付けられている現在キューに登録されているすべての I/O 操作を、オペレーティング システムの同期 I/O 完了状態に強制します。詳細については、POSIX の fdatasync(2) のドキュメントを参照してください。完了コールバックには、起こりうる例外以外の引数は渡されません。

fs.fstat(fd[, options], callback)#

• fd <整数>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

ファイル記述子の <fs.Stats> を使用してコールバックを呼び出します。

詳細については、POSIX の fstat(2) のドキュメントを参照してください。

fs.fsync(fd, callback)#

• fd <整数>
• callback <Function>
  • err <Error>

オープン ファイル記述子のすべてのデータをストレージ デバイスにフラッシュするように要求します。特定の実装は、オペレーティング システムとデバイスに固有です。詳細については、POSIX の fsync(2) のドキュメントを参照してください。完了コールバックには、起こりうる例外以外の引数は渡されません。

fs.ftruncate(fd[, len], callback)#

• fd <整数>
• len <integer> デフォルト: 0
• callback <Function>
  • err <Error>

ファイル記述子を切り詰めます。完了コールバックには、起こりうる例外以外の引数は渡されません。

詳細については、POSIX の ftruncate(2) のドキュメントを参照してください。

ファイル記述子が参照するファイルが len バイトよりも大きい場合、ファイルの最初の len バイトのみが保持されます。

たとえば、次のプログラムでは、ファイルの最初の 4 バイトのみが保持されます。

import { open, close, ftruncate } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err;

  try {
    ftruncate(fd, 4, (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    if (err) throw err;
  }
}); copy

ファイルが以前に len バイトより短かった場合は拡張され、拡張された部分はヌルバイト ('\0') で埋められます。

len が負の場合、0 が使用されます。

fs.futimes(fd, atime, mtime, callback)#

• fd <整数>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

指定されたファイル記述子が参照するオブジェクトのファイルシステムのタイムスタンプを変更します。fs.utimes()を参照してください。

fs.lchmod(path, mode, callback)#

• path <文字列> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

シンボリックリンクのパーミッションを変更します。完了コールバックには、発生しうる例外以外の引数は渡されません。

このメソッドは macOS でのみ実装されています。

詳細はPOSIXのlchmod(2)ドキュメントを参照してください。

fs.lchown(path, uid, gid, callback)#

• path <文字列> | <Buffer> | <URL>
• uid <整数>
• gid <整数>
• callback <Function>
  • err <Error>

シンボリックリンクの所有者を設定します。完了コールバックには、発生しうる例外以外の引数は渡されません。

詳細はPOSIXのlchown(2)ドキュメントを参照してください。

fs.lutimes(path, atime, mtime, callback)#

• path <文字列> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

fs.utimes()と同じようにファイルのアクセス時間と変更時間を変更しますが、パスがシンボリックリンクを参照する場合、リンクは非参照化されません。代わりに、シンボリックリンク自体のタイムスタンプが変更されます。

完了コールバックには、発生しうる例外以外の引数は渡されません。

fs.link(existingPath, newPath, callback)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

existingPathからnewPathへの新しいリンクを作成します。詳細はPOSIXのlink(2)ドキュメントを参照してください。完了コールバックには、発生しうる例外以外の引数は渡されません。

fs.lstat(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

パスで参照されるシンボリックリンクの<fs.Stats>を取得します。コールバックは、2つの引数 (err, stats) を受け取ります。ここで stats は<fs.Stats>オブジェクトです。lstat() は stat() と同じですが、path がシンボリックリンクの場合、参照先のファイルではなく、リンク自体が stat されます。

詳細はPOSIXのlstat(2)ドキュメントを参照してください。

fs.mkdir(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。デフォルト: 0o777。
• callback <Function>
  • err <Error>
  • path <string> | <undefined> ディレクトリが recursive を true に設定して作成された場合にのみ存在します。

非同期的にディレクトリを作成します。

コールバックには、発生しうる例外と、recursive が true の場合は、最初に作成されたディレクトリパス、(err[, path]) が渡されます。recursive が true の場合でも、ディレクトリが作成されなかった (たとえば、以前に作成されていた場合) 場合、path は undefined になることがあります。

オプションの options 引数は、mode (パーミッションとスティッキービット) を指定する整数、または親ディレクトリを作成するかどうかを示す mode プロパティと recursive プロパティを持つオブジェクトにすることができます。path が存在するディレクトリの場合に fs.mkdir() を呼び出すと、recursive が false の場合にのみエラーが発生します。recursive が false でディレクトリが存在する場合、EEXIST エラーが発生します。

import { mkdir } from 'node:fs';

// Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist.
mkdir('./tmp/a/apple', { recursive: true }, (err) => {
  if (err) throw err;
}); copy

Windows では、再帰を使用してもルートディレクトリで fs.mkdir() を使用するとエラーが発生します

import { mkdir } from 'node:fs';

mkdir('/', { recursive: true }, (err) => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
}); copy

詳細はPOSIXのmkdir(2)ドキュメントを参照してください。

fs.mkdtemp(prefix[, options], callback)#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • err <Error>
  • directory <string>

一意な一時ディレクトリを作成します。

一意な一時ディレクトリを作成するために、必須の prefix の後ろに付加される 6 つのランダムな文字を生成します。プラットフォームの不整合のため、prefix の末尾に X 文字を使用することは避けてください。一部のプラットフォーム、特にBSDでは、6つ以上のランダムな文字を返し、prefix の末尾の X 文字をランダムな文字に置き換えることができます。

作成されたディレクトリパスは、コールバックの2番目のパラメータとして文字列で渡されます。

オプションの options 引数には、エンコーディングを指定する文字列、または使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。

import { mkdtemp } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
}); copy

fs.mkdtemp() メソッドは、6つのランダムに選択された文字を prefix 文字列に直接追加します。たとえば、ディレクトリが /tmp の場合、/tmp *内* に一時ディレクトリを作成したい場合は、prefix は末尾にプラットフォーム固有のパス区切り文字 (require('node:path').sep) を付ける必要があります。

import { tmpdir } from 'node:os';
import { mkdtemp } from 'node:fs';

// The parent directory for the new temporary directory
const tmpDir = tmpdir();

// This method is *INCORRECT*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmpabc123`.
  // A new temporary directory is created at the file system root
  // rather than *within* the /tmp directory.
});

// This method is *CORRECT*:
import { sep } from 'node:path';
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmp/abc123`.
  // A new temporary directory is created within
  // the /tmp directory.
}); copy

fs.open(path[, flags[, mode]], callback)#

• path <文字列> | <Buffer> | <URL>
• flags <string> | <number> ファイルシステムの flags のサポート を参照してください。デフォルト: 'r'。
• mode <string> | <integer> デフォルト: 0o666 (読み書き可能)
• callback <Function>
  • err <Error>
  • fd <整数>

非同期ファイルオープン。詳細はPOSIXのopen(2)ドキュメントを参照してください。

mode は、ファイルが作成された場合にのみファイルモード (パーミッションとスティッキービット) を設定します。Windowsでは、書き込みパーミッションのみを操作できます。fs.chmod()を参照してください。

コールバックは2つの引数 (err, fd) を受け取ります。

一部の文字 (< > : " / \ | ? *) は、ファイル、パス、名前空間の命名 に記載されているように、Windows で予約されています。NTFS では、ファイル名にコロンが含まれている場合、Node.js は この MSDN ページ に記載されているように、ファイルシステムストリームを開きます。

fs.open() に基づく関数も同様の動作をします。fs.writeFile()、fs.readFile() など。

fs.openAsBlob(path[, options])#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • type <string> Blob のオプションの mime タイプ。
• 戻り値: <Promise> 成功すると、<Blob> で解決されます。

データが指定されたファイルによって裏付けられる<Blob>を返します。

ファイルは、<Blob> が作成された後に変更してはなりません。変更を加えると、<Blob> データの読み取りが DOMException エラーで失敗します。Blob が作成されたとき、およびディスク上でファイルデータが変更されたかどうかを検出するために各読み取りの前に、ファイルに対して同期 stat 操作が行われます。

import { openAsBlob } from 'node:fs';

const blob = await openAsBlob('the.file.txt');
const ab = await blob.arrayBuffer();
blob.stream();const { openAsBlob } = require('node:fs');

(async () => {
  const blob = await openAsBlob('the.file.txt');
  const ab = await blob.arrayBuffer();
  blob.stream();
})();copy

fs.opendir(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取るときに内部的にバッファリングされるディレクトリエントリの数。値を大きくするとパフォーマンスは向上しますが、メモリ使用量も増加します。デフォルト: 32
  • recursive <boolean> デフォルト: false
• callback <Function>
  • err <Error>
  • dir <fs.Dir>

ディレクトリを非同期的に開きます。詳細はPOSIXのopendir(3)ドキュメントを参照してください。

<fs.Dir> を作成します。これには、ディレクトリからの読み取りとクリーンアップのすべての追加機能が含まれています。

encoding オプションは、ディレクトリを開く際と、後続の読み取り操作時の path のエンコーディングを設定します。

fs.read(fd, buffer, offset, length, position, callback)#

• fd <整数>
• buffer <Buffer> | <TypedArray> | <DataView> データが書き込まれるバッファ。
• offset <integer> buffer 内でデータを書き込む位置。
• length <integer> 読み込むバイト数。
• position <integer> | <bigint> | <null> ファイルの読み込みを開始する位置を指定します。position が null または -1 の場合、データは現在のファイル位置から読み込まれ、ファイル位置が更新されます。position が負でない整数の場合、ファイル位置は変更されません。
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fd で指定されたファイルからデータを読み取ります。

コールバックには、3つの引数 (err, bytesRead, buffer) が渡されます。

ファイルが同時に変更されない場合、読み込まれたバイト数がゼロになったときにファイルの終わりに到達します。

このメソッドがutil.promisify()されたバージョンとして呼び出された場合、bytesRead および buffer プロパティを持つ Object の Promise を返します。

fs.read(fd[, options], callback)#

• fd <整数>
• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> デフォルト: Buffer.alloc(16384)
  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> デフォルト: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fs.read() 関数と同様に、このバージョンではオプションの options オブジェクトを受け取ります。options オブジェクトが指定されていない場合は、上記の値がデフォルトになります。

fs.read(fd, buffer[, options], callback)#

• fd <整数>
• buffer <Buffer> | <TypedArray> | <DataView> データが書き込まれるバッファ。
• options <Object>
  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> デフォルト: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fs.read() 関数と同様に、このバージョンではオプションの options オブジェクトを受け取ります。options オブジェクトが指定されていない場合は、上記の値がデフォルトになります。

fs.readdir(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
  • withFileTypes <boolean> デフォルト: false
  • recursive <boolean> true の場合、ディレクトリの内容を再帰的に読み取ります。再帰モードでは、すべてのファイル、サブファイル、およびディレクトリを一覧表示します。デフォルト: false。
• callback <Function>
  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

ディレクトリの内容を読み取ります。コールバックは (err, files) の2つの引数を受け取ります。ここで、files はディレクトリ内のファイル名の配列であり、'.' と '..' は除外されます。

詳細については、POSIX のreaddir(3)ドキュメントを参照してください。

オプションの options 引数には、エンコーディングを指定する文字列、またはコールバックに渡されるファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるファイル名は<Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、files 配列には <fs.Dirent> オブジェクトが含まれます。

fs.readFile(path[, options], callback)#

• path <string> | <Buffer> | <URL> | <integer> ファイル名またはファイル記述子
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: null
  • flag <string> ファイルシステムの flags のサポート を参照してください。デフォルト: 'r'。
  • signal <AbortSignal> 進行中の readFile を中止できるようにします
• callback <Function>
  • err <Error> | <AggregateError>
  • data <文字列> | <Buffer>

ファイルの全内容を非同期的に読み込みます。

import { readFile } from 'node:fs';

readFile('/etc/passwd', (err, data) => {
  if (err) throw err;
  console.log(data);
}); copy

コールバックには、2つの引数 (err, data) が渡されます。ここで、data はファイルの内容です。

エンコーディングが指定されていない場合、生のバッファが返されます。

optionsが文字列の場合、エンコーディングを指定します。

import { readFile } from 'node:fs';

readFile('/etc/passwd', 'utf8', callback); copy

パスがディレクトリの場合、fs.readFile() および fs.readFileSync() の動作はプラットフォーム固有です。macOS、Linux、およびWindowsでは、エラーが返されます。FreeBSDでは、ディレクトリの内容の表現が返されます。

import { readFile } from 'node:fs';

// macOS, Linux, and Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegal operation on a directory, read <directory>]
});

//  FreeBSD
readFile('<directory>', (err, data) => {
  // => null, <data>
}); copy

AbortSignalを使用して進行中のリクエストを中断することができます。リクエストが中断された場合、コールバックは AbortError と共に呼び出されます。

import { readFile } from 'node:fs';

const controller = new AbortController();
const signal = controller.signal;
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
});
// When you want to abort the request
controller.abort(); copy

fs.readFile() 関数はファイル全体をバッファリングします。メモリコストを最小限に抑えるには、可能な場合は fs.createReadStream() を介したストリーミングを優先してください。

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるのではなく、内部バッファリングである fs.readFile の実行が中止されます。

ファイル記述子#

1. 指定されたファイル記述子は、読み取りをサポートしている必要があります。
2. ファイル記述子が path として指定されている場合、自動的に閉じられることはありません。
3. 読み取りは現在の位置から開始されます。たとえば、ファイルにすでに 'Hello World' があり、ファイル記述子で6バイトが読み取られた場合、同じファイル記述子で fs.readFile() を呼び出すと、'Hello World' ではなく 'World' が返されます。

パフォーマンスに関する考慮事項#

fs.readFile() メソッドは、ファイルのコンテンツを一度に1チャンクずつメモリに非同期的に読み込み、各チャンクの間でイベントループを回転させることができます。これにより、読み取り操作が、基盤となるlibuvスレッドプールを使用している可能性のある他のアクティビティへの影響を軽減できますが、完全なファイルをメモリに読み込むのに時間がかかることを意味します。

追加の読み取りオーバーヘッドは、システムによって大きく異なり、読み取られるファイルの種類によって異なります。ファイルの種類が通常のファイル（たとえばパイプ）ではなく、Node.jsが実際のファイルサイズを判断できない場合、各読み取り操作は64KiBのデータをロードします。通常のファイルの場合、各読み取りは512 KiBのデータを処理します。

可能な限り高速なファイルコンテンツの読み取りを必要とするアプリケーションの場合、fs.read() を直接使用し、アプリケーションコードがファイル全体のコンテンツの読み取りを管理する方が適切です。

Node.js GitHub issue #25741 には、異なるNode.jsバージョンでの複数のファイルサイズの fs.readFile() のパフォーマンスに関する詳細な情報と分析が記載されています。

fs.readlink(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • err <Error>
  • linkString <string> | <Buffer>

path で参照されるシンボリックリンクの内容を読み取ります。コールバックは (err, linkString) の2つの引数を受け取ります。

詳細については、POSIX の readlink(2) ドキュメントを参照してください。

オプションの options 引数には、エンコーディングを指定する文字列、またはコールバックに渡されるリンクパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるリンクパスは <Buffer> オブジェクトとして渡されます。

fs.readv(fd, buffers[, position], callback)#

• fd <整数>
• buffers <ArrayBufferView[]>
• position <integer> | <null> デフォルト: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

readv()を使用して、fdで指定されたファイルから読み取り、ArrayBufferViewの配列に書き込みます。

positionは、ファイルの先頭からデータを読み取る必要があるオフセットです。typeof position !== 'number'の場合、データは現在の位置から読み取られます。

コールバックには、3つの引数 err、bytesRead、およびbuffersが渡されます。bytesReadはファイルから読み取られたバイト数です。

このメソッドがutil.promisify()されたバージョンとして呼び出された場合、bytesReadとbuffersプロパティを持つObjectのPromiseを返します。

fs.realpath(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

.、..、およびシンボリックリンクを解決することにより、標準的なパス名を非同期的に計算します。

標準的なパス名は必ずしも一意ではありません。ハードリンクとバインドマウントは、多くのパス名を介してファイルシステムエンティティを公開できます。

この関数は、realpath(3)のように動作しますが、いくつかの例外があります

1. 大文字と小文字を区別しないファイルシステムでは、大文字と小文字の変換は実行されません。

2. シンボリックリンクの最大数はプラットフォームに依存せず、通常、ネイティブの realpath(3) 実装がサポートするよりも（はるかに）高くなっています。

callback は (err, resolvedPath) の2つの引数を受け取ります。相対パスを解決するために process.cwd を使用する場合があります。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数には、エンコーディングを指定する文字列、またはコールバックに渡されるパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

path がソケットまたはパイプに解決される場合、関数はそのオブジェクトのシステム依存の名前を返します。

fs.realpath.native(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

非同期 realpath(3)。

callback は (err, resolvedPath) の2つの引数を受け取ります。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数には、エンコーディングを指定する文字列、またはコールバックに渡されるパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

Linux では、Node.js が musl libc にリンクされている場合、この関数が動作するためには、procfs ファイルシステムが /proc にマウントされている必要があります。Glibc にはこの制限はありません。

fs.rename(oldPath, newPath, callback)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

oldPath のファイルを、newPath として指定されたパス名に非同期的に名前変更します。newPath がすでに存在する場合、上書きされます。newPath にディレクトリがある場合、代わりにエラーが発生します。完了コールバックには、可能性のある例外以外の引数は渡されません。

参照: rename(2)。

import { rename } from 'node:fs';

rename('oldFile.txt', 'newFile.txt', (err) => {
  if (err) throw err;
  console.log('Rename complete!');
}); copy

fs.rmdir(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は、試行ごとに retryDelay ミリ秒ずつ長く線形バックオフ待機で操作を再試行します。このオプションは、再試行の回数を表します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 0。
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。デフォルト: false。非推奨。
  • retryDelay <integer> 再試行の間隔をミリ秒単位で指定します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 100。
• callback <Function>
  • err <Error>

非同期rmdir(2)。完了コールバックには、可能性のある例外以外の引数は渡されません。

ファイル（ディレクトリではない）でfs.rmdir()を使用すると、WindowsではENOENTエラーが発生し、POSIXではENOTDIRエラーが発生します。

rm -rfUnixコマンドと同様の動作を実現するには、オプション{ recursive: true, force: true }を指定してfs.rm()を使用します。

fs.rm(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • force <boolean> true の場合、path が存在しない場合は例外が無視されます。デフォルト: false。
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は、試行ごとに retryDelay ミリ秒ずつ長く線形バックオフ待機で操作を再試行します。このオプションは、再試行の回数を表します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 0。
  • recursive <boolean> trueの場合、再帰的な削除を実行します。再帰モードでは、失敗時に操作が再試行されます。デフォルト: false。
  • retryDelay <integer> 再試行の間隔をミリ秒単位で指定します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 100。
• callback <Function>
  • err <Error>

ファイルとディレクトリを非同期的に削除します（標準のPOSIX rmユーティリティに基づいてモデル化されています）。完了コールバックには、可能性のある例外以外の引数は渡されません。

fs.stat(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

非同期 stat(2)。コールバックは (err, stats) の2つの引数を受け取ります。ここで、stats は <fs.Stats> オブジェクトです。

エラーの場合、err.code は Common System Errors のいずれかになります。

fs.stat() はシンボリックリンクに従います。リンク自体を確認するには、fs.lstat() を使用してください。

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前に、ファイルの存在を確認するために fs.stat() を使用することは推奨されません。代わりに、ユーザーコードはファイルを直接開く/読み取る/書き込み、ファイルが利用できない場合に発生するエラーを処理する必要があります。

後で操作せずにファイルの存在を確認するには、fs.access() をお勧めします。

たとえば、次のディレクトリ構造があるとします

- txtDir
-- file.txt
- app.js copy

次のプログラムは、指定されたパスの統計情報を確認します

import { stat } from 'node:fs';

const pathsToCheck = ['./txtDir', './txtDir/file.txt'];

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory());
    console.log(stats);
  });
} copy

結果の出力は次のようになります

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
} copy

fs.statfs(path[, options], callback)#

• path <文字列> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返される <fs.StatFs> オブジェクトの数値が bigint であるかどうか。デフォルト: false。
• callback <Function>
  • err <Error>
  • stats <fs.StatFs>

非同期 statfs(2)。path を含むマウントされたファイルシステムに関する情報を返します。コールバックは (err, stats) の2つの引数を受け取ります。ここで、stats は <fs.StatFs> オブジェクトです。

エラーの場合、err.code は Common System Errors のいずれかになります。

fs.symlink(target, path[, type], callback)#

• target <string> | <Buffer> | <URL>
• path <文字列> | <Buffer> | <URL>
• type <string> | <null> デフォルト: null
• callback <Function>
  • err <Error>

target を指す path という名前のリンクを作成します。完了コールバックには、発生する可能性のある例外以外に引数は渡されません。

詳細については、POSIX の symlink(2) ドキュメントを参照してください。

type 引数は Windows でのみ利用可能で、他のプラットフォームでは無視されます。'dir'、'file'、または 'junction' に設定できます。type 引数が文字列でない場合、Node.js は target の型を自動検出し、'file' または 'dir' を使用します。target が存在しない場合は、'file' が使用されます。Windows のジャンクションポイントは、宛先パスが絶対パスである必要があります。'junction' を使用する場合、target 引数は自動的に絶対パスに正規化されます。NTFS ボリューム上のジャンクションポイントは、ディレクトリのみを指すことができます。

相対ターゲットは、リンクの親ディレクトリに対する相対パスです。

import { symlink } from 'node:fs';

symlink('./mew', './mewtwo', callback); copy

上記の例では、同じディレクトリ内の mew を指すシンボリックリンク mewtwo を作成します。

$ tree .
.
├── mew
└── mewtwo -> ./mew copy

fs.truncate(path[, len], callback)#

• path <文字列> | <Buffer> | <URL>
• len <integer> デフォルト: 0
• callback <Function>
  • err <Error> | <AggregateError>

ファイルを切り詰めます。完了コールバックには、発生する可能性のある例外以外に引数は渡されません。ファイル記述子を最初の引数として渡すこともできます。この場合、fs.ftruncate() が呼び出されます。

import { truncate } from 'node:fs';
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});const { truncate } = require('node:fs');
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});copy

ファイル記述子の受け渡しは非推奨であり、将来的にエラーがスローされる可能性があります。

詳細については、POSIX の truncate(2) ドキュメントを参照してください。

fs.unlink(path, callback)#

• path <文字列> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

ファイルまたはシンボリックリンクを非同期的に削除します。完了コールバックには、発生する可能性のある例外以外に引数は渡されません。

import { unlink } from 'node:fs';
// Assuming that 'path/file.txt' is a regular file.
unlink('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was deleted');
}); copy

fs.unlink() は、空であるかどうかにかかわらず、ディレクトリでは機能しません。ディレクトリを削除するには、fs.rmdir() を使用してください。

詳細については、POSIX の unlink(2) ドキュメントを参照してください。

fs.unwatchFile(filename[, listener])#

• filename <string> | <Buffer> | <URL>
• listener <Function> オプション。以前に fs.watchFile() を使用してアタッチされたリスナー。

filename での変更の監視を停止します。listener が指定されている場合は、その特定のリスナーのみが削除されます。それ以外の場合は、すべて のリスナーが削除され、実質的に filename の監視が停止します。

監視されていないファイル名で fs.unwatchFile() を呼び出すことは、エラーではなく、何もしない操作です。

fs.watch() を使用する方が、fs.watchFile() および fs.unwatchFile() よりも効率的です。可能な場合は、fs.watchFile() および fs.unwatchFile() の代わりに fs.watch() を使用する必要があります。

fs.utimes(path, atime, mtime, callback)#

• path <文字列> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

path で参照されるオブジェクトのファイルシステムタイムスタンプを変更します。

atime および mtime 引数は、次のルールに従います。