Dateisystem

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/fs.js

Das Modul node:fs ermöglicht die Interaktion mit dem Dateisystem auf eine Art und Weise, die an Standard-POSIX-Funktionen angelehnt ist.

Zur Verwendung der Promise-basierten APIs:

ESM

import * as fs from 'node:fs/promises'

CJS

const fs = require('node:fs/promises')

Zur Verwendung der Callback- und synchronen APIs:

ESM

import * as fs from 'node:fs'

CJS

const fs = require('node:fs')

Alle Dateisystemoperationen haben synchrone, Callback- und Promise-basierte Formen und sind sowohl mit CommonJS-Syntax als auch mit ES6-Modulen (ESM) zugänglich.

Promise-Beispiel

Promise-basierte Operationen geben ein Promise zurück, das erfüllt wird, wenn die asynchrone Operation abgeschlossen ist.

ESM

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)
}

CJS

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')

Callback-Beispiel

Die Callback-Form nimmt eine Completion-Callback-Funktion als letztes Argument entgegen und ruft die Operation asynchron auf. Die an den Completion-Callback übergebenen Argumente hängen von der Methode ab, aber das erste Argument ist immer für eine Ausnahme reserviert. Wenn die Operation erfolgreich abgeschlossen wurde, ist das erste Argument null oder undefined.

ESM

import { unlink } from 'node:fs'

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

CJS

const { unlink } = require('node:fs')

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

Die callback-basierten Versionen der node:fs-Modul-APIs sind den Promise-APIs vorzuziehen, wenn maximale Leistung (sowohl in Bezug auf Ausführungszeit als auch Speicherzuweisung) erforderlich ist.

Synchrones Beispiel

Die synchronen APIs blockieren die Node.js-Ereignisschleife und die weitere JavaScript-Ausführung, bis der Vorgang abgeschlossen ist. Ausnahmen werden sofort ausgelöst und können mit try…catch behandelt oder weitergegeben werden.

ESM

import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('Datei /tmp/hello erfolgreich gelöscht')
} catch (err) {
  // Fehlerbehandlung
}

CJS

const { unlinkSync } = require('node:fs')

try {
  unlinkSync('/tmp/hello')
  console.log('Datei /tmp/hello erfolgreich gelöscht')
} catch (err) {
  // Fehlerbehandlung
}

Promises API

[Verlauf]

Version	Änderungen
v14.0.0	Verfügbar als require('fs/promises').
v11.14.0, v10.17.0	Diese API ist nicht mehr experimentell.
v10.1.0	Die API ist nur über require('fs').promises zugänglich.
v10.0.0	Hinzugefügt in: v10.0.0

Die fs/promises API stellt asynchrone Dateisystemmethoden bereit, die Promises zurückgeben.

Die Promise-APIs verwenden den zugrundeliegenden Node.js-Threadpool, um Dateisystemoperationen außerhalb des Ereignisschleifen-Threads auszuführen. Diese Operationen sind nicht synchronisiert oder threadsicher. Vorsicht ist geboten, wenn mehrere gleichzeitige Änderungen an derselben Datei vorgenommen werden, da sonst Datenbeschädigung auftreten kann.

Klasse: FileHandle

Hinzugefügt in: v10.0.0

Ein <FileHandle>-Objekt ist ein Objekt-Wrapper für einen numerischen Dateideskriptor.

Instanzen des <FileHandle>-Objekts werden von der Methode fsPromises.open() erstellt.

Alle <FileHandle>-Objekte sind <EventEmitter>-Objekte.

Wenn ein <FileHandle> nicht mit der Methode filehandle.close() geschlossen wird, versucht es, den Dateideskriptor automatisch zu schließen und eine Prozesswarnung auszugeben, um Speicherlecks zu vermeiden. Verlassen Sie sich nicht auf dieses Verhalten, da es unzuverlässig sein kann und die Datei möglicherweise nicht geschlossen wird. Schließen Sie stattdessen immer explizit <FileHandle>-Objekte. Node.js kann dieses Verhalten in Zukunft ändern.

Ereignis: 'close'

Hinzugefügt in: v15.4.0

Das Ereignis 'close' wird ausgelöst, wenn die <FileHandle> geschlossen wurde und nicht mehr verwendet werden kann.

filehandle.appendFile(data[, options])

[Verlauf]

Version	Änderungen
v21.1.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v15.14.0, v14.18.0	Das Argument data unterstützt AsyncIterable, Iterable und Stream.
v14.0.0	Der Parameter data konvertiert nicht unterstützte Eingaben nicht mehr in Strings.
v10.0.0	Hinzugefügt in: v10.0.0

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> Standard: 'utf8'
  • flush <boolean> Wenn true, wird der zugrunde liegende Datei-Descriptor vor dem Schließen geleert. Standard: false.

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Alias von filehandle.writeFile().

Bei der Arbeit mit Dateihandles kann der Modus nicht von dem geändert werden, der mit fsPromises.open() festgelegt wurde. Daher ist dies äquivalent zu filehandle.writeFile().

filehandle.chmod(mode)

Hinzugefügt in: v10.0.0

• mode <integer> die Datei-Modus-Bitmaske.
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Ändert die Berechtigungen der Datei. Siehe chmod(2).

filehandle.chown(uid, gid)

Hinzugefügt in: v10.0.0

• uid <integer> Die Benutzer-ID des neuen Besitzers der Datei.
• gid <integer> Die Gruppen-ID der neuen Gruppe der Datei.
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Ändert den Besitzer der Datei. Ein Wrapper für chown(2).

filehandle.close()

Hinzugefügt in: v10.0.0

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Schließt den Dateihandle, nachdem auf den Abschluss aller ausstehenden Operationen auf dem Handle gewartet wurde.

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

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

filehandle.createReadStream([options])

Hinzugefügt in: v16.11.0

• options <Object>

  • encoding <string> Standard: null
  • autoClose <boolean> Standard: true
  • emitClose <boolean> Standard: true
  • start <integer>
  • end <integer> Standard: Infinity
  • highWaterMark <integer> Standard: 64 * 1024
  • signal <AbortSignal> | <undefined> Standard: undefined

• Rückgabewert: <fs.ReadStream>

options kann start und end Werte enthalten, um einen Bereich von Bytes aus der Datei zu lesen, anstatt die gesamte Datei. Sowohl start als auch end sind inklusiv und beginnen bei 0, zulässige Werte liegen im Bereich [0, Number.MAX_SAFE_INTEGER]. Wenn start ausgelassen oder undefined ist, liest filehandle.createReadStream() sequentiell von der aktuellen Dateiposition. Die encoding kann eine beliebige der von <Buffer> akzeptierten sein.

Wenn der FileHandle auf ein Zeichengerät zeigt, das nur blockierende Lesevorgänge unterstützt (wie z. B. Tastatur oder Soundkarte), werden Lesevorgänge erst abgeschlossen, wenn Daten verfügbar sind. Dies kann verhindern, dass der Prozess beendet wird und der Stream sich auf natürliche Weise schließt.

Standardmäßig sendet der Stream ein 'close'-Ereignis, nachdem er zerstört wurde. Setzen Sie die Option emitClose auf false, um dieses Verhalten zu ändern.

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

const fd = await open('/dev/input/event0')
// Erstellt einen Stream von einem Zeichengerät.
const stream = fd.createReadStream()
setTimeout(() => {
  stream.close() // Dies schließt den Stream möglicherweise nicht.
  // Künstliches Markieren des Endes des Streams, als ob die zugrunde liegende Ressource
  // selbst das Ende der Datei angezeigt hätte, ermöglicht das Schließen des Streams.
  // Dies bricht ausstehende Lesevorgänge nicht ab, und wenn ein solcher Vorgang vorhanden ist,
  // kann der Prozess möglicherweise erst erfolgreich beendet werden, wenn er abgeschlossen ist.
  stream.push(null)
  stream.read(0)
}, 100)

Wenn autoClose falsch ist, wird der Dateideskriptor nicht geschlossen, selbst wenn ein Fehler auftritt. Es liegt in der Verantwortung der Anwendung, ihn zu schließen und sicherzustellen, dass kein Dateideskriptor-Leck auftritt. Wenn autoClose auf true gesetzt ist (Standardverhalten), wird der Dateideskriptor bei 'error' oder 'end' automatisch geschlossen.

Ein Beispiel zum Lesen der letzten 10 Bytes einer Datei mit einer Länge von 100 Bytes:

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

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

filehandle.createWriteStream([options])

[Verlauf]

Version	Änderungen
v21.0.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v16.11.0	Hinzugefügt in: v16.11.0

• options <Objekt>

  • encoding <Zeichenkette> Standard: 'utf8'
  • autoClose <Boolescher Wert> Standard: true
  • emitClose <Boolescher Wert> Standard: true
  • start <Ganzzahl>
  • highWaterMark <Zahl> Standard: 16384
  • flush <Boolescher Wert> Wenn true, wird der zugrunde liegende Datei-Descriptor vor dem Schließen geleert. Standard: false.

• Rückgabewert: <fs.WriteStream>

options kann auch eine start-Option enthalten, um das Schreiben von Daten an einer Position hinter dem Dateianfang zu ermöglichen. Zulässige Werte liegen im Bereich [0, Number.MAX_SAFE_INTEGER]. Das Ändern einer Datei anstelle des Ersetzens erfordert möglicherweise, dass die flags open-Option auf r+ anstatt auf den Standardwert r gesetzt wird. Die encoding kann eine beliebige der von <Buffer> akzeptierten sein.

Wenn autoClose auf true (Standardverhalten) gesetzt ist, wird der Datei-Descriptor bei 'error' oder 'finish' automatisch geschlossen. Wenn autoClose false ist, wird der Datei-Descriptor nicht geschlossen, selbst wenn ein Fehler auftritt. Es liegt in der Verantwortung der Anwendung, ihn zu schließen und sicherzustellen, dass kein Datei-Descriptor-Leck entsteht.

Standardmäßig sendet der Stream ein 'close'-Ereignis, nachdem er zerstört wurde. Setzen Sie die emitClose-Option auf false, um dieses Verhalten zu ändern.

filehandle.datasync()

Hinzugefügt in: v10.0.0

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Zwingt alle aktuell gepufferten E/A-Operationen, die mit der Datei verknüpft sind, in den synchronisierten E/A-Abschlusszustand des Betriebssystems. Weitere Informationen finden Sie in der POSIX fdatasync(2) Dokumentation.

Im Gegensatz zu filehandle.sync löscht diese Methode keine geänderten Metadaten.

filehandle.fd

Hinzugefügt in: v10.0.0

• <number> Der numerische Dateideskriptor, der vom <FileHandle> Objekt verwaltet wird.

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

[Verlauf]

Version	Änderungen
v21.0.0	Akzeptiert BigInt-Werte als position.
v10.0.0	Hinzugefügt in: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView> Ein Puffer, der mit den gelesenen Dateidaten gefüllt wird.
• offset <integer> Die Position im Puffer, an der mit dem Füllen begonnen werden soll. Standard: 0
• length <integer> Die Anzahl der zu lesenden Bytes. Standard: buffer.byteLength - offset
• position <integer> | <bigint> | <null> Die Position, an der mit dem Lesen von Daten aus der Datei begonnen werden soll. Wenn null oder -1, werden Daten ab der aktuellen Dateiposition gelesen, und die Position wird aktualisiert. Wenn position eine nicht-negative ganze Zahl ist, bleibt die aktuelle Dateiposition unverändert. Standard: null
• Rückgabewert: <Promise> Löst bei Erfolg mit einem Objekt mit zwei Eigenschaften auf:
  • bytesRead <integer> Die Anzahl der gelesenen Bytes
  • buffer <Buffer> | <TypedArray> | <DataView> Ein Verweis auf das übergebene buffer-Argument.

Liest Daten aus der Datei und speichert diese im angegebenen Puffer.

Wenn die Datei nicht gleichzeitig geändert wird, wird das Dateiende erreicht, wenn die Anzahl der gelesenen Bytes Null ist.

filehandle.read([options])

[Versionsgeschichte]

Version	Änderungen
v21.0.0	Akzeptiert BigInt-Werte als position.
v13.11.0, v12.17.0	Hinzugefügt in: v13.11.0, v12.17.0

• options <Object>

  • buffer <Buffer> | <TypedArray> | <DataView> Ein Puffer, der mit den gelesenen Datei-Daten gefüllt wird. Standard: Buffer.alloc(16384)
  • offset <integer> Die Position im Puffer, an der das Füllen beginnen soll. Standard: 0
  • length <integer> Die Anzahl der zu lesenden Bytes. Standard: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Die Position, an der mit dem Lesen von Daten aus der Datei begonnen werden soll. Wenn null oder -1, werden Daten ab der aktuellen Dateiposition gelesen und die Position wird aktualisiert. Wenn position eine nicht-negative ganze Zahl ist, bleibt die aktuelle Dateiposition unverändert. Standard: null

• Rückgabewert: <Promise> Löst bei Erfolg mit einem Objekt mit zwei Eigenschaften auf:

  • bytesRead <integer> Die Anzahl der gelesenen Bytes
  • buffer <Buffer> | <TypedArray> | <DataView> Ein Verweis auf das übergebene buffer-Argument.

Liest Daten aus der Datei und speichert diese im angegebenen Puffer.

Wenn die Datei nicht gleichzeitig geändert wird, wird das Dateiende erreicht, wenn die Anzahl der gelesenen Bytes Null ist.

filehandle.read(buffer[, options])

[Historie]

Version	Änderungen
v21.0.0	Akzeptiert BigInt-Werte als position.
v18.2.0, v16.17.0	Hinzugefügt in: v18.2.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView> Ein Puffer, der mit den gelesenen Dateidaten gefüllt wird.

• options <Object>

  • offset <integer> Die Position im Puffer, an der mit dem Füllen begonnen werden soll. Standard: 0
  • length <integer> Die Anzahl der zu lesenden Bytes. Standard: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Die Position, an der mit dem Lesen von Daten aus der Datei begonnen werden soll. Wenn null oder -1, werden Daten ab der aktuellen Dateiposition gelesen, und die Position wird aktualisiert. Wenn position eine nicht-negative ganze Zahl ist, bleibt die aktuelle Dateiposition unverändert. Standard: null

• Rückgabewert: <Promise> Erfolgreich abgeschlossen mit einem Objekt mit zwei Eigenschaften:

  • bytesRead <integer> Die Anzahl der gelesenen Bytes
  • buffer <Buffer> | <TypedArray> | <DataView> Ein Verweis auf das übergebene buffer-Argument.

Liest Daten aus der Datei und speichert diese im angegebenen Puffer.

Wenn die Datei nicht gleichzeitig geändert wird, wird das Dateiende erreicht, wenn die Anzahl der gelesenen Bytes Null ist.

filehandle.readableWebStream([options])

[Historie]

Version	Änderungen
v20.0.0, v18.17.0	Option zum Erstellen eines 'bytes'-Streams hinzugefügt.
v17.0.0	Hinzugefügt in: v17.0.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• options <Object>

  • type <string> | <undefined> Ob ein normaler oder ein 'bytes'-Stream geöffnet werden soll. Standardwert: undefined

• Gibt zurück: <ReadableStream>

Gibt einen ReadableStream zurück, der zum Lesen der Dateidaten verwendet werden kann.

Ein Fehler wird ausgelöst, wenn diese Methode mehr als einmal aufgerufen wird oder nachdem der FileHandle geschlossen oder im Schließvorgang ist.

ESM

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()

CJS

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()
})()

Während der ReadableStream die Datei vollständig liest, schließt er den FileHandle nicht automatisch. Der Benutzercode muss dennoch die Methode fileHandle.close() aufrufen.

filehandle.readFile(options)

Hinzugefügt in: v10.0.0

• options <Object> | <string>

  • encoding <string> | <null> Standardwert: null
  • signal <AbortSignal> ermöglicht das Abbrechen eines laufenden readFile

• Gibt zurück: <Promise> Löst sich nach einem erfolgreichen Lesevorgang mit dem Inhalt der Datei auf. Wenn keine Codierung angegeben ist (mit options.encoding), werden die Daten als <Buffer>-Objekt zurückgegeben. Andernfalls sind die Daten eine Zeichenkette.

Liest den gesamten Inhalt einer Datei asynchron.

Wenn options eine Zeichenkette ist, gibt diese die encoding an.

Das <FileHandle> muss das Lesen unterstützen.

Wenn ein oder mehrere filehandle.read()-Aufrufe an einem Filehandle durchgeführt werden und dann ein filehandle.readFile()-Aufruf erfolgt, werden die Daten ab der aktuellen Position bis zum Ende der Datei gelesen. Es wird nicht immer vom Anfang der Datei gelesen.

filehandle.readLines([options])

Hinzugefügt in: v18.11.0

• options <Object>

  • encoding <string> Standardwert: null
  • autoClose <boolean> Standardwert: true
  • emitClose <boolean> Standardwert: true
  • start <integer>
  • end <integer> Standardwert: Infinity
  • highWaterMark <integer> Standardwert: 64 * 1024

• Rückgabewert: <readline.InterfaceConstructor>

Hilfsmethode zum Erstellen einer readline-Schnittstelle und zum Streamen über die Datei. Siehe filehandle.createReadStream() für die Optionen.

ESM

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

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

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

CJS

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)
  }
})()

filehandle.readv(buffers[, position])

Hinzugefügt in: v13.13.0, v12.17.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> Der Offset vom Dateianfang, von dem aus die Daten gelesen werden sollen. Wenn position keine number ist, werden die Daten von der aktuellen Position gelesen. Standardwert: null
• Rückgabewert: <Promise> Löst bei Erfolg ein Objekt mit zwei Eigenschaften auf:
  • bytesRead <integer> die Anzahl der gelesenen Bytes
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> Eigenschaft, die einen Verweis auf die Eingabe buffers enthält.

Lesen Sie aus einer Datei und schreiben Sie in ein Array von <ArrayBufferView>s

filehandle.stat([options])

[Versionsgeschichte]

Version	Änderungen
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte bigint sein sollen.
v10.0.0	Hinzugefügt in: v10.0.0

• options <Objekt>

  • bigint <boolean> Gibt an, ob die numerischen Werte im zurückgegebenen <fs.Stats>-Objekt bigint sein sollen. Standardwert: false.

• Rückgabewert: <Promise> Löst mit einem <fs.Stats> für die Datei auf.

filehandle.sync()

Hinzugefügt in: v10.0.0

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Fordert an, dass alle Daten für den geöffneten Datei-Descriptor auf das Speichergerät geschrieben werden. Die spezifische Implementierung ist betriebssystem- und gerätespezifisch. Weitere Details finden Sie in der POSIX fsync(2) Dokumentation.

filehandle.truncate(len)

Hinzugefügt in: v10.0.0

• len <Integer> Standardwert: 0
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Kürzt die Datei.

Wenn die Datei größer als len Bytes war, bleiben nur die ersten len Bytes in der Datei erhalten.

Das folgende Beispiel behält nur die ersten vier Bytes der Datei:

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

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

Wenn die Datei vorher kürzer als len Bytes war, wird sie erweitert, und der erweiterte Teil wird mit Nullbytes ('\0') gefüllt:

Wenn len negativ ist, wird 0 verwendet.

filehandle.utimes(atime, mtime)

Hinzugefügt in: v10.0.0

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Gibt zurück: <Promise>

Ändert die Zeitstempel des Dateisystems des vom <FileHandle> referenzierten Objekts und löst das Promise dann ohne Argumente bei Erfolg auf.

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

[Verlauf]

Version	Änderungen
v14.0.0	Der Parameter buffer konvertiert nicht mehr nicht unterstützte Eingaben in Puffer.
v10.0.0	Hinzugefügt in: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Die Startposition innerhalb von buffer, an der die zu schreibenden Daten beginnen.
• length <integer> Die Anzahl der Bytes aus buffer, die geschrieben werden sollen. Standard: buffer.byteLength - offset
• position <integer> | <null> Der Offset vom Dateianfang, an dem die Daten aus buffer geschrieben werden sollen. Wenn position keine Zahl ist, werden die Daten an der aktuellen Position geschrieben. Weitere Informationen finden Sie in der POSIX pwrite(2) Dokumentation. Standard: null
• Gibt zurück: <Promise>

Schreibt buffer in die Datei.

Das Promise wird mit einem Objekt erfüllt, das zwei Eigenschaften enthält:

• bytesWritten <integer> die Anzahl der geschriebenen Bytes
• buffer <Buffer> | <TypedArray> | <DataView> eine Referenz auf den geschriebenen buffer.

Es ist unsicher, filehandle.write() mehrmals auf dieselbe Datei zu verwenden, ohne auf die Erfüllung (oder Ablehnung) des Promises zu warten. Verwenden Sie in diesem Szenario filehandle.createWriteStream().

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhangsmodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

filehandle.write(buffer[, options])

Hinzugefügt in: v18.3.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Standardwert: 0
  • length <integer> Standardwert: buffer.byteLength - offset
  • position <integer> Standardwert: null

• Rückgabewert: <Promise>

Schreibt buffer in die Datei.

Ähnlich der obigen Funktion filehandle.write nimmt diese Version ein optionales options-Objekt entgegen. Wird kein options-Objekt angegeben, werden die oben genannten Werte als Standard verwendet.

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

[Verlauf]

Version	Änderungen
v14.0.0	Der Parameter string konvertiert nicht mehr nicht unterstützte Eingaben in Strings.
v10.0.0	Hinzugefügt in: v10.0.0

• string <string>
• position <integer> | <null> Der Offset vom Dateianfang, an dem die Daten aus string geschrieben werden sollen. Wenn position keine number ist, werden die Daten an der aktuellen Position geschrieben. Siehe die POSIX pwrite(2) Dokumentation für weitere Details. Standardwert: null
• encoding <string> Die erwartete String-Codierung. Standardwert: 'utf8'
• Rückgabewert: <Promise>

Schreibt string in die Datei. Wenn string kein String ist, wird das Promise mit einem Fehler abgelehnt.

Das Promise wird mit einem Objekt erfüllt, das zwei Eigenschaften enthält:

• bytesWritten <integer> die Anzahl der geschriebenen Bytes
• buffer <string> eine Referenz auf den geschriebenen string.

Es ist unsicher, filehandle.write() mehrmals auf dieselbe Datei anzuwenden, ohne auf die Erfüllung (oder Ablehnung) des Promises zu warten. Verwenden Sie in diesem Szenario filehandle.createWriteStream().

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhangsmodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

filehandle.writeFile(data, options)

[Verlauf]

Version	Änderungen
v15.14.0, v14.18.0	Das Argument data unterstützt AsyncIterable, Iterable und Stream.
v14.0.0	Der Parameter data konvertiert nicht mehr ungültige Eingaben in Strings.
v10.0.0	Hinzugefügt in: v10.0.0

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> Die erwartete Zeichenkodierung, wenn data eine Zeichenkette ist. Standard: 'utf8'

• Rückgabewert: <Promise>

Schreibt asynchron Daten in eine Datei und ersetzt die Datei, falls sie bereits existiert. data kann eine Zeichenkette, ein Buffer, ein <AsyncIterable> oder ein <Iterable> Objekt sein. Das Promise wird bei Erfolg ohne Argumente erfüllt.

Wenn options eine Zeichenkette ist, gibt diese die encoding an.

Das <FileHandle> muss das Schreiben unterstützen.

Es ist unsicher, filehandle.writeFile() mehrmals für dieselbe Datei zu verwenden, ohne auf die Erfüllung (oder Ablehnung) des Promises zu warten.

Wenn ein oder mehrere filehandle.write()-Aufrufe für einen File Handle durchgeführt werden und anschließend ein filehandle.writeFile()-Aufruf erfolgt, werden die Daten von der aktuellen Position bis zum Ende der Datei geschrieben. Es wird nicht immer vom Anfang der Datei aus geschrieben.

filehandle.writev(buffers[, position])

Hinzugefügt in: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> Der Offset vom Dateianfang, an dem die Daten aus buffers geschrieben werden sollen. Wenn position keine number ist, werden die Daten an der aktuellen Position geschrieben. Standardwert: null
• Rückgabewert: <Promise>

Schreibt ein Array von <ArrayBufferView>s in die Datei.

Das Promise wird mit einem Objekt erfüllt, das zwei Eigenschaften enthält:

• bytesWritten <integer> die Anzahl der geschriebenen Bytes
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> eine Referenz auf die buffers Eingabe.

Es ist unsicher, writev() mehrfach auf dieselbe Datei aufzurufen, ohne auf die Erfüllung (oder Ablehnung) des Promises zu warten.

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhängemodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

filehandle[Symbol.asyncDispose]()

Hinzugefügt in: v20.4.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Ein Alias für filehandle.close().

fsPromises.access(path[, mode])

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> Standardwert: fs.constants.F_OK
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Prüft die Berechtigungen eines Benutzers für die durch path angegebene Datei oder das Verzeichnis. Das Argument mode ist eine optionale Ganzzahl, die die durchzuführenden Zugriffsprüfungen angibt. mode sollte entweder der Wert fs.constants.F_OK oder eine Maske sein, die aus dem bitweisen ODER von fs.constants.R_OK, fs.constants.W_OK und fs.constants.X_OK besteht (z. B. fs.constants.W_OK | fs.constants.R_OK). Überprüfen Sie Dateizugriffskonstanten für mögliche Werte von mode.

Wenn die Zugriffsprüfung erfolgreich ist, wird das Promise ohne Wert erfüllt. Wenn eine der Zugriffsprüfungen fehlschlägt, wird das Promise mit einem <Error>-Objekt abgelehnt. Das folgende Beispiel prüft, ob die Datei /etc/passwd vom aktuellen Prozess gelesen und geschrieben werden kann.

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')
}

Die Verwendung von fsPromises.access() zum Überprüfen der Zugänglichkeit einer Datei, bevor fsPromises.open() aufgerufen wird, wird nicht empfohlen. Dies führt zu einem Race Condition, da andere Prozesse den Zustand der Datei zwischen den beiden Aufrufen ändern können. Stattdessen sollte der Benutzercode die Datei direkt öffnen/lesen/schreiben und den Fehler behandeln, der ausgelöst wird, wenn die Datei nicht zugänglich ist.

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

[Verlauf]

Version	Änderungen
v21.1.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> Dateiname oder <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Standardwert: 'utf8'
  • mode <integer> Standardwert: 0o666
  • flag <string> Siehe Unterstützung von Dateisystem-flags. Standardwert: 'a'.
  • flush <boolean> Wenn true, wird der zugrunde liegende Dateideskriptor vor dem Schließen geleert. Standardwert: false.

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Fügt asynchron Daten an eine Datei an und erstellt die Datei, falls sie noch nicht existiert. data kann eine Zeichenkette oder ein <Buffer> sein.

Wenn options eine Zeichenkette ist, gibt diese die encoding an.

Die Option mode betrifft nur die neu erstellte Datei. Siehe fs.open() für weitere Details.

Der path kann als <FileHandle> angegeben werden, der zum Anhängen geöffnet wurde (mit fsPromises.open()).

fsPromises.chmod(path, mode)

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Ändert die Berechtigungen einer Datei.

fsPromises.chown(path, uid, gid)

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Ändert den Eigentümer einer Datei.

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

[Verlauf]

Version	Änderungen
v14.0.0	Das Argument flags wurde in mode geändert und eine strengere Typvalidierung eingeführt.
v10.0.0	Hinzugefügt in: v10.0.0

• src <string> | <Buffer> | <URL> Quelldateiname zum Kopieren

• dest <string> | <Buffer> | <URL> Zieldateiname des Kopiervorgangs

• mode <integer> Optionale Modifikatoren, die das Verhalten des Kopiervorgangs festlegen. Es ist möglich, eine Maske zu erstellen, die aus dem bitweisen ODER von zwei oder mehr Werten besteht (z. B. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE). Standardwert: 0.

  • fs.constants.COPYFILE_EXCL: Der Kopiervorgang schlägt fehl, wenn dest bereits existiert.
  • fs.constants.COPYFILE_FICLONE: Der Kopiervorgang versucht, einen schreibgeschützten Reflink zu erstellen. Wenn die Plattform Copy-on-Write nicht unterstützt, wird ein Ausweichkopiermechanismus verwendet.
  • fs.constants.COPYFILE_FICLONE_FORCE: Der Kopiervorgang versucht, einen schreibgeschützten Reflink zu erstellen. Wenn die Plattform Copy-on-Write nicht unterstützt, schlägt der Vorgang fehl.

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Kopiert src asynchron nach dest. Standardmäßig wird dest überschrieben, wenn es bereits existiert.

Es werden keine Garantien für die Atomarität des Kopiervorgangs gegeben. Wenn nach dem Öffnen der Zieldatei zum Schreiben ein Fehler auftritt, wird versucht, die Zieldatei zu entfernen.

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

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('source.txt wurde nach destination.txt kopiert')
} catch {
  console.error('Die Datei konnte nicht kopiert werden')
}

// Durch die Verwendung von COPYFILE_EXCL schlägt der Vorgang fehl, wenn destination.txt existiert.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('source.txt wurde nach destination.txt kopiert')
} catch {
  console.error('Die Datei konnte nicht kopiert werden')
}

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

[Versionsgeschichte]

Version	Änderungen
v22.3.0	Diese API ist nicht mehr experimentell.
v20.1.0, v18.17.0	Akzeptiert eine zusätzliche mode-Option, um das Kopierverhalten als mode-Argument von fs.copyFile() anzugeben.
v17.6.0, v16.15.0	Akzeptiert eine zusätzliche verbatimSymlinks-Option, um anzugeben, ob die Pfadauflösung für symbolische Links durchgeführt werden soll.
v16.7.0	Hinzugefügt in: v16.7.0

• src <string> | <URL> Quelldateipfad zum Kopieren.

• dest <string> | <URL> Zielpfad zum Kopieren.

• options <Object>

  • dereference <boolean> Symbolische Links auflösen. Standard: false.

  • errorOnExist <boolean> Wenn force false ist und das Ziel existiert, einen Fehler auslösen. Standard: false.

  • filter <Function> Funktion zum Filtern kopierter Dateien/Verzeichnisse. Liefert true zurück, um das Element zu kopieren, false, um es zu ignorieren. Wenn ein Verzeichnis ignoriert wird, wird auch der gesamte Inhalt übersprungen. Kann auch ein Promise zurückgeben, das mit true oder false aufgelöst wird. Standard: undefined.

  • src <string> Quelldateipfad zum Kopieren.

  • dest <string> Zielpfad zum Kopieren.

  • Gibt zurück: <boolean> | <Promise> Ein Wert, der in einen booleschen Wert umgewandelt werden kann, oder ein Promise, das einen solchen Wert erfüllt.

  • force <boolean> Bestehende Datei oder Verzeichnis überschreiben. Der Kopiervorgang ignoriert Fehler, wenn Sie dies auf false setzen und das Ziel existiert. Verwenden Sie die Option errorOnExist, um dieses Verhalten zu ändern. Standard: true.

  • mode <integer> Modifikatoren für den Kopiervorgang. Standard: 0. Siehe mode-Flag von fsPromises.copyFile().

  • preserveTimestamps <boolean> Wenn true, werden Zeitstempel von src beibehalten. Standard: false.

  • recursive <boolean> Verzeichnisse rekursiv kopieren. Standard: false

  • verbatimSymlinks <boolean> Wenn true, wird die Pfadauflösung für symbolische Links übersprungen. Standard: false

• Gibt zurück: <Promise> Löst mit undefined bei Erfolg auf.

Kopiert asynchron die gesamte Verzeichnisstruktur von src nach dest, einschließlich Unterverzeichnissen und Dateien.

Beim Kopieren eines Verzeichnisses in ein anderes Verzeichnis werden keine Globs unterstützt, und das Verhalten ähnelt cp dir1/ dir2/.

fsPromises.glob(pattern[, options])

[Historie]

Version	Änderungen
v22.2.0	Unterstützung für withFileTypes als Option hinzugefügt.
v22.0.0	Hinzugefügt in: v22.0.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> aktuelles Arbeitsverzeichnis. Standardwert: process.cwd()
  • exclude <Function> Funktion zum Filtern von Dateien/Verzeichnissen. Gibt true zurück, um das Element auszuschließen, false, um es einzuschließen. Standardwert: undefined.
  • withFileTypes <boolean> true, wenn der Glob Pfade als Dirents zurückgeben soll, andernfalls false. Standardwert: false.

• Rückgabewert: <AsyncIterator> Ein AsyncIterator, der die Pfade der Dateien liefert, die dem Muster entsprechen.

ESM

import { glob } from 'node:fs/promises'

for await (const entry of glob('**/*.js')) console.log(entry)

CJS

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

;(async () => {
  for await (const entry of glob('**/*.js')) console.log(entry)
})()

fsPromises.lchmod(path, mode)

Seit v10.0.0 veraltet

• path <string> | <Buffer> | <URL>
• mode <integer>
• Rückgabewert: <Promise> Erfüllt mit undefined bei Erfolg.

Ändert die Berechtigungen eines symbolischen Links.

Diese Methode ist nur unter macOS implementiert.

fsPromises.lchown(path, uid, gid)

[Verlauf]

Version	Änderungen
v10.6.0	Diese API ist nicht mehr veraltet.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Rückgabewert: <Promise> Erfüllt mit undefined bei Erfolg.

Ändert den Besitz eines symbolischen Links.

fsPromises.lutimes(path, atime, mtime)

Hinzugefügt in: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Rückgabewert: <Promise> Erfüllt mit undefined bei Erfolg.

Ändert die Zugriffs- und Änderungszeiten einer Datei auf die gleiche Weise wie fsPromises.utimes(), mit dem Unterschied, dass, wenn der Pfad auf einen symbolischen Link verweist, der Link nicht dereferenziert wird: Stattdessen werden die Zeitstempel des symbolischen Links selbst geändert.

fsPromises.link(existingPath, newPath)

Hinzugefügt in: v10.0.0

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Gibt zurück: <Promise> Erfüllt mit undefined bei Erfolg.

Erstellt einen neuen Link von existingPath nach newPath. Siehe die POSIX link(2) Dokumentation für weitere Details.

fsPromises.lstat(path[, options])

[Verlauf]

Version	Änderungen
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte BigInts sein sollen.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats> Objekt bigint sein sollen. Standard: false.

• Gibt zurück: <Promise> Erfüllt mit dem <fs.Stats> Objekt für den angegebenen symbolischen Link path.

Äquivalent zu fsPromises.stat(), es sei denn, path verweist auf einen symbolischen Link, in diesem Fall wird der Link selbst geprüft, nicht die Datei, auf die er verweist. Siehe die POSIX lstat(2) Dokumentation für weitere Details.

fsPromises.mkdir(path[, options])

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> Standardwert: false
  • mode <string> | <integer> Wird unter Windows nicht unterstützt. Standardwert: 0o777.

• Rückgabewert: <Promise> Bei Erfolg wird undefined zurückgegeben, wenn recursive false ist, oder der Pfad des ersten erstellten Verzeichnisses, wenn recursive true ist.

Erstellt asynchron ein Verzeichnis.

Das optionale Argument options kann eine ganze Zahl sein, die mode (Berechtigungen und Sticky Bits) angibt, oder ein Objekt mit einer mode-Eigenschaft und einer recursive-Eigenschaft, die angibt, ob übergeordnete Verzeichnisse erstellt werden sollen. Ein Aufruf von fsPromises.mkdir(), wenn path ein bereits existierendes Verzeichnis ist, führt nur dann zu einer Ablehnung, wenn recursive false ist.

ESM

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)
}

CJS

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)

fsPromises.mkdtemp(prefix[, options])

[Verlauf]

Version	Änderungen
v20.6.0, v18.19.0	Der Parameter prefix akzeptiert jetzt Puffer und URLs.
v16.5.0, v14.18.0	Der Parameter prefix akzeptiert jetzt eine leere Zeichenkette.
v10.0.0	Hinzugefügt in: v10.0.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• Rückgabewert: <Promise> Erfüllt mit einer Zeichenkette, die den Dateisystempfad des neu erstellten temporären Verzeichnisses enthält.

Erstellt ein eindeutiges temporäres Verzeichnis. Ein eindeutiger Verzeichnisname wird generiert, indem sechs zufällige Zeichen an das Ende des angegebenen prefix angehängt werden. Vermeiden Sie aufgrund von Plattforminkonsistenzen nachgestellte X-Zeichen in prefix. Einige Plattformen, insbesondere die BSDs, können mehr als sechs zufällige Zeichen zurückgeben und nachgestellte X-Zeichen in prefix durch zufällige Zeichen ersetzen.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer Eigenschaft encoding, die die zu verwendende Zeichencodierung angibt.

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)
}

Die Methode fsPromises.mkdtemp() hängt die sechs zufällig ausgewählten Zeichen direkt an die prefix-Zeichenkette an. Wenn beispielsweise ein Verzeichnis /tmp vorhanden ist und die Absicht besteht, ein temporäres Verzeichnis innerhalb von /tmp zu erstellen, muss prefix mit einem plattformspezifischen Pfadtrennzeichen enden (require('node:path').sep).

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

[Verlauf]

Version	Änderungen
v11.1.0	Das Argument flags ist jetzt optional und standardmäßig auf 'r' gesetzt.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Siehe Unterstützung von Dateisystem-flags. Standardwert: 'r'.
• mode <string> | <integer> Legt den Datei-Modus (Berechtigungen und Sticky-Bits) fest, wenn die Datei erstellt wird. Standardwert: 0o666 (lesbar und beschreibbar)
• Rückgabewert: <Promise> Erfüllt mit einem <FileHandle>-Objekt.

Öffnet ein <FileHandle>.

Weitere Details finden Sie in der POSIX open(2)-Dokumentation.

Einige Zeichen (\< \> : " / \ | ? *) sind unter Windows reserviert, wie in Benennen von Dateien, Pfaden und Namespaces dokumentiert. Unter NTFS öffnet Node.js einen Dateisystemstrom, wenn der Dateiname einen Doppelpunkt enthält, wie auf dieser MSDN-Seite beschrieben.

fsPromises.opendir(path[, options])

[Verlauf]

Version	Änderungen
v20.1.0, v18.17.0	Option recursive hinzugefügt.
v13.1.0, v12.16.0	Die Option bufferSize wurde eingeführt.
v12.12.0	Hinzugefügt in: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> Standardwert: 'utf8'
  • bufferSize <number> Anzahl der Verzeichniseinträge, die intern beim Lesen aus dem Verzeichnis gepuffert werden. Höhere Werte führen zu besserer Leistung, aber höherem Speicherverbrauch. Standardwert: 32
  • recursive <boolean> Das aufgelöste Dir wird ein <AsyncIterable> sein, das alle Unterdateien und -verzeichnisse enthält. Standardwert: false

• Rückgabewert: <Promise> Erfüllt mit einem <fs.Dir>.

Öffnet asynchron ein Verzeichnis für die iterative Suche. Weitere Details finden Sie in der POSIX opendir(3)-Dokumentation.

Erstellt ein <fs.Dir>, das alle weiteren Funktionen zum Lesen aus und Bereinigen des Verzeichnisses enthält.

Die Option encoding legt die Codierung für den path beim Öffnen des Verzeichnisses und nachfolgenden Lesevorgängen fest.

Beispiel mit asynchroner Iteration:

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)
}

Bei Verwendung des asynchronen Iterators wird das <fs.Dir>-Objekt automatisch geschlossen, nachdem der Iterator beendet wurde.

fsPromises.readdir(path[, options])

[Verlauf]

Version	Änderungen
v20.1.0, v18.17.0	Option recursive hinzugefügt.
v10.11.0	Neue Option withFileTypes hinzugefügt.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'
  • withFileTypes <boolean> Standard: false
  • recursive <boolean> Wenn true, liest den Inhalt eines Verzeichnisses rekursiv. Im rekursiven Modus werden alle Dateien, Unterdateien und Verzeichnisse aufgelistet. Standard: false.

• Rückgabewert: <Promise> Erfüllt mit einem Array der Namen der Dateien im Verzeichnis, ausgenommen '.' und '..'.

Liest den Inhalt eines Verzeichnisses.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung für die Dateinamen angibt. Wenn encoding auf 'buffer' gesetzt ist, werden die zurückgegebenen Dateinamen als <Buffer>-Objekte übergeben.

Wenn options.withFileTypes auf true gesetzt ist, enthält das zurückgegebene Array <fs.Dirent>-Objekte.

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)
}

fsPromises.readFile(path[, options])

[Historie]

Version	Änderungen
v15.2.0, v14.17.0	Das options-Argument kann ein AbortSignal enthalten, um eine laufende readFile-Anfrage abzubrechen.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> Dateiname oder FileHandle

• options <Object> | <string>

  • encoding <string> | <null> Standard: null
  • flag <string> Siehe Unterstützung von Dateisystem-flags. Standard: 'r'.
  • signal <AbortSignal> ermöglicht das Abbrechen einer laufenden readFile-Operation

• Rückgabewert: <Promise> Erfüllt mit dem Inhalt der Datei.

Liest asynchron den gesamten Inhalt einer Datei.

Wenn keine Codierung angegeben ist (mit options.encoding), werden die Daten als <Buffer>-Objekt zurückgegeben. Andernfalls sind die Daten eine Zeichenkette.

Wenn options eine Zeichenkette ist, gibt diese die Codierung an.

Wenn path ein Verzeichnis ist, ist das Verhalten von fsPromises.readFile() plattformabhängig. Unter macOS, Linux und Windows wird das Promise mit einem Fehler abgelehnt. Unter FreeBSD wird eine Darstellung des Inhalts des Verzeichnisses zurückgegeben.

Ein Beispiel zum Lesen einer package.json-Datei im selben Verzeichnis wie der laufende Code:

ESM

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)
}

CJS

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()

Es ist möglich, eine laufende readFile-Operation mit einem <AbortSignal> abzubrechen. Wenn eine Anfrage abgebrochen wird, wird das zurückgegebene Promise mit einem AbortError abgelehnt:

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

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

  // Brechen Sie die Anfrage ab, bevor das Promise erfüllt wird.
  controller.abort()

  await promise
} catch (err) {
  // Wenn eine Anfrage abgebrochen wird - err ist ein AbortError
  console.error(err)
}

Das Abbrechen einer laufenden Anfrage bricht keine einzelnen Betriebssystemanforderungen ab, sondern eher die interne Pufferung, die fs.readFile durchführt.

Jeder angegebene <FileHandle> muss das Lesen unterstützen.

fsPromises.readlink(path[, options])

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standardwert: 'utf8'

• Gibt zurück: <Promise> Löst sich mit linkString bei Erfolg auf.

Liest den Inhalt des symbolischen Links, auf den path verweist. Weitere Details finden Sie in der POSIX readlink(2) Dokumentation. Das Promise wird mit linkString bei Erfolg aufgelöst.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung für den zurückgegebenen Linkpfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Linkpfad als <Buffer> Objekt übergeben.

fsPromises.realpath(path[, options])

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standardwert: 'utf8'

• Gibt zurück: <Promise> Löst sich mit dem aufgelösten Pfad bei Erfolg auf.

Bestimmt den tatsächlichen Speicherort von path unter Verwendung der gleichen Semantik wie die Funktion fs.realpath.native().

Nur Pfade, die in UTF8-Zeichenketten konvertiert werden können, werden unterstützt.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung für den Pfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Pfad als <Buffer> Objekt übergeben.

Unter Linux muss, wenn Node.js mit musl libc verknüpft ist, das procfs-Dateisystem auf /proc gemountet sein, damit diese Funktion funktioniert. Glibc hat diese Einschränkung nicht.

fsPromises.rename(oldPath, newPath)

Hinzugefügt in: v10.0.0

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Rückgabewert: <Promise> Wird mit undefined bei Erfolg erfüllt.

Benennt oldPath in newPath um.

fsPromises.rmdir(path[, options])

[Verlauf]

Version	Änderungen
v16.0.0	Die Verwendung von fsPromises.rmdir(path, { recursive: true }) für einen Pfad, der eine Datei ist, ist nicht mehr zulässig und führt unter Windows zu einem ENOENT-Fehler und unter POSIX zu einem ENOTDIR-Fehler.
v16.0.0	Die Verwendung von fsPromises.rmdir(path, { recursive: true }) für einen Pfad, der nicht existiert, ist nicht mehr zulässig und führt zu einem ENOENT-Fehler.
v16.0.0	Die Option recursive ist veraltet, ihre Verwendung löst eine Veraltungswarnung aus.
v14.14.0	Die Option recursive ist veraltet, verwenden Sie stattdessen fsPromises.rm.
v13.3.0, v12.16.0	Die Option maxBusyTries wurde in maxRetries umbenannt, und ihr Standardwert ist 0. Die Option emfileWait wurde entfernt, und EMFILE-Fehler verwenden dieselbe Wiederholungslogik wie andere Fehler. Die Option retryDelay wird jetzt unterstützt. ENFILE-Fehler werden jetzt wiederholt.
v12.10.0	Die Optionen recursive, maxBusyTries und emfileWait werden jetzt unterstützt.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> Wenn ein EBUSY, EMFILE, ENFILE, ENOTEMPTY oder EPERM Fehler auftritt, wiederholt Node.js den Vorgang mit einer linearen Backoff-Wartezeit von retryDelay Millisekunden länger bei jedem Versuch. Diese Option gibt die Anzahl der Wiederholungsversuche an. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 0.
  • recursive <boolean> Wenn true, wird ein rekursiver Verzeichnisentfernung durchgeführt. Im rekursiven Modus werden Operationen bei Fehlern wiederholt. Standard: false. Veraltet.
  • retryDelay <integer> Die Wartezeit in Millisekunden zwischen Wiederholungsversuchen. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 100.

• Rückgabewert: <Promise> Wird mit undefined bei Erfolg erfüllt.

Entfernt das durch path identifizierte Verzeichnis.

Die Verwendung von fsPromises.rmdir() auf einer Datei (kein Verzeichnis) führt dazu, dass das Promise mit einem ENOENT-Fehler unter Windows und einem ENOTDIR-Fehler unter POSIX abgelehnt wird.

Um ein ähnliches Verhalten wie der Unix-Befehl rm -rf zu erhalten, verwenden Sie fsPromises.rm() mit den Optionen { recursive: true, force: true }.

fsPromises.rm(path[, options])

Hinzugefügt in: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> Wenn true, werden Ausnahmen ignoriert, wenn path nicht existiert. Standard: false.
  • maxRetries <integer> Wenn ein EBUSY, EMFILE, ENFILE, ENOTEMPTY oder EPERM Fehler auftritt, wiederholt Node.js den Vorgang mit einer linearen Backoff-Wartezeit von retryDelay Millisekunden länger bei jedem Versuch. Diese Option gibt die Anzahl der Wiederholungsversuche an. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 0.
  • recursive <boolean> Wenn true, wird eine rekursive Verzeichnislöschung durchgeführt. Im rekursiven Modus werden Operationen bei Fehlern wiederholt. Standard: false.
  • retryDelay <integer> Die Wartezeit in Millisekunden zwischen Wiederholungsversuchen. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 100.

• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Entfernt Dateien und Verzeichnisse (modelliert nach dem Standard-POSIX rm Dienstprogramm).

fsPromises.stat(path[, options])

[Verlauf]

Version	Änderungen
v10.5.0	Akzeptiert ein zusätzliches options Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte BigInts sein sollen.
v10.0.0	Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats> Objekt bigint sein sollen. Standard: false.

• Rückgabewert: <Promise> Löst mit dem <fs.Stats> Objekt für den gegebenen path auf.

fsPromises.statfs(path[, options])

Hinzugefügt in: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.StatFs> Objekt bigint sein sollen. Standard: false.

• Rückgabewert: <Promise> Löst mit dem <fs.StatFs> Objekt für den gegebenen path auf.

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

[Verlauf]

Version	Änderungen
v19.0.0	Wenn das type-Argument null ist oder weggelassen wird, erkennt Node.js den target-Typ automatisch und wählt automatisch dir oder file aus.
v10.0.0	Hinzugefügt in: v10.0.0

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Standard: null
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Erstellt einen symbolischen Link.

Das type-Argument wird nur auf Windows-Plattformen verwendet und kann einer von 'dir', 'file' oder 'junction' sein. Wenn das type-Argument null ist, erkennt Node.js den target-Typ automatisch und verwendet 'file' oder 'dir'. Wenn target nicht existiert, wird 'file' verwendet. Windows-Verknüpfungspunkte erfordern, dass der Zielpfad absolut ist. Bei Verwendung von 'junction' wird das target-Argument automatisch auf den absoluten Pfad normalisiert. Verknüpfungspunkte auf NTFS-Volumes können nur auf Verzeichnisse verweisen.

fsPromises.truncate(path[, len])

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> Standard: 0
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Kürzt (verkürzt oder erweitert die Länge) des Inhalts unter path auf len Bytes.

fsPromises.unlink(path)

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Wenn path auf einen symbolischen Link verweist, wird der Link entfernt, ohne die Datei oder das Verzeichnis zu beeinflussen, auf die dieser Link verweist. Wenn path auf einen Dateipfad verweist, der kein symbolischer Link ist, wird die Datei gelöscht. Siehe die POSIX unlink(2) Dokumentation für weitere Details.

fsPromises.utimes(path, atime, mtime)

Hinzugefügt in: v10.0.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Rückgabewert: <Promise> Löst mit undefined bei Erfolg auf.

Ändert die Dateisystem-Zeitstempel des Objekts, auf das path verweist.

Die Argumente atime und mtime folgen diesen Regeln:

• Werte können entweder Zahlen sein, die die Unix-Epoch-Zeit darstellen, Date-Objekte oder numerische Zeichenketten wie '123456789.0'.
• Wenn der Wert nicht in eine Zahl konvertiert werden kann oder NaN, Infinity oder -Infinity ist, wird ein Error geworfen.

fsPromises.watch(filename[, options])

Hinzugefügt in: v15.9.0, v14.18.0

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> Gibt an, ob der Prozess so lange weiterlaufen soll, wie Dateien überwacht werden. Standardwert: true.
  • recursive <boolean> Gibt an, ob alle Unterverzeichnisse überwacht werden sollen oder nur das aktuelle Verzeichnis. Dies gilt, wenn ein Verzeichnis angegeben ist und nur auf unterstützten Plattformen (siehe Einschränkungen). Standardwert: false.
  • encoding <string> Gibt die Zeichencodierung an, die für den an den Listener übergebenen Dateinamen verwendet werden soll. Standardwert: 'utf8'.
  • signal <AbortSignal> Ein <AbortSignal>, der signalisiert, wann der Watcher gestoppt werden soll.

• Gibt zurück: <AsyncIterator> von Objekten mit den Eigenschaften:

  • eventType <string> Der Typ der Änderung
  • filename <string> | <Buffer> | <null> Der Name der geänderten Datei.

Gibt einen asynchronen Iterator zurück, der Änderungen an filename überwacht, wobei filename entweder eine Datei oder ein Verzeichnis ist.

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
  }
})()

Auf den meisten Plattformen wird 'rename' immer dann ausgegeben, wenn ein Dateiname im Verzeichnis erscheint oder verschwindet.

Alle Einschränkungen für fs.watch() gelten auch für fsPromises.watch().

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

[Verlauf]

Version	Änderungen
v21.0.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v15.14.0, v14.18.0	Das Argument data unterstützt AsyncIterable, Iterable und Stream.
v15.2.0, v14.17.0	Das options-Argument kann ein AbortSignal enthalten, um eine laufende writeFile-Anfrage abzubrechen.
v14.0.0	Der data-Parameter konvertiert nicht mehr ungültige Eingaben in Strings.
v10.0.0	Hinzugefügt in: v10.0.0

• file <string> | <Buffer> | <URL> | <FileHandle> Dateiname oder FileHandle

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> Standard: 'utf8'
  • mode <integer> Standard: 0o666
  • flag <string> Siehe Unterstützung von Dateisystem-Flags. Standard: 'w'.
  • flush <boolean> Wenn alle Daten erfolgreich in die Datei geschrieben wurden und flush true ist, wird filehandle.sync() verwendet, um die Daten zu leeren. Standard: false.
  • signal <AbortSignal> ermöglicht das Abbrechen eines laufenden writeFile

• Rückgabewert: <Promise> Löst sich mit undefined bei Erfolg auf.

Schreibt asynchron Daten in eine Datei und ersetzt die Datei, falls sie bereits existiert. data kann eine Zeichenkette, ein Buffer, ein <AsyncIterable> oder ein <Iterable>-Objekt sein.

Die Option encoding wird ignoriert, wenn data ein Buffer ist.

Wenn options eine Zeichenkette ist, gibt sie die Codierung an.

Die Option mode betrifft nur die neu erstellte Datei. Weitere Einzelheiten finden Sie unter fs.open().

Jeder angegebene <FileHandle> muss das Schreiben unterstützen.

Es ist unsicher, fsPromises.writeFile() mehrmals für dieselbe Datei zu verwenden, ohne auf die Erfüllung des Promises zu warten.

Ähnlich wie fsPromises.readFile - fsPromises.writeFile ist eine Komfortmethode, die intern mehrere write-Aufrufe durchführt, um den übergebenen Buffer zu schreiben. Für performancekritischen Code sollten Sie fs.createWriteStream() oder filehandle.createWriteStream() verwenden.

Es ist möglich, ein <AbortSignal> zu verwenden, um ein fsPromises.writeFile() abzubrechen. Der Abbruch erfolgt "best effort", und es werden wahrscheinlich noch einige Daten geschrieben.

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 })

  // Brechen Sie die Anfrage ab, bevor das Promise erfüllt wird.
  controller.abort()

  await promise
} catch (err) {
  // Wenn eine Anfrage abgebrochen wird - err ist ein AbortError
  console.error(err)
}

Das Abbrechen einer laufenden Anfrage bricht keine einzelnen Betriebssystemanforderungen ab, sondern das interne Puffern, das fs.writeFile durchführt.

fsPromises.constants

Hinzugefügt in: v18.4.0, v16.17.0

• <Objekt>

Gibt ein Objekt zurück, das häufig verwendete Konstanten für Dateisystemoperationen enthält. Das Objekt ist identisch mit fs.constants. Weitere Details finden Sie unter FS-Konstanten.

Callback-API

Die Callback-APIs führen alle Operationen asynchron aus, ohne die Ereignisschleife zu blockieren, und rufen dann nach Abschluss oder Fehler eine Callback-Funktion auf.

Die Callback-APIs verwenden den zugrunde liegenden Node.js-Threadpool, um Dateisystemoperationen außerhalb des Ereignisschleifen-Threads auszuführen. Diese Operationen sind nicht synchronisiert oder threadsicher. Vorsicht ist geboten, wenn mehrere gleichzeitige Änderungen an derselben Datei vorgenommen werden, da sonst Datenbeschädigungen auftreten können.

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

[Verlauf]

Version	Änderungen
v20.8.0	Die Konstanten fs.F_OK, fs.R_OK, fs.W_OK und fs.X_OK, die direkt auf fs vorhanden waren, sind veraltet.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE statt ERR_INVALID_CALLBACK aus.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v6.3.0	Die Konstanten wie fs.R_OK usw., die direkt auf fs vorhanden waren, wurden als weiche Veraltung in fs.constants verschoben. Daher verwenden Sie für Node.js < v6.3.0 fs, um auf diese Konstanten zuzugreifen, oder verwenden Sie etwas wie `(fs.constants
v0.11.15	Hinzugefügt in: v0.11.15

• path <Zeichenkette> | <Buffer> | <URL>
• mode <Ganzzahl> Standard: fs.constants.F_OK
• callback <Funktion>
  • err <Error>

Testet die Berechtigungen eines Benutzers für die Datei oder das Verzeichnis, die durch path angegeben ist. Das Argument mode ist eine optionale Ganzzahl, die die durchzuführenden Zugriffsüberprüfungen angibt. mode sollte entweder der Wert fs.constants.F_OK oder eine Maske sein, die aus dem bitweisen ODER von beliebigen Werten von fs.constants.R_OK, fs.constants.W_OK und fs.constants.X_OK besteht (z. B. fs.constants.W_OK | fs.constants.R_OK). Überprüfen Sie Dateizugriffskonstanten für mögliche Werte von mode.

Das letzte Argument, callback, ist eine Callback-Funktion, die mit einem möglichen Fehlerargument aufgerufen wird. Wenn eine der Zugriffsüberprüfungen fehlschlägt, ist das Fehlerargument ein Error-Objekt. Die folgenden Beispiele überprüfen, ob package.json existiert und ob es lesbar oder beschreibbar ist.

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

const file = 'package.json'

// Überprüfen, ob die Datei im aktuellen Verzeichnis existiert.
access(file, constants.F_OK, err => {
  console.log(`${file} ${err ? 'existiert nicht' : 'existiert'}`)
})

// Überprüfen, ob die Datei lesbar ist.
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? 'ist nicht lesbar' : 'ist lesbar'}`)
})

// Überprüfen, ob die Datei beschreibbar ist.
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? 'ist nicht beschreibbar' : 'ist beschreibbar'}`)
})

// Überprüfen, ob die Datei lesbar und beschreibbar ist.
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? 'ist nicht' : 'ist'} lesbar und beschreibbar`)
})

Verwenden Sie fs.access() nicht, um die Zugänglichkeit einer Datei zu überprüfen, bevor Sie fs.open(), fs.readFile() oder fs.writeFile() aufrufen. Dies führt zu einem Race Condition, da andere Prozesse den Zustand der Datei zwischen den beiden Aufrufen ändern können. Stattdessen sollte der Benutzercode die Datei direkt öffnen/lesen/schreiben und den Fehler behandeln, der ausgelöst wird, wenn die Datei nicht zugänglich ist.

Schreiben (NICHT EMPFOHLEN)

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

access('myfile', err => {
  if (!err) {
    console.error('myfile existiert bereits')
    return
  }

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

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

Schreiben (EMPFOHLEN)

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

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

    throw err
  }

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

Lesen (NICHT EMPFOHLEN)

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

    throw err
  }

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

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

Lesen (EMPFOHLEN)

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

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile existiert nicht')
      return
    }

    throw err
  }

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

Die oben genannten "nicht empfohlenen" Beispiele überprüfen die Zugänglichkeit und verwenden dann die Datei; die "empfohlenen" Beispiele sind besser, da sie die Datei direkt verwenden und den Fehler behandeln, falls vorhanden.

Überprüfen Sie die Zugänglichkeit einer Datei im Allgemeinen nur, wenn die Datei nicht direkt verwendet wird, z. B. wenn ihre Zugänglichkeit ein Signal von einem anderen Prozess ist.

Unter Windows können Zugriffssteuerungslisten (ACLs) in einem Verzeichnis den Zugriff auf eine Datei oder ein Verzeichnis einschränken. Die Funktion fs.access() prüft jedoch die ACL nicht und kann daher melden, dass ein Pfad zugänglich ist, selbst wenn die ACL den Benutzer am Lesen oder Schreiben daran hindert.

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

[Versionsgeschichte]

Version	Änderungen
v21.1.0, v20.10.0	Die Option flush wird nun unterstützt.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE statt ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v7.0.0	Das übergebene options-Objekt wird niemals verändert.
v5.0.0	Der Parameter file kann nun ein File Descriptor sein.
v0.6.7	Hinzugefügt in: v0.6.7

• path <string> | <Buffer> | <URL> | <number> Dateiname oder File Descriptor

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Standard: 'utf8'
  • mode <integer> Standard: 0o666
  • flag <string> Siehe Unterstützung von Dateisystem-flags. Standard: 'a'.
  • flush <boolean> Wenn true, wird der zugrunde liegende File Descriptor vor dem Schließen geleert. Standard: false.

• callback <Function>

  • err <Error>

Fügt asynchron Daten an eine Datei an und erstellt die Datei, falls sie noch nicht existiert. data kann eine Zeichenkette oder ein <Buffer> sein.

Die Option mode wirkt sich nur auf die neu erstellte Datei aus. Siehe fs.open() für weitere Details.

import { appendFile } from 'node:fs'

appendFile('message.txt', 'data to append', err => {
  if (err) throw err
  console.log('Die "data to append" wurden an die Datei angehängt!')
})

Wenn options eine Zeichenkette ist, gibt diese die Kodierung an:

import { appendFile } from 'node:fs'

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

Der path kann als numerischer File Descriptor angegeben werden, der zum Anhängen geöffnet wurde (mit fs.open() oder fs.openSync()). Der File Descriptor wird nicht automatisch geschlossen.

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
  }
})

fs.chmod(path, mode, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.1.30	Hinzugefügt in: v0.1.30

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

Ändert asynchron die Berechtigungen einer Datei. An den Completion-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Siehe die POSIX chmod(2) Dokumentation für weitere Details.

import { chmod } from 'node:fs'

chmod('my_file.txt', 0o775, err => {
  if (err) throw err
  console.log('Die Berechtigungen für die Datei "my_file.txt" wurden geändert!')
})

Dateimodi

Das in den Methoden fs.chmod() und fs.chmodSync() verwendete Argument mode ist eine numerische Bitmaske, die mithilfe eines logischen ODER der folgenden Konstanten erstellt wird:

Konstante	Oktal	Beschreibung
fs.constants.S_IRUSR	0o400	Lesen durch Besitzer
fs.constants.S_IWUSR	0o200	Schreiben durch Besitzer
fs.constants.S_IXUSR	0o100	Ausführen/Suchen durch Besitzer
fs.constants.S_IRGRP	0o40	Lesen durch Gruppe
fs.constants.S_IWGRP	0o20	Schreiben durch Gruppe
fs.constants.S_IXGRP	0o10	Ausführen/Suchen durch Gruppe
fs.constants.S_IROTH	0o4	Lesen durch Andere
fs.constants.S_IWOTH	0o2	Schreiben durch Andere
fs.constants.S_IXOTH	0o1	Ausführen/Suchen durch Andere

Eine einfachere Methode zum Erstellen des mode ist die Verwendung einer Sequenz von drei Oktalzahlen (z. B. 765). Die linke Ziffer (7 im Beispiel) gibt die Berechtigungen für den Dateibesitzer an. Die mittlere Ziffer (6 im Beispiel) gibt die Berechtigungen für die Gruppe an. Die rechte Ziffer (5 im Beispiel) gibt die Berechtigungen für Andere an.

Zahl	Beschreibung
7	Lesen, Schreiben und Ausführen
6	Lesen und Schreiben
5	Lesen und Ausführen
4	Nur Lesen
3	Schreiben und Ausführen
2	Nur Schreiben
1	Nur Ausführen
0	Keine Berechtigung

Beispielsweise bedeutet der Oktalwert 0o765:

• Der Besitzer darf die Datei lesen, schreiben und ausführen.
• Die Gruppe darf die Datei lesen und schreiben.
• Andere dürfen die Datei lesen und ausführen.

Bei Verwendung von rohen Zahlen, wo Dateimodi erwartet werden, kann jeder Wert größer als 0o777 zu plattformspezifischem Verhalten führen, das nicht konsistent funktioniert. Daher werden Konstanten wie S_ISVTX, S_ISGID oder S_ISUID nicht in fs.constants verfügbar gemacht.

Einschränkungen: Unter Windows kann nur die Schreibberechtigung geändert werden, und die Unterscheidung zwischen den Berechtigungen von Gruppe, Besitzer oder Anderen wird nicht implementiert.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem file:-Protokoll sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.1.97	Hinzugefügt in: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

Ändert asynchron den Besitzer und die Gruppe einer Datei. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Siehe die POSIX chown(2) Dokumentation für weitere Details.

fs.close(fd[, callback])

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.9.0, v14.17.0	Ein Standard-Callback wird jetzt verwendet, wenn keiner angegeben wird.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.0.2	Hinzugefügt in: v0.0.2

• fd <integer>
• callback <Function>
  • err <Error>

Schließt den Filedescriptor. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Das Aufrufen von fs.close() auf einen beliebigen Filedescriptor (fd), der derzeit über eine andere fs-Operation verwendet wird, kann zu undefiniertem Verhalten führen.

Siehe die POSIX close(2) Dokumentation für weitere Details.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v14.0.0	Das Argument flags wurde in mode geändert und eine strengere Typvalidierung eingeführt.
v8.5.0	Hinzugefügt in: v8.5.0

• src <string> | <Buffer> | <URL> Quelldateiname zum Kopieren
• dest <string> | <Buffer> | <URL> Zieldateiname des Kopiervorgangs
• mode <integer> Modifikatoren für den Kopiervorgang. Standard: 0.
• callback <Function>
  • err <Error>

Kopiert src asynchron nach dest. Standardmäßig wird dest überschrieben, wenn es bereits existiert. Dem Callback-Funktion werden keine anderen Argumente als eine mögliche Ausnahme übergeben. Node.js gibt keine Garantien hinsichtlich der Atomarität des Kopiervorgangs ab. Wenn ein Fehler auftritt, nachdem die Zieldatei zum Schreiben geöffnet wurde, versucht Node.js, die Zieldatei zu entfernen.

mode ist eine optionale ganze Zahl, die das Verhalten des Kopiervorgangs angibt. Es ist möglich, eine Maske zu erstellen, die aus dem bitweisen ODER von zwei oder mehr Werten besteht (z. B. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: Der Kopiervorgang schlägt fehl, wenn dest bereits existiert.
• fs.constants.COPYFILE_FICLONE: Der Kopiervorgang versucht, einen Copy-on-Write-Reflink zu erstellen. Wenn die Plattform Copy-on-Write nicht unterstützt, wird ein Fallback-Kopiermechanismus verwendet.
• fs.constants.COPYFILE_FICLONE_FORCE: Der Kopiervorgang versucht, einen Copy-on-Write-Reflink zu erstellen. Wenn die Plattform Copy-on-Write nicht unterstützt, schlägt der Vorgang fehl.

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

function callback(err) {
  if (err) throw err
  console.log('source.txt wurde nach destination.txt kopiert')
}

// destination.txt wird standardmäßig erstellt oder überschrieben.
copyFile('source.txt', 'destination.txt', callback)

// Mit COPYFILE_EXCL schlägt der Vorgang fehl, wenn destination.txt existiert.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback)

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

[Versionsgeschichte]

Version	Änderungen
v22.3.0	Diese API ist nicht mehr experimentell.
v20.1.0, v18.17.0	Akzeptiert eine zusätzliche mode-Option, um das Kopierverhalten als mode-Argument von fs.copyFile() anzugeben.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v17.6.0, v16.15.0	Akzeptiert eine zusätzliche verbatimSymlinks-Option, um anzugeben, ob die Pfadauflösung für symbolische Links durchgeführt werden soll.
v16.7.0	Hinzugefügt in: v16.7.0

• src <string> | <URL> Quellpfad zum Kopieren.

• dest <string> | <URL> Zielpfad zum Kopieren.

• options <Object>

  • dereference <boolean> Symbolische Links auflösen. Standard: false.

  • errorOnExist <boolean> Wenn force false ist und das Ziel existiert, wird ein Fehler ausgelöst. Standard: false.

  • filter <Function> Funktion zum Filtern kopierter Dateien/Verzeichnisse. Gibt true zurück, um das Element zu kopieren, false, um es zu ignorieren. Wenn ein Verzeichnis ignoriert wird, wird auch der gesamte Inhalt übersprungen. Kann auch ein Promise zurückgeben, das mit true oder false aufgelöst wird. Standard: undefined.

  • src <string> Quellpfad zum Kopieren.

  • dest <string> Zielpfad zum Kopieren.

  • Gibt zurück: <boolean> | <Promise> Ein Wert, der in einen booleschen Wert umgewandelt werden kann, oder ein Promise, das mit einem solchen Wert erfüllt wird.

  • force <boolean> Bestehende Datei oder Verzeichnis überschreiben. Der Kopiervorgang ignoriert Fehler, wenn Sie dies auf false setzen und das Ziel existiert. Verwenden Sie die Option errorOnExist, um dieses Verhalten zu ändern. Standard: true.

  • mode <integer> Modifikatoren für den Kopiervorgang. Standard: 0. Siehe mode-Flag von fs.copyFile().

  • preserveTimestamps <boolean> Wenn true, werden Zeitstempel von src beibehalten. Standard: false.

  • recursive <boolean> Verzeichnisse rekursiv kopieren. Standard: false

  • verbatimSymlinks <boolean> Wenn true, wird die Pfadauflösung für symbolische Links übersprungen. Standard: false

• callback <Function>

  • err <Error>

Kopiert asynchron die gesamte Verzeichnisstruktur von src nach dest, einschließlich Unterverzeichnisse und Dateien.

Beim Kopieren eines Verzeichnisses in ein anderes Verzeichnis werden keine Globs unterstützt, und das Verhalten ähnelt cp dir1/ dir2/.

fs.createReadStream(path[, options])

[Historie]

Version	Änderungen
v16.10.0	Die Option fs benötigt keine open-Methode, wenn ein fd bereitgestellt wurde.
v16.10.0	Die Option fs benötigt keine close-Methode, wenn autoClose auf false gesetzt ist.
v15.5.0	Unterstützung für AbortSignal hinzugefügt.
v15.4.0	Die Option fd akzeptiert FileHandle-Argumente.
v14.0.0	Standardwert von emitClose auf true geändert.
v13.6.0, v12.17.0	Die fs-Optionen ermöglichen das Überschreiben der verwendeten fs-Implementierung.
v12.10.0	Option emitClose aktiviert.
v11.0.0	Neue Einschränkungen für start und end eingeführt, wobei in Fällen, in denen die Eingabewerte nicht sinnvoll verarbeitet werden können, aussagekräftigere Fehler geworfen werden.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Das übergebene options-Objekt wird niemals modifiziert.
v2.3.0	Das übergebene options-Objekt kann jetzt eine Zeichenkette sein.
v0.1.31	Hinzugefügt in: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> Siehe Unterstützung von Dateisystem flags. Standard: 'r'.
  • encoding <string> Standard: null
  • fd <integer> | <FileHandle> Standard: null
  • mode <integer> Standard: 0o666
  • autoClose <boolean> Standard: true
  • emitClose <boolean> Standard: true
  • start <integer>
  • end <integer> Standard: Infinity
  • highWaterMark <integer> Standard: 64 * 1024
  • fs <Object> | <null> Standard: null
  • signal <AbortSignal> | <null> Standard: null

• Rückgabewert: <fs.ReadStream>

options kann start und end Werte enthalten, um einen Bereich von Bytes aus der Datei anstatt der gesamten Datei zu lesen. Sowohl start als auch end sind inklusiv und beginnen bei 0. Zulässige Werte liegen im Bereich [0, Number.MAX_SAFE_INTEGER]. Wenn fd angegeben ist und start ausgelassen oder undefined ist, liest fs.createReadStream() sequentiell von der aktuellen Dateiposition. encoding kann jeder der von <Buffer> akzeptierten sein.

Wenn fd angegeben ist, ignoriert ReadStream das Argument path und verwendet den angegebenen Dateideskriptor. Das bedeutet, dass kein 'open'-Ereignis emittiert wird. fd sollte blockierend sein; nicht blockierende fds sollten an <net.Socket> übergeben werden.

Wenn fd auf ein Zeichengerät verweist, das nur blockierende Lesevorgänge unterstützt (z. B. Tastatur oder Soundkarte), beenden Lesevorgänge erst, wenn Daten verfügbar sind. Dies kann verhindern, dass der Prozess beendet wird und der Stream auf natürliche Weise geschlossen wird.

Standardmäßig emittiert der Stream ein 'close'-Ereignis, nachdem er zerstört wurde. Setzen Sie die Option emitClose auf false, um dieses Verhalten zu ändern.

Durch die Angabe der Option fs ist es möglich, die entsprechenden fs-Implementierungen für open, read und close zu überschreiben. Bei Angabe der Option fs ist ein Überschreiben von read erforderlich. Wenn kein fd angegeben ist, ist auch ein Überschreiben von open erforderlich. Wenn autoClose auf true gesetzt ist, ist auch ein Überschreiben von close erforderlich.

import { createReadStream } from 'node:fs'

// Erstellt einen Stream von einem Zeichengerät.
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
  stream.close() // Dies schließt den Stream möglicherweise nicht.
  // Künstliches Markieren des Endes des Streams, als ob die zugrunde liegende Ressource
  // selbst das Ende der Datei angezeigt hätte, ermöglicht das Schließen des Streams.
  // Dies bricht keine ausstehenden Lesevorgänge ab, und wenn ein solcher Vorgang vorhanden ist,
  // kann der Prozess möglicherweise immer noch nicht erfolgreich beendet werden, bis er abgeschlossen ist.
  stream.push(null)
  stream.read(0)
}, 100)

Wenn autoClose auf false gesetzt ist, wird der Dateideskriptor nicht geschlossen, selbst wenn ein Fehler auftritt. Es liegt in der Verantwortung der Anwendung, ihn zu schließen und sicherzustellen, dass kein Dateideskriptor-Leck entsteht. Wenn autoClose auf true gesetzt ist (Standardverhalten), wird der Dateideskriptor bei 'error' oder 'end' automatisch geschlossen.

mode legt den Dateimodus (Berechtigungen und Sticky-Bits) fest, aber nur, wenn die Datei erstellt wurde.

Ein Beispiel zum Lesen der letzten 10 Bytes einer Datei mit einer Länge von 100 Bytes:

import { createReadStream } from 'node:fs'

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

Wenn options eine Zeichenkette ist, gibt diese die Kodierung an.

fs.createWriteStream(path[, options])

[Verlauf]

Version	Änderungen
v21.0.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v16.10.0	Die Option fs benötigt keine open-Methode, wenn ein fd bereitgestellt wurde.
v16.10.0	Die Option fs benötigt keine close-Methode, wenn autoClose false ist.
v15.5.0	Unterstützung für AbortSignal hinzugefügt.
v15.4.0	Die Option fd akzeptiert FileHandle-Argumente.
v14.0.0	Standardwert von emitClose auf true geändert.
v13.6.0, v12.17.0	Die fs-Optionen ermöglichen das Überschreiben der verwendeten fs-Implementierung.
v12.10.0	Option emitClose aktiviert.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Das übergebene options-Objekt wird niemals modifiziert.
v5.5.0	Die Option autoClose wird jetzt unterstützt.
v2.3.0	Das übergebene options-Objekt kann jetzt eine Zeichenkette sein.
v0.1.31	Hinzugefügt in: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> Siehe Unterstützung von Dateisystem-flags. Standard: 'w'.
  • encoding <string> Standard: 'utf8'
  • fd <integer> | <FileHandle> Standard: null
  • mode <integer> Standard: 0o666
  • autoClose <boolean> Standard: true
  • emitClose <boolean> Standard: true
  • start <integer>
  • fs <Object> | <null> Standard: null
  • signal <AbortSignal> | <null> Standard: null
  • highWaterMark <number> Standard: 16384
  • flush <boolean> Wenn true, wird der zugrunde liegende Dateideskriptor vor dem Schließen geleert. Standard: false.

• Rückgabewert: <fs.WriteStream>

options kann auch eine start-Option enthalten, um das Schreiben von Daten an einer Position hinter dem Dateianfang zu ermöglichen. Zulässige Werte liegen im Bereich [0, Number.MAX_SAFE_INTEGER]. Das Ändern einer Datei anstelle des Ersetzens kann erfordern, dass die Option flags auf r+ anstelle des Standardwerts w gesetzt wird. Die encoding kann eine beliebige der von <Buffer> akzeptierten sein.

Wenn autoClose auf true gesetzt ist (Standardverhalten), wird der Dateideskriptor bei 'error' oder 'finish' automatisch geschlossen. Wenn autoClose false ist, wird der Dateideskriptor nicht geschlossen, selbst wenn ein Fehler auftritt. Es liegt in der Verantwortung der Anwendung, ihn zu schließen und sicherzustellen, dass kein Dateideskriptor-Leak auftritt.

Standardmäßig sendet der Stream ein 'close'-Ereignis, nachdem er zerstört wurde. Setzen Sie die Option emitClose auf false, um dieses Verhalten zu ändern.

Durch die Bereitstellung der Option fs ist es möglich, die entsprechenden fs-Implementierungen für open, write, writev und close zu überschreiben. Das Überschreiben von write() ohne writev() kann die Leistung verringern, da einige Optimierungen (_writev()) deaktiviert werden. Bei Angabe der Option fs sind Überschreibungen für mindestens eine von write und writev erforderlich. Wenn keine fd-Option angegeben ist, ist auch eine Überschreibung für open erforderlich. Wenn autoClose true ist, ist auch eine Überschreibung für close erforderlich.

Wie bei <fs.ReadStream> ignoriert <fs.WriteStream>, wenn fd angegeben ist, das path-Argument und verwendet den angegebenen Dateideskriptor. Dies bedeutet, dass kein 'open'-Ereignis ausgelöst wird. fd sollte blockierend sein; nicht blockierende fds sollten an <net.Socket> übergeben werden.

Wenn options eine Zeichenkette ist, gibt sie die Kodierung an.

fs.exists(path, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v1.0.0	Veraltet seit: v1.0.0
v0.0.2	Hinzugefügt in: v0.0.2

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen fs.stat() oder fs.access().

• path <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

Überprüft, ob das Element am angegebenen path im Dateisystem existiert. Ruft dann das callback-Argument mit entweder true oder false auf:

import { exists } from 'node:fs'

exists('/etc/passwd', e => {
  console.log(e ? 'es existiert' : 'kein passwd!')
})

Die Parameter für diesen Callback sind nicht konsistent mit anderen Node.js-Callbacks. Normalerweise ist der erste Parameter eines Node.js-Callbacks ein err-Parameter, optional gefolgt von anderen Parametern. Der fs.exists()-Callback hat nur einen booleschen Parameter. Dies ist ein Grund, warum fs.access() anstelle von fs.exists() empfohlen wird.

Wenn path ein symbolischer Link ist, wird diesem gefolgt. Wenn also path existiert, aber auf ein nicht existierendes Element verweist, erhält der Callback den Wert false.

Die Verwendung von fs.exists() zum Überprüfen der Existenz einer Datei, bevor fs.open(), fs.readFile() oder fs.writeFile() aufgerufen wird, wird nicht empfohlen. Dies führt zu einem Race Condition, da andere Prozesse den Zustand der Datei zwischen den beiden Aufrufen ändern können. Stattdessen sollte der Benutzercode die Datei direkt öffnen/lesen/schreiben und den Fehler behandeln, der ausgelöst wird, wenn die Datei nicht existiert.

Schreiben (NICHT EMPFOHLEN)

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

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

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

Schreiben (EMPFOHLEN)

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

    throw err
  }

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

Lesen (NICHT EMPFOHLEN)

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 existiert nicht')
  }
})

Lesen (EMPFOHLEN)

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

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile existiert nicht')
      return
    }

    throw err
  }

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

Die oben genannten "nicht empfohlenen" Beispiele prüfen auf Existenz und verwenden dann die Datei; die "empfohlenen" Beispiele sind besser, da sie die Datei direkt verwenden und den Fehler, falls vorhanden, behandeln.

Im Allgemeinen sollte nur dann auf die Existenz einer Datei geprüft werden, wenn die Datei nicht direkt verwendet wird, z. B. wenn ihre Existenz ein Signal von einem anderen Prozess ist.

fs.fchmod(fd, mode, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.4.7	Hinzugefügt in: v0.4.7

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

Legt die Berechtigungen für die Datei fest. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Weitere Informationen finden Sie in der POSIX fchmod(2) Dokumentation.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.4.7	Hinzugefügt in: v0.4.7

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

Legt den Besitzer der Datei fest. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Weitere Informationen finden Sie in der POSIX fchown(2) Dokumentation.

fs.fdatasync(fd, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.0.0	Der Parameter callback ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v0.1.96	Hinzugefügt in: v0.1.96

• fd <integer>
• callback <Function>
  • err <Error>

Zwingt alle aktuell gepufferten E/A-Operationen, die mit der Datei verbunden sind, in den synchronisierten E/A-Abschlusszustand des Betriebssystems. Einzelheiten finden Sie in der POSIX fdatasync(2) Dokumentation. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte bigint sein sollen.
v10.0.0	Der Parameter callback ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.0.0	Der Parameter callback ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v0.1.95	Hinzugefügt in: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats>-Objekt bigint sein sollen. Standard: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Ruft den Callback mit den <fs.Stats> für den Dateideskriptor auf.

Weitere Details finden Sie in der POSIX fstat(2) Dokumentation.

fs.fsync(fd, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.1.96	Hinzugefügt in: v0.1.96

• fd <Integer>
• callback <Funktion>
  • err <Error>

Fordert an, dass alle Daten für den geöffneten Dateideskriptor auf das Speichergerät geschrieben werden. Die spezifische Implementierung ist betriebssystemspezifisch und gerätespezifisch. Weitere Details finden Sie in der POSIX fsync(2) Dokumentation. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.8.6	Hinzugefügt in: v0.8.6

• fd <Integer>
• len <Integer> Standard: 0
• callback <Funktion>
  • err <Error>

Stutzt den Dateideskriptor. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Siehe die POSIX ftruncate(2) Dokumentation für weitere Details.

War die Datei, auf die der Dateideskriptor verweist, größer als len Bytes, bleiben nur die ersten len Bytes in der Datei erhalten.

Das folgende Programm behält beispielsweise nur die ersten vier Bytes der Datei bei:

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
  }
})

War die Datei vorher kürzer als len Bytes, wird sie erweitert, und der erweiterte Teil wird mit Nullbytes ('\0') gefüllt:

Ist len negativ, wird 0 verwendet.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v4.1.0	Numerische Zeichenketten, NaN und Infinity sind jetzt als Zeitangaben zulässig.
v0.4.2	Hinzugefügt in: v0.4.2

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

Ändert die Zeitstempel des Dateisystems des durch den angegebenen Dateideskriptor referenzierten Objekts. Siehe fs.utimes().

fs.glob(pattern[, options], callback)

[Verlauf]

Version	Änderungen
v22.2.0	Unterstützung für withFileTypes als Option hinzugefügt.
v22.0.0	Hinzugefügt in: v22.0.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> aktuelles Arbeitsverzeichnis. Standard: process.cwd()
  • exclude <Function> Funktion zum Filtern von Dateien/Verzeichnissen. Gibt true zurück, um das Element auszuschließen, false, um es einzuschließen. Standard: undefined.
  • withFileTypes <boolean> true, wenn der Glob Pfade als Dirents zurückgeben soll, andernfalls false. Standard: false.

• callback <Function>

  • err <Error>

• Ruft die Dateien ab, die mit dem angegebenen Muster übereinstimmen.

ESM

import { glob } from 'node:fs'

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

CJS

const { glob } = require('node:fs')

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

fs.lchmod(path, mode, callback)

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v16.0.0	Der zurückgegebene Fehler kann ein AggregateError sein, wenn mehr als ein Fehler zurückgegeben wird.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v0.4.7	Seit v0.4.7 veraltet

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

Ändert die Berechtigungen eines symbolischen Links. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Diese Methode ist nur unter macOS implementiert.

Weitere Details finden Sie in der POSIX lchmod(2) Dokumentation.

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

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.6.0	Diese API ist nicht mehr veraltet.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v0.4.7	Nur Dokumentations-Veralterung.

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

Setzt den Besitzer des symbolischen Links. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Weitere Details finden Sie in der POSIX lchown(2) Dokumentation.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v14.5.0, v12.19.0	Hinzugefügt in: v14.5.0, v12.19.0

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

Ändert die Zugriffs- und Änderungszeiten einer Datei auf die gleiche Weise wie fs.utimes(), mit dem Unterschied, dass, wenn der Pfad auf einen symbolischen Link verweist, der Link nicht dereferenziert wird: Stattdessen werden die Zeitstempel des symbolischen Links selbst geändert.

Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

fs.link(existingPath, newPath, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Die Parameter existingPath und newPath können WHATWG URL-Objekte mit dem Protokoll file: sein. Die Unterstützung ist derzeit noch experimentell.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.1.31	Hinzugefügt in: v0.1.31

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

Erstellt einen neuen Link von existingPath zu newPath. Siehe die POSIX link(2) Dokumentation für weitere Details. Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte BigInts sein sollen.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.1.30	Hinzugefügt in: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats>-Objekt bigint sein sollen. Standard: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Ruft die <fs.Stats> für den symbolischen Link ab, auf den der Pfad verweist. Der Callback erhält zwei Argumente (err, stats), wobei stats ein <fs.Stats>-Objekt ist. lstat() ist identisch mit stat(), außer dass, wenn path ein symbolischer Link ist, der Link selbst geprüft wird, nicht die Datei, auf die er verweist.

Siehe die POSIX lstat(2) Dokumentation für weitere Details.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v13.11.0, v12.17.0	Im recursive-Modus erhält der Callback jetzt den ersten erstellten Pfad als Argument.
v10.12.0	Das zweite Argument kann jetzt ein options-Objekt mit den Eigenschaften recursive und mode sein.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem file:-Protokoll sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v0.1.8	Hinzugefügt in: v0.1.8

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> Standard: false
  • mode <string> | <integer> Wird unter Windows nicht unterstützt. Standard: 0o777.

• callback <Function>

  • err <Error>
  • path <string> | <undefined> Nur vorhanden, wenn ein Verzeichnis mit recursive auf true erstellt wird.

Erstellt asynchron ein Verzeichnis.

Der Callback erhält eine mögliche Ausnahme und, wenn recursive true ist, den ersten erstellten Verzeichnispfad, (err[, path]). path kann auch dann undefined sein, wenn recursive true ist, wenn kein Verzeichnis erstellt wurde (z. B. wenn es bereits vorher erstellt wurde).

Das optionale options-Argument kann eine ganze Zahl sein, die mode (Berechtigungen und Sticky Bits) angibt, oder ein Objekt mit einer mode-Eigenschaft und einer recursive-Eigenschaft, die angibt, ob übergeordnete Verzeichnisse erstellt werden sollen. Ein Aufruf von fs.mkdir(), wenn path ein bereits existierendes Verzeichnis ist, führt nur dann zu einem Fehler, wenn recursive false ist. Wenn recursive false ist und das Verzeichnis existiert, tritt ein EEXIST-Fehler auf.

import { mkdir } from 'node:fs'

// Erstellt ./tmp/a/apple, unabhängig davon, ob ./tmp und ./tmp/a existieren.
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

Unter Windows führt die Verwendung von fs.mkdir() im Stammverzeichnis selbst mit Rekursion zu einem Fehler:

import { mkdir } from 'node:fs'

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

Siehe die POSIX mkdir(2) Dokumentation für weitere Details.

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

[Historie]

Version	Änderungen
v20.6.0, v18.19.0	Der Parameter prefix akzeptiert jetzt Puffer und URLs.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v16.5.0, v14.18.0	Der Parameter prefix akzeptiert jetzt eine leere Zeichenkette.
v10.0.0	Der Parameter callback ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.0.0	Der Parameter callback ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v6.2.1	Der Parameter callback ist jetzt optional.
v5.10.0	Hinzugefügt in: v5.10.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• callback <Function>

  • err <Error>
  • directory <string>

Erstellt ein eindeutiges temporäres Verzeichnis.

Generiert sechs zufällige Zeichen, die an ein erforderliches prefix angehängt werden, um ein eindeutiges temporäres Verzeichnis zu erstellen. Aufgrund von Plattforminkonsistenzen sollten nachgestellte X-Zeichen im prefix vermieden werden. Einige Plattformen, insbesondere die BSDs, können mehr als sechs zufällige Zeichen zurückgeben und nachgestellte X-Zeichen im prefix durch zufällige Zeichen ersetzen.

Der Pfad des erstellten Verzeichnisses wird als Zeichenkette an den zweiten Parameter des Callbacks übergeben.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung angibt.

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)
  // Gibt aus: /tmp/foo-itXde2 oder C:\Users\...\AppData\Local\Temp\foo-itXde2
})

Die Methode fs.mkdtemp() hängt die sechs zufällig ausgewählten Zeichen direkt an die prefix-Zeichenkette an. Wenn beispielsweise ein Verzeichnis /tmp vorhanden ist und die Absicht besteht, ein temporäres Verzeichnis innerhalb von /tmp zu erstellen, muss das prefix mit einem plattformspezifischen Pfadtrennzeichen enden (require('node:path').sep).

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

// Das übergeordnete Verzeichnis für das neue temporäre Verzeichnis
const tmpDir = tmpdir()

// Diese Methode ist *FALSCH*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Gibt etwas Ähnliches wie `/tmpabc123` aus.
  // Ein neues temporäres Verzeichnis wird im Stamm des Dateisystems erstellt,
  // anstatt *innerhalb* des `/tmp`-Verzeichnisses.
})

// Diese Methode ist *RICHTIG*:
import { sep } from 'node:path'
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Gibt etwas Ähnliches wie `/tmp/abc123` aus.
  // Ein neues temporäres Verzeichnis wird innerhalb
  // des `/tmp`-Verzeichnisses erstellt.
})

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

[Versionsgeschichte]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v11.1.0	Das Argument flags ist nun optional und standardmäßig auf 'r' gesetzt.
v9.9.0	Die Flags as und as+ werden nun unterstützt.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.0.2	Hinzugefügt in: v0.0.2

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Siehe Unterstützung von Dateisystem-flags. Standard: 'r'.
• mode <string> | <integer> Standard: 0o666 (lesbar und beschreibbar)
• callback <Function>
  • err <Error>
  • fd <integer>

Asynchrones Öffnen von Dateien. Weitere Details finden Sie in der POSIX open(2) Dokumentation.

mode setzt den Dateimodus (Berechtigungen und Sticky Bits), aber nur, wenn die Datei erstellt wurde. Unter Windows kann nur die Schreibberechtigung manipuliert werden; siehe fs.chmod().

Der Callback erhält zwei Argumente (err, fd).

Einige Zeichen (\< \> : " / \ | ? *) sind unter Windows reserviert, wie in Benennen von Dateien, Pfaden und Namespaces dokumentiert. Unter NTFS öffnet Node.js, wenn der Dateiname einen Doppelpunkt enthält, einen Dateisystemstrom, wie auf dieser MSDN-Seite beschrieben.

Auf fs.open() basierende Funktionen zeigen dieses Verhalten ebenfalls: fs.writeFile(), fs.readFile() usw.

fs.openAsBlob(path[, options])

Hinzugefügt in: v19.8.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• path <string> | <Buffer> | <URL>

• options <Object>

  • type <string> Ein optionaler MIME-Typ für das Blob.

• Rückgabewert: <Promise> Löst mit einem <Blob> bei Erfolg auf.

Gibt ein <Blob> zurück, dessen Daten vom angegebenen File unterstützt werden.

Die Datei darf nach der Erstellung des <Blob> nicht mehr verändert werden. Jegliche Änderungen führen dazu, dass das Lesen der <Blob>-Daten mit einem DOMException-Fehler fehlschlägt. Synchrone Stat-Operationen an der Datei werden beim Erstellen des Blob und vor jeder Leseoperation durchgeführt, um zu erkennen, ob die Datei-Daten auf der Festplatte verändert wurden.

ESM

import { openAsBlob } from 'node:fs'

const blob = await openAsBlob('the.file.txt')
const ab = await blob.arrayBuffer()
blob.stream()

CJS

const { openAsBlob } = require('node:fs')

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

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

[Verlauf]

Version	Änderungen
v20.1.0, v18.17.0	Option recursive hinzugefügt.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v13.1.0, v12.16.0	Die Option bufferSize wurde eingeführt.
v12.12.0	Hinzugefügt in: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> Standard: 'utf8'
  • bufferSize <number> Anzahl der Verzeichniseinträge, die intern beim Lesen aus dem Verzeichnis gepuffert werden. Höhere Werte führen zu einer besseren Leistung, aber zu einem höheren Speicherverbrauch. Standard: 32
  • recursive <boolean> Standard: false

• callback <Function>

  • err <Error>
  • dir <fs.Dir>

Öffnet asynchron ein Verzeichnis. Weitere Informationen finden Sie in der POSIX-Dokumentation zu opendir(3).

Erstellt ein <fs.Dir>, das alle weiteren Funktionen zum Lesen von und Bereinigen des Verzeichnisses enthält.

Die Option encoding legt die Codierung für den path beim Öffnen des Verzeichnisses und bei nachfolgenden Lesevorgängen fest.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.10.0	Der Parameter buffer kann nun ein beliebiges TypedArray oder ein DataView sein.
v7.4.0	Der Parameter buffer kann nun ein Uint8Array sein.
v6.0.0	Der Parameter length kann nun 0 sein.
v0.0.2	Hinzugefügt in: v0.0.2

• fd <Integer>
• buffer <Buffer> | <TypedArray> | <DataView> Der Puffer, in den die Daten geschrieben werden.
• offset <Integer> Die Position in buffer, an die die Daten geschrieben werden sollen.
• length <Integer> Die Anzahl der zu lesenden Bytes.
• position <Integer> | <BigInt> | <Null> Gibt an, wo mit dem Lesen in der Datei begonnen werden soll. Wenn position null oder -1 ist, werden Daten ab der aktuellen Dateiposition gelesen, und die Dateiposition wird aktualisiert. Wenn position eine nicht-negative ganze Zahl ist, bleibt die Dateiposition unverändert.
• callback <Funktion>
  • err <Error>
  • bytesRead <Integer>
  • buffer <Buffer>

Liest Daten aus der durch fd angegebenen Datei.

Der Callback erhält die drei Argumente (err, bytesRead, buffer).

Wenn die Datei nicht gleichzeitig geändert wird, wird das Dateiende erreicht, wenn die Anzahl der gelesenen Bytes Null ist.

Wenn diese Methode als ihre util.promisify()ierte Version aufgerufen wird, gibt sie ein Promise für ein Object mit den Eigenschaften bytesRead und buffer zurück.

Die Methode fs.read() liest Daten aus der Datei, die durch den Dateideskriptor (fd) angegeben ist. Das Argument length gibt die maximale Anzahl von Bytes an, die Node.js versuchen wird, vom Kernel zu lesen. Die tatsächlich gelesene Byteanzahl (bytesRead) kann jedoch aus verschiedenen Gründen niedriger sein als die angegebene length.

Beispielsweise:

• Wenn die Datei kürzer als die angegebene length ist, wird bytesRead auf die tatsächlich gelesene Byteanzahl gesetzt.
• Wenn die Datei EOF (End of File) erreicht, bevor der Puffer gefüllt werden konnte, liest Node.js alle verfügbaren Bytes bis zum Erreichen von EOF, und der Parameter bytesRead im Callback gibt die tatsächlich gelesene Byteanzahl an, die möglicherweise kleiner als die angegebene length ist.
• Wenn sich die Datei auf einem langsamen Netzwerk-filesystem befindet oder während des Lesens auf andere Probleme stößt, kann bytesRead kleiner als die angegebene length sein.

Daher ist es bei der Verwendung von fs.read() wichtig, den Wert von bytesRead zu überprüfen, um festzustellen, wie viele Bytes tatsächlich aus der Datei gelesen wurden. Abhängig von Ihrer Anwendungslogik müssen Sie möglicherweise Fälle behandeln, in denen bytesRead kleiner als die angegebene length ist, z. B. indem Sie den Lesevorgang in eine Schleife einbetten, wenn Sie eine Mindestanzahl von Bytes benötigen.

Dieses Verhalten ähnelt der POSIX-Funktion preadv2.

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

[Historie]

Version	Änderungen
v13.11.0, v12.17.0	Ein Options-Objekt kann übergeben werden, um buffer, offset, length und position optional zu machen.
v13.11.0, v12.17.0	Hinzugefügt in: v13.11.0, v12.17.0

• fd <integer>

• options <Object>

  • buffer <Buffer> | <TypedArray> | <DataView> Standard: Buffer.alloc(16384)
  • offset <integer> Standard: 0
  • length <integer> Standard: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Standard: null

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Ähnlich der Funktion fs.read() nimmt diese Version ein optionales options-Objekt entgegen. Wird kein options-Objekt angegeben, werden die oben genannten Standardwerte verwendet.

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

Hinzugefügt in: v18.2.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView> Der Puffer, in den die Daten geschrieben werden.

• options <Object>

  • offset <integer> Standardwert: 0
  • length <integer> Standardwert: buffer.byteLength - offset
  • position <integer> | <bigint> Standardwert: null

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Ähnlich der Funktion fs.read() verwendet diese Version ein optionales options-Objekt. Wenn kein options-Objekt angegeben ist, werden die oben genannten Werte als Standard verwendet.

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

[Verlauf]

Version	Änderungen
v20.1.0, v18.17.0	Option recursive hinzugefügt.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.10.0	Neue Option withFileTypes hinzugefügt.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v6.0.0	Der options-Parameter wurde hinzugefügt.
v0.1.8	Hinzugefügt in: v0.1.8

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standardwert: 'utf8'
  • withFileTypes <boolean> Standardwert: false
  • recursive <boolean> Wenn true, liest den Inhalt eines Verzeichnisses rekursiv. Im rekursiven Modus werden alle Dateien, Unterdateien und Verzeichnisse aufgelistet. Standardwert: false.

• callback <Function>

  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

Liest den Inhalt eines Verzeichnisses. Der Callback erhält zwei Argumente (err, files), wobei files ein Array der Namen der Dateien im Verzeichnis ist, ausgenommen '.' und '..'.

Siehe die POSIX readdir(3) Dokumentation für weitere Details.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer Eigenschaft encoding, die die zu verwendende Zeichencodierung für die an den Callback übergebenen Dateinamen angibt. Wenn encoding auf 'buffer' gesetzt ist, werden die zurückgegebenen Dateinamen als <Buffer> Objekte übergeben.

Wenn options.withFileTypes auf true gesetzt ist, enthält das Array files <fs.Dirent> Objekte.

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

[Versionsgeschichte]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v16.0.0	Der zurückgegebene Fehler kann ein AggregateError sein, wenn mehr als ein Fehler zurückgegeben wird.
v15.2.0, v14.17.0	Das options-Argument kann ein AbortSignal enthalten, um eine laufende readFile-Anfrage abzubrechen.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem file:-Protokoll sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v5.1.0	Der callback wird im Erfolgsfall immer mit null als error-Parameter aufgerufen.
v5.0.0	Der path-Parameter kann nun ein File Descriptor sein.
v0.1.29	Hinzugefügt in: v0.1.29

• path <string> | <Buffer> | <URL> | <integer> Dateiname oder File Descriptor

• options <Object> | <string>

  • encoding <string> | <null> Standard: null
  • flag <string> Siehe Unterstützung von Dateisystem-flags. Standard: 'r'.
  • signal <AbortSignal> ermöglicht das Abbrechen einer laufenden readFile-Anfrage

• callback <Function>

  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

Liest asynchron den gesamten Inhalt einer Datei.

import { readFile } from 'node:fs'

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

Der Callback erhält zwei Argumente (err, data), wobei data der Inhalt der Datei ist.

Wenn keine Kodierung angegeben ist, wird der Rohbuffer zurückgegeben.

Wenn options eine Zeichenkette ist, gibt diese die Kodierung an:

import { readFile } from 'node:fs'

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

Wenn der Pfad ein Verzeichnis ist, ist das Verhalten von fs.readFile() und fs.readFileSync() plattformabhängig. Unter macOS, Linux und Windows wird ein Fehler zurückgegeben. Unter FreeBSD wird eine Darstellung des Inhalts des Verzeichnisses zurückgegeben.

import { readFile } from 'node:fs'

// macOS, Linux und Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegale Operation auf einem Verzeichnis, read <directory>]
})

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

Es ist möglich, eine laufende Anfrage mit einem AbortSignal abzubrechen. Wenn eine Anfrage abgebrochen wird, wird der Callback mit einem AbortError aufgerufen:

import { readFile } from 'node:fs'

const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
})
// Wenn Sie die Anfrage abbrechen möchten
controller.abort()

Die Funktion fs.readFile() puffert die gesamte Datei. Um den Speicherbedarf zu minimieren, bevorzugen Sie nach Möglichkeit das Streaming über fs.createReadStream().

Das Abbrechen einer laufenden Anfrage bricht nicht einzelne Betriebssystemanforderungen ab, sondern eher die interne Pufferung, die fs.readFile durchführt.

Dateideskriptoren

Leistungsaspekte

Die Methode fs.readFile() liest den Inhalt einer Datei asynchron und abschnittsweise in den Speicher, wodurch der Event-Loop zwischen den einzelnen Abschnitten wechseln kann. Dies ermöglicht es dem Lesevorgang, weniger Einfluss auf andere Aktivitäten zu haben, die den zugrunde liegenden libuv-Thread-Pool verwenden, bedeutet aber auch, dass das Lesen einer vollständigen Datei in den Speicher länger dauert.

Der zusätzliche Lese-Overhead kann auf verschiedenen Systemen stark variieren und hängt von der Art der zu lesenden Datei ab. Wenn es sich bei der Datei nicht um eine reguläre Datei (z. B. eine Pipe) handelt und Node.js keine tatsächliche Dateigröße ermitteln kann, wird bei jedem Lesevorgang 64 KiB Daten geladen. Bei regulären Dateien verarbeitet jeder Lesevorgang 512 KiB Daten.

Für Anwendungen, die ein möglichst schnelles Lesen des Dateiinhalts erfordern, ist es besser, fs.read() direkt zu verwenden und den Lesevorgang des vollständigen Dateiinhalts selbst durch den Anwendungscode zu verwalten.

Das Node.js GitHub-Issue #25741 bietet weitere Informationen und eine detaillierte Analyse der Leistung von fs.readFile() für verschiedene Dateigrößen in verschiedenen Node.js-Versionen.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.1.31	Hinzugefügt in: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• callback <Function>

  • err <Error>
  • linkString <string> | <Buffer>

Liest den Inhalt des symbolischen Links, auf den sich path bezieht. Der Callback erhält zwei Argumente (err, linkString).

Weitere Details finden Sie in der POSIX-Dokumentation zu readlink(2).

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer Eigenschaft encoding, die die zu verwendende Zeichencodierung für den an den Callback übergebenen Linkpfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Linkpfad als <Buffer>-Objekt übergeben.

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

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v13.13.0, v12.17.0	Hinzugefügt in: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Standardwert: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

Liest von einer durch fd angegebenen Datei und schreibt mit readv() in ein Array von ArrayBufferViews.

position ist der Offset vom Dateianfang, von dem aus Daten gelesen werden sollen. Wenn typeof position !== 'number', werden die Daten von der aktuellen Position gelesen.

Der Callback erhält drei Argumente: err, bytesRead und buffers. bytesRead gibt an, wie viele Bytes aus der Datei gelesen wurden.

Wenn diese Methode als ihre util.promisify()-Version aufgerufen wird, gibt sie ein Promise für ein Object mit den Eigenschaften bytesRead und buffers zurück.

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

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v8.0.0	Unterstützung für Pipe/Socket-Auflösung wurde hinzugefügt.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v6.4.0	Das Aufrufen von realpath funktioniert jetzt wieder für verschiedene Randfälle unter Windows.
v6.0.0	Der cache-Parameter wurde entfernt.
v0.1.31	Hinzugefügt in: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standardwert: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

Berechnet asynchron den kanonischen Pfadnamen durch Auflösen von ., .. und symbolischen Links.

Ein kanonischer Pfadname ist nicht unbedingt eindeutig. Hardlinks und Bind Mounts können eine Datei-System-Entität über viele Pfadnamen verfügbar machen.

Diese Funktion verhält sich wie realpath(3), mit einigen Ausnahmen:

Der callback erhält zwei Argumente (err, resolvedPath). Kann process.cwd verwenden, um relative Pfade aufzulösen.

Nur Pfade, die in UTF8-Strings konvertiert werden können, werden unterstützt.

Das optionale options-Argument kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung für den an den Callback übergebenen Pfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Pfad als <Buffer>-Objekt übergeben.

Wenn path zu einer Socket oder einer Pipe auflöst, gibt die Funktion einen system-abhängigen Namen für dieses Objekt zurück.

Ein Pfad, der nicht existiert, führt zu einem ENOENT-Fehler. error.path ist der absolute Dateipfad.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v9.2.0	Hinzugefügt in: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

Asynchrones realpath(3).

Das callback erhält zwei Argumente (err, resolvedPath).

Nur Pfade, die in UTF8-Strings konvertiert werden können, werden unterstützt.

Das optionale options-Argument kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung für den an das Callback übergebenen Pfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Pfad als <Buffer>-Objekt übergeben.

Unter Linux muss, wenn Node.js gegen musl libc verlinkt ist, das procfs-Dateisystem auf /proc gemountet sein, damit diese Funktion funktioniert. Glibc hat diese Einschränkung nicht.

fs.rename(oldPath, newPath, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Die Parameter oldPath und newPath können WHATWG URL-Objekte mit dem Protokoll file: sein. Die Unterstützung ist derzeit noch experimentell.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.0.2	Hinzugefügt in: v0.0.2

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

Benennt asynchron die Datei unter oldPath in den als newPath angegebenen Dateinamen um. Falls newPath bereits existiert, wird sie überschrieben. Wenn sich unter newPath ein Verzeichnis befindet, wird stattdessen ein Fehler ausgelöst. Dem Abschluss-Callback werden keine weiteren Argumente als eine mögliche Ausnahme übergeben.

Siehe auch: rename(2).

import { rename } from 'node:fs'

rename('oldFile.txt', 'newFile.txt', err => {
  if (err) throw err
  console.log('Umbenennung abgeschlossen!')
})

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v16.0.0	Die Verwendung von fs.rmdir(path, { recursive: true }) für einen path, der eine Datei ist, ist nicht mehr zulässig und führt unter Windows zu einem ENOENT-Fehler und unter POSIX zu einem ENOTDIR-Fehler.
v16.0.0	Die Verwendung von fs.rmdir(path, { recursive: true }) für einen path, der nicht existiert, ist nicht mehr zulässig und führt zu einem ENOENT-Fehler.
v16.0.0	Die Option recursive ist veraltet; ihre Verwendung löst eine Verwarnung aus.
v14.14.0	Die Option recursive ist veraltet; verwenden Sie stattdessen fs.rm.
v13.3.0, v12.16.0	Die Option maxBusyTries wurde in maxRetries umbenannt, und ihr Standardwert ist 0. Die Option emfileWait wurde entfernt, und EMFILE-Fehler verwenden dieselbe Wiederholungslogik wie andere Fehler. Die Option retryDelay wird jetzt unterstützt. ENFILE-Fehler werden jetzt wiederholt.
v12.10.0	Die Optionen recursive, maxBusyTries und emfileWait werden jetzt unterstützt.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Verwarnung mit der ID DEP0013 ausgegeben.
v0.0.2	Hinzugefügt in: v0.0.2

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> Wenn ein EBUSY, EMFILE, ENFILE, ENOTEMPTY oder EPERM-Fehler auftritt, wiederholt Node.js den Vorgang mit einer linearen exponentiellen Wartezeit von retryDelay Millisekunden länger bei jedem Versuch. Diese Option gibt die Anzahl der Wiederholungsversuche an. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 0.
  • recursive <boolean> Wenn true, wird ein rekursives Löschen des Verzeichnisses durchgeführt. Im rekursiven Modus werden Operationen bei Fehlern wiederholt. Standard: false. Veraltet.
  • retryDelay <integer> Die Wartezeit in Millisekunden zwischen Wiederholungsversuchen. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 100.

• callback <Function>

  • err <Error>

Asynchrones rmdir(2). Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Die Verwendung von fs.rmdir() für eine Datei (kein Verzeichnis) führt unter Windows zu einem ENOENT-Fehler und unter POSIX zu einem ENOTDIR-Fehler.

Um ein ähnliches Verhalten wie der Unix-Befehl rm -rf zu erhalten, verwenden Sie fs.rm() mit den Optionen { recursive: true, force: true }.

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

[Versionsgeschichte]

Version	Änderungen
v17.3.0, v16.14.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v14.14.0	Hinzugefügt in: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> Wenn true, werden Ausnahmen ignoriert, wenn path nicht existiert. Standardwert: false.
  • maxRetries <integer> Wenn ein EBUSY, EMFILE, ENFILE, ENOTEMPTY oder EPERM Fehler auftritt, wiederholt Node.js den Vorgang mit einer linearen Backoff-Wartezeit von retryDelay Millisekunden länger bei jedem Versuch. Diese Option gibt die Anzahl der Wiederholungsversuche an. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standardwert: 0.
  • recursive <boolean> Wenn true, wird eine rekursive Entfernung durchgeführt. Im rekursiven Modus werden Operationen bei Fehlern wiederholt. Standardwert: false.
  • retryDelay <integer> Die Wartezeit in Millisekunden zwischen Wiederholungsversuchen. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standardwert: 100.

• callback <Function>

  • err <Error>

Entfernt asynchron Dateien und Verzeichnisse (modelliert nach dem Standard-POSIX rm-Dienstprogramm). Dem Abschluss-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

fs.stat(pfad[, optionen], callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.5.0	Akzeptiert ein zusätzliches optionen-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte BigInts sein sollen.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der pfad-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.0.2	Hinzugefügt in: v0.0.2

• pfad <string> | <Buffer> | <URL>

• optionen <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats>-Objekt bigint sein sollen. Standard: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Asynchrones stat(2). Der Callback erhält zwei Argumente (err, stats), wobei stats ein <fs.Stats>-Objekt ist.

Im Fehlerfall ist err.code einer der Häufigen Systemfehler.

fs.stat() folgt symbolischen Links. Verwenden Sie fs.lstat(), um die Links selbst zu betrachten.

Die Verwendung von fs.stat() zum Überprüfen der Existenz einer Datei, bevor fs.open(), fs.readFile() oder fs.writeFile() aufgerufen wird, wird nicht empfohlen. Stattdessen sollte der Benutzercode die Datei direkt öffnen/lesen/schreiben und den Fehler behandeln, der ausgelöst wird, wenn die Datei nicht verfügbar ist.

Um zu überprüfen, ob eine Datei existiert, ohne sie anschließend zu manipulieren, wird fs.access() empfohlen.

Beispielsweise bei folgender Verzeichnisstruktur:

- txtDir
-- file.txt
- app.js

Das nächste Programm prüft die Statistiken der angegebenen Pfade:

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)
  })
}

Die resultierende Ausgabe sieht folgendermaßen aus:

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
}

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

Hinzugefügt in: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.StatFs> Objekt bigint sein sollen. Standard: false.

• callback <Function>

  • err <Error>
  • stats <fs.StatFs>

Asynchrones statfs(2). Gibt Informationen über das gemountete Dateisystem zurück, das path enthält. Der Callback erhält zwei Argumente (err, stats), wobei stats ein <fs.StatFs> Objekt ist.

Im Falle eines Fehlers ist err.code einer der Common System Errors.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v12.0.0	Wenn das type-Argument undefiniert bleibt, erkennt Node den target-Typ automatisch und wählt automatisch dir oder file.
v7.6.0	Die Parameter target und path können WHATWG URL-Objekte mit dem Protokoll file: sein. Die Unterstützung ist derzeit noch experimentell.
v0.1.31	Hinzugefügt in: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Standard: null
• callback <Function>
  • err <Error>

Erstellt den Link mit dem Namen path, der auf target verweist. Dem Completion-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

Siehe die POSIX symlink(2) Dokumentation für weitere Details.

Das type-Argument ist nur unter Windows verfügbar und wird auf anderen Plattformen ignoriert. Es kann auf 'dir', 'file' oder 'junction' gesetzt werden. Wenn das type-Argument null ist, erkennt Node.js den target-Typ automatisch und verwendet 'file' oder 'dir'. Wenn das target nicht existiert, wird 'file' verwendet. Windows-Verknüpfungspunkte erfordern, dass der Zielpfad absolut ist. Bei Verwendung von 'junction' wird das target-Argument automatisch auf den absoluten Pfad normalisiert. Verknüpfungspunkte auf NTFS-Volumes können nur auf Verzeichnisse verweisen.

Relative Ziele sind relativ zum übergeordneten Verzeichnis des Links.

import { symlink } from 'node:fs'

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

Das obige Beispiel erstellt einen symbolischen Link mewtwo, der auf mew im gleichen Verzeichnis verweist:

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

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben einer ungültigen Callback-Funktion an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v16.0.0	Der zurückgegebene Fehler kann ein AggregateError sein, wenn mehr als ein Fehler zurückgegeben wird.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.8.6	Hinzugefügt in: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> Standardwert: 0
• callback <Function>
  • err <Error> | <AggregateError>

Kürzt die Datei. Dem Completion-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben. Ein File Descriptor kann auch als erstes Argument übergeben werden. In diesem Fall wird fs.ftruncate() aufgerufen.

ESM

import { truncate } from 'node:fs'
// Angenommen, 'path/file.txt' ist eine reguläre Datei.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt wurde gekürzt')
})

CJS

const { truncate } = require('node:fs')
// Angenommen, 'path/file.txt' ist eine reguläre Datei.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt wurde gekürzt')
})

Das Übergeben eines File Descriptors ist veraltet und kann in Zukunft zu einem Fehler führen.

Siehe die POSIX truncate(2) Dokumentation für weitere Details.

fs.unlink(path, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v0.0.2	Hinzugefügt in: v0.0.2

• path <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

Entfernt asynchron eine Datei oder einen symbolischen Link. Dem Completion-Callback werden keine anderen Argumente als eine mögliche Ausnahme übergeben.

import { unlink } from 'node:fs'
// Angenommen, 'path/file.txt' ist eine reguläre Datei.
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt wurde gelöscht')
})

fs.unlink() funktioniert nicht bei einem Verzeichnis, egal ob leer oder nicht. Um ein Verzeichnis zu entfernen, verwenden Sie fs.rmdir().

Weitere Details finden Sie in der POSIX-Dokumentation zu unlink(2).

fs.unwatchFile(filename[, listener])

Hinzugefügt in: v0.1.31

• filename <string> | <Buffer> | <URL>
• listener <Function> Optional, ein zuvor mit fs.watchFile() hinzugefügter Listener

Stoppt die Überwachung von Änderungen an filename. Wenn listener angegeben ist, wird nur dieser bestimmte Listener entfernt. Andernfalls werden alle Listener entfernt, wodurch die Überwachung von filename effektiv beendet wird.

Das Aufrufen von fs.unwatchFile() mit einem Dateinamen, der nicht überwacht wird, ist ein No-Op, kein Fehler.

Die Verwendung von fs.watch() ist effizienter als fs.watchFile() und fs.unwatchFile(). fs.watch() sollte anstelle von fs.watchFile() und fs.unwatchFile() verwendet werden, wenn möglich.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v10.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird zur Laufzeit ein TypeError ausgelöst.
v8.0.0	NaN, Infinity und -Infinity sind keine gültigen Zeitangaben mehr.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Der Parameter callback ist nicht mehr optional. Wird er nicht übergeben, wird eine Deprecation-Warnung mit der ID DEP0013 ausgegeben.
v4.1.0	Numerische Zeichenketten, NaN und Infinity sind nun zulässige Zeitangaben.
v0.4.2	Hinzugefügt in: v0.4.2

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

Ändert die Zeitstempel des Dateisystems des Objekts, auf das path verweist.

Die Argumente atime und mtime folgen diesen Regeln:

• Werte können entweder Zahlen sein, die die Unix-Epochezeit in Sekunden darstellen, Date-Objekte oder numerische Zeichenketten wie '123456789.0'.
• Wenn der Wert nicht in eine Zahl konvertiert werden kann oder NaN, Infinity oder -Infinity ist, wird ein Error ausgelöst.

fs.watch(filename[, options][, listener])

[Historie]

Version	Änderungen
v19.1.0	Hinzugefügt: Rekursive Unterstützung für Linux, AIX und IBMi.
v15.9.0, v14.17.0	Hinzugefügt: Unterstützung zum Schließen des Watchers mit einem AbortSignal.
v7.6.0	Der Parameter filename kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v7.0.0	Das übergebene options-Objekt wird niemals modifiziert.
v0.5.10	Hinzugefügt in: v0.5.10

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> Gibt an, ob der Prozess so lange weiterlaufen soll, wie Dateien überwacht werden. Standard: true.
  • recursive <boolean> Gibt an, ob alle Unterverzeichnisse überwacht werden sollen oder nur das aktuelle Verzeichnis. Dies gilt, wenn ein Verzeichnis angegeben ist und nur auf unterstützten Plattformen (siehe Einschränkungen). Standard: false.
  • encoding <string> Gibt die Zeichenkodierung an, die für den an den Listener übergebenen Dateinamen verwendet werden soll. Standard: 'utf8'.
  • signal <AbortSignal> ermöglicht das Schließen des Watchers mit einem AbortSignal.

• listener <Function> | <undefined> Standard: undefined

  • eventType <string>
  • filename <string> | <Buffer> | <null>

• Gibt zurück: <fs.FSWatcher>

Überwacht Änderungen an filename, wobei filename entweder eine Datei oder ein Verzeichnis ist.

Das zweite Argument ist optional. Wenn options als Zeichenkette angegeben wird, gibt es die encoding an. Andernfalls sollte options als Objekt übergeben werden.

Der Listener-Callback erhält zwei Argumente (eventType, filename). eventType ist entweder 'rename' oder 'change', und filename ist der Name der Datei, die das Ereignis ausgelöst hat.

Auf den meisten Plattformen wird 'rename' immer dann ausgegeben, wenn ein Dateiname im Verzeichnis erscheint oder verschwindet.

Der Listener-Callback ist an das Ereignis 'change' angehängt, das von <fs.FSWatcher> ausgelöst wird, aber es ist nicht dasselbe wie der Wert 'change' von eventType.

Wenn ein signal übergeben wird, wird das Abbrechen des entsprechenden AbortControllers den zurückgegebenen <fs.FSWatcher> schließen.

Einschränkungen

Die fs.watch-API ist nicht zu 100 % plattformübergreifend konsistent und in einigen Situationen nicht verfügbar.

Unter Windows werden keine Ereignisse ausgegeben, wenn das überwachte Verzeichnis verschoben oder umbenannt wird. Ein EPERM-Fehler wird gemeldet, wenn das überwachte Verzeichnis gelöscht wird.

Verfügbarkeit

Diese Funktion hängt davon ab, dass das zugrunde liegende Betriebssystem eine Möglichkeit bietet, über Änderungen im Dateisystem benachrichtigt zu werden.

• Unter Linux verwendet dies inotify(7).
• Unter BSD-Systemen verwendet dies kqueue(2).
• Unter macOS verwendet dies kqueue(2) für Dateien und FSEvents für Verzeichnisse.
• Unter SunOS-Systemen (einschließlich Solaris und SmartOS) verwendet dies event ports.
• Unter Windows-Systemen hängt diese Funktion von ReadDirectoryChangesW ab.
• Unter AIX-Systemen hängt diese Funktion von AHAFS ab, das aktiviert sein muss.
• Unter IBM i-Systemen wird diese Funktion nicht unterstützt.

Wenn die zugrunde liegende Funktionalität aus irgendeinem Grund nicht verfügbar ist, kann fs.watch() nicht funktionieren und möglicherweise eine Ausnahme auslösen. Beispielsweise kann die Überwachung von Dateien oder Verzeichnissen auf Netzwerkdateisystemen (NFS, SMB usw.) oder Hostdateisystemen bei Verwendung von Virtualisierungssoftware wie Vagrant oder Docker unzuverlässig und in einigen Fällen unmöglich sein.

Es ist immer noch möglich, fs.watchFile() zu verwenden, das Stat-Polling verwendet, aber diese Methode ist langsamer und weniger zuverlässig.

Inodes

Unter Linux und macOS-Systemen löst fs.watch() den Pfad zu einem Inode auf und überwacht den Inode. Wenn der überwachte Pfad gelöscht und neu erstellt wird, wird ihm ein neuer Inode zugewiesen. Die Überwachung gibt ein Ereignis für das Löschen aus, überwacht aber weiterhin den ursprünglichen Inode. Ereignisse für den neuen Inode werden nicht ausgegeben. Dies ist das erwartete Verhalten.

AIX-Dateien behalten den gleichen Inode für die Lebensdauer einer Datei. Das Speichern und Schließen einer überwachten Datei unter AIX führt zu zwei Benachrichtigungen (eine für das Hinzufügen neuer Inhalte und eine für das Kürzen).

Dateiname-Argument

Die Angabe des Arguments filename im Callback wird nur unter Linux, macOS, Windows und AIX unterstützt. Selbst auf unterstützten Plattformen ist nicht immer garantiert, dass filename bereitgestellt wird. Gehen Sie daher nicht davon aus, dass das Argument filename immer im Callback bereitgestellt wird, und implementieren Sie eine Fallback-Logik, falls es null ist.

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`Ereignistyp ist: ${eventType}`)
  if (filename) {
    console.log(`Dateiname bereitgestellt: ${filename}`)
  } else {
    console.log('Dateiname nicht bereitgestellt')
  }
})

fs.watchFile(filename[, options], listener)

[Verlauf]

Version	Änderungen
v10.5.0	Die Option bigint wird jetzt unterstützt.
v7.6.0	Der Parameter filename kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.31	Hinzugefügt in: v0.1.31

• filename <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Standardwert: false
  • persistent <boolean> Standardwert: true
  • interval <integer> Standardwert: 5007

• listener <Function>

  • current <fs.Stats>
  • previous <fs.Stats>

• Rückgabewert: <fs.StatWatcher>

Beobachtet Änderungen an filename. Der Callback listener wird jedes Mal aufgerufen, wenn auf die Datei zugegriffen wird.

Das Argument options kann weggelassen werden. Falls angegeben, sollte es ein Objekt sein. Das options-Objekt kann einen booleschen Wert namens persistent enthalten, der angibt, ob der Prozess so lange weiterlaufen soll, wie Dateien beobachtet werden. Das options-Objekt kann eine Eigenschaft interval angeben, die festlegt, wie oft das Ziel in Millisekunden abgefragt werden soll.

Der listener erhält zwei Argumente: das aktuelle Stat-Objekt und das vorherige Stat-Objekt:

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`die aktuelle mtime ist: ${curr.mtime}`)
  console.log(`die vorherige mtime war: ${prev.mtime}`)
})

Diese Stat-Objekte sind Instanzen von fs.Stat. Wenn die Option bigint auf true gesetzt ist, werden die numerischen Werte in diesen Objekten als BigInts angegeben.

Um benachrichtigt zu werden, wenn die Datei geändert wurde, nicht nur zugegriffen wurde, ist es notwendig, curr.mtimeMs und prev.mtimeMs zu vergleichen.

Wenn eine fs.watchFile-Operation zu einem ENOENT-Fehler führt, wird der Listener einmal aufgerufen, wobei alle Felder auf Null gesetzt sind (oder bei Datumsangaben auf die Unix-Epoche). Wenn die Datei später erstellt wird, wird der Listener erneut mit den neuesten Stat-Objekten aufgerufen. Dies ist eine Änderung der Funktionalität seit v0.10.

Die Verwendung von fs.watch() ist effizienter als fs.watchFile und fs.unwatchFile. fs.watch sollte anstelle von fs.watchFile und fs.unwatchFile verwendet werden, wenn möglich.

Wenn eine von fs.watchFile() beobachtete Datei verschwindet und wieder auftaucht, ist der Inhalt von previous im zweiten Callback-Ereignis (das Wiederauftauchen der Datei) identisch mit dem Inhalt von previous im ersten Callback-Ereignis (ihr Verschwinden).

Dies geschieht, wenn:

• die Datei gelöscht und anschließend wiederhergestellt wird
• die Datei umbenannt und dann ein zweites Mal in ihren ursprünglichen Namen umbenannt wird

fs.write(fd, buffer, offset[, length[, position]], callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v14.0.0	Der buffer-Parameter konvertiert nicht mehr nicht unterstützte Eingaben in Zeichenketten.
v10.10.0	Der buffer-Parameter kann nun ein beliebiges TypedArray oder ein DataView sein.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Weglassen löst zur Laufzeit einen TypeError aus.
v7.4.0	Der buffer-Parameter kann nun ein Uint8Array sein.
v7.2.0	Die Parameter offset und length sind jetzt optional.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Weglassen löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v0.0.2	Hinzugefügt in: v0.0.2

• fd <Ganzzahl>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <Ganzzahl> Standard: 0
• length <Ganzzahl> Standard: buffer.byteLength - offset
• position <Ganzzahl> | <null> Standard: null
• callback <Funktion>
  • err <Error>
  • bytesWritten <Ganzzahl>
  • buffer <Buffer> | <TypedArray> | <DataView>

Schreibt buffer in die durch fd angegebene Datei.

offset bestimmt den zu schreibenden Teil des Puffers, und length ist eine Ganzzahl, die die Anzahl der zu schreibenden Bytes angibt.

position bezieht sich auf den Offset vom Dateianfang, an dem diese Daten geschrieben werden sollen. Wenn typeof position !== 'number', werden die Daten an der aktuellen Position geschrieben. Siehe pwrite(2).

Der Callback erhält drei Argumente (err, bytesWritten, buffer), wobei bytesWritten angibt, wie viele Bytes aus buffer geschrieben wurden.

Wenn diese Methode als ihre util.promisify()-Version aufgerufen wird, gibt sie ein Promise für ein Object mit den Eigenschaften bytesWritten und buffer zurück.

Es ist unsicher, fs.write() mehrmals auf dieselbe Datei aufzurufen, ohne auf den Callback zu warten. Für dieses Szenario wird fs.createWriteStream() empfohlen.

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhängemodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

fs.write(fd, buffer[, options], callback)

Hinzugefügt in: v18.3.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Standardwert: 0
  • length <integer> Standardwert: buffer.byteLength - offset
  • position <integer> Standardwert: null

• callback <Function>

  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

Schreibt buffer in die durch fd angegebene Datei.

Ähnlich der obigen fs.write-Funktion nimmt diese Version ein optionales options-Objekt entgegen. Wenn kein options-Objekt angegeben wird, werden die oben genannten Werte als Standard verwendet.

fs.write(fd, string[, position[, encoding]], callback)

[Verlauf]

Version	Änderungen
v19.0.0	Das Übergeben eines Objekts mit einer eigenen toString-Funktion an den string-Parameter wird nicht mehr unterstützt.
v17.8.0	Das Übergeben eines Objekts mit einer eigenen toString-Funktion an den string-Parameter ist veraltet.
v14.12.0	Der string-Parameter wandelt ein Objekt mit einer expliziten toString-Funktion in eine Zeichenkette um.
v14.0.0	Der string-Parameter konvertiert ungültige Eingaben nicht mehr in Zeichenketten.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Weglassen löst zur Laufzeit einen TypeError aus.
v7.2.0	Der position-Parameter ist jetzt optional.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Weglassen löst eine Verwarnung wegen Veralterung mit der ID DEP0013 aus.
v0.11.5	Hinzugefügt in: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> Standardwert: null
• encoding <string> Standardwert: 'utf8'
• callback <Function>
  • err <Error>
  • written <integer>
  • string <string>

Schreibt string in die durch fd angegebene Datei. Wenn string keine Zeichenkette ist, wird eine Ausnahme ausgelöst.

position bezieht sich auf den Offset vom Dateianfang, an dem diese Daten geschrieben werden sollen. Wenn typeof position !== 'number', werden die Daten an der aktuellen Position geschrieben. Siehe pwrite(2).

encoding ist die erwartete Zeichenkodierung.

Der Rückruffunktion werden die Argumente (err, written, string) übergeben, wobei written angibt, wie viele Bytes die übergebene Zeichenkette zum Schreiben benötigt hat. Geschriebene Bytes sind nicht unbedingt gleichgeschriebene Zeichen. Siehe Buffer.byteLength.

Es ist unsicher, fs.write() mehrmals auf dieselbe Datei anzuwenden, ohne auf den Rückruf zu warten. Für dieses Szenario wird fs.createWriteStream() empfohlen.

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhängemodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

Unter Windows wird eine Zeichenkette mit nicht-ASCII-Zeichen standardmäßig nicht richtig gerendert, wenn der Dateideskriptor mit der Konsole verbunden ist (z. B. fd == 1 oder stdout), unabhängig von der verwendeten Kodierung. Es ist möglich, die Konsole so zu konfigurieren, dass UTF-8 korrekt gerendert wird, indem die aktive Codepage mit dem Befehl chcp 65001 geändert wird. Weitere Informationen finden Sie in der chcp-Dokumentation.

fs.writeFile(file, data[, options], callback)

[Verlauf]

Version	Änderungen
v21.0.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v19.0.0	Das Übergeben eines Objekts mit einer eigenen toString-Funktion an den string-Parameter wird nicht mehr unterstützt.
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE statt ERR_INVALID_CALLBACK aus.
v17.8.0	Das Übergeben eines Objekts mit einer eigenen toString-Funktion an den string-Parameter ist veraltet.
v16.0.0	Der zurückgegebene Fehler kann ein AggregateError sein, wenn mehr als ein Fehler zurückgegeben wird.
v15.2.0, v14.17.0	Das options-Argument kann ein AbortSignal enthalten, um eine laufende writeFile-Anforderung abzubrechen.
v14.12.0	Der data-Parameter serialisiert ein Objekt mit einer expliziten toString-Funktion.
v14.0.0	Der data-Parameter konvertiert nicht mehr nicht unterstützte Eingaben in Strings.
v10.10.0	Der data-Parameter kann jetzt jedes TypedArray oder ein DataView sein.
v10.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst zur Laufzeit einen TypeError aus.
v7.4.0	Der data-Parameter kann jetzt ein Uint8Array sein.
v7.0.0	Der callback-Parameter ist nicht mehr optional. Das Nichtübergeben löst eine Deprecation-Warnung mit der ID DEP0013 aus.
v5.0.0	Der file-Parameter kann jetzt ein File Descriptor sein.
v0.1.29	Hinzugefügt in: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> Dateiname oder File Descriptor

• data <string> | <Buffer> | <TypedArray> | <DataView>

• options <Object> | <string>

  • encoding <string> | <null> Standard: 'utf8'
  • mode <integer> Standard: 0o666
  • flag <string> Siehe Unterstützung von Dateisystem flags. Standard: 'w'.
  • flush <boolean> Wenn alle Daten erfolgreich in die Datei geschrieben wurden und flush true ist, wird fs.fsync() verwendet, um die Daten zu leeren. Standard: false.
  • signal <AbortSignal> ermöglicht das Abbrechen eines laufenden Schreibvorgangs

• callback <Function>

  • err <Error> | <AggregateError>

Wenn file ein Dateiname ist, schreibt asynchron Daten in die Datei und ersetzt die Datei, wenn sie bereits existiert. data kann ein String oder ein Buffer sein.

Wenn file ein File Descriptor ist, ist das Verhalten ähnlich dem direkten Aufruf von fs.write() (was empfohlen wird). Siehe die Hinweise unten zur Verwendung eines File Descriptors.

Die Option encoding wird ignoriert, wenn data ein Buffer ist.

Die Option mode betrifft nur die neu erstellte Datei. Siehe fs.open() für weitere Details.

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, err => {
  if (err) throw err
  console.log('Die Datei wurde gespeichert!')
})

Wenn options ein String ist, gibt er die Kodierung an:

import { writeFile } from 'node:fs'

writeFile('message.txt', 'Hello Node.js', 'utf8', callback)

Es ist unsicher, fs.writeFile() mehrmals auf dieselbe Datei anzuwenden, ohne auf den Callback zu warten. Für dieses Szenario wird fs.createWriteStream() empfohlen.

Ähnlich wie fs.readFile - fs.writeFile ist eine Komfortmethode, die intern mehrere write-Aufrufe durchführt, um den übergebenen Buffer zu schreiben. Für performancekritischen Code sollte fs.createWriteStream() verwendet werden.

Es ist möglich, ein <AbortSignal> zu verwenden, um ein fs.writeFile() abzubrechen. Der Abbruch erfolgt nach bestem Wissen und Gewissen, und es werden wahrscheinlich noch einige Daten geschrieben.

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const controller = new AbortController()
const { signal } = controller
const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, { signal }, err => {
  // Wenn eine Anfrage abgebrochen wird, wird der Callback mit einem AbortError aufgerufen
})
// Wenn die Anfrage abgebrochen werden soll
controller.abort()

Das Abbrechen einer laufenden Anfrage bricht nicht einzelne Betriebssystemanfragen ab, sondern das interne Puffern, das fs.writeFile durchführt.

Verwendung von fs.writeFile() mit Filedeskriptoren

Wenn file ein Filedeskriptor ist, ist das Verhalten nahezu identisch mit dem direkten Aufruf von fs.write(), wie folgt:

import { write } from 'node:fs'
import { Buffer } from 'node:buffer'

write(fd, Buffer.from(data, options.encoding), callback)

Der Unterschied zum direkten Aufruf von fs.write() besteht darin, dass fs.write() unter ungewöhnlichen Bedingungen möglicherweise nur einen Teil des Puffers schreibt und wiederholt aufgerufen werden muss, um die restlichen Daten zu schreiben, während fs.writeFile() so lange wiederholt wird, bis die Daten vollständig geschrieben wurden (oder ein Fehler auftritt).

Die Auswirkungen dieser Unterschiede sind eine häufige Quelle für Verwirrung. Im Fall des Filedeskriptors wird die Datei nicht ersetzt! Die Daten werden nicht unbedingt am Anfang der Datei geschrieben, und die ursprünglichen Daten der Datei können vor und/oder nach den neu geschriebenen Daten verbleiben.

Wenn beispielsweise fs.writeFile() zweimal hintereinander aufgerufen wird, zuerst um die Zeichenkette 'Hello' zu schreiben und dann um die Zeichenkette ', World' zu schreiben, würde die Datei 'Hello, World' enthalten und möglicherweise einige der ursprünglichen Daten der Datei (abhängig von der Größe der ursprünglichen Datei und der Position des Filedeskriptors). Wäre stattdessen ein Dateiname anstelle eines Deskriptors verwendet worden, würde die Datei garantiert nur ', World' enthalten.

fs.writev(fd, buffers[, position], callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v12.9.0	Hinzugefügt in: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Standard: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

Schreibt ein Array von ArrayBufferViews in die durch fd angegebene Datei mit writev().

position ist der Offset vom Anfang der Datei, an dem diese Daten geschrieben werden sollen. Wenn typeof position !== 'number', werden die Daten an der aktuellen Position geschrieben.

Der Callback erhält drei Argumente: err, bytesWritten und buffers. bytesWritten gibt an, wie viele Bytes aus buffers geschrieben wurden.

Wenn diese Methode mit util.promisify() verwendet wird, gibt sie ein Promise für ein Object mit den Eigenschaften bytesWritten und buffers zurück.

Es ist unsicher, fs.writev() mehrmals auf dieselbe Datei anzuwenden, ohne auf den Callback zu warten. Verwenden Sie in diesem Szenario fs.createWriteStream().

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhangsmodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

Synchrone API

Die synchronen APIs führen alle Operationen synchron aus und blockieren die Ereignisschleife, bis die Operation abgeschlossen oder fehlgeschlagen ist.

fs.accessSync(path[, mode])

[Verlauf]

Version	Änderungen
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.11.15	Hinzugefügt in: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> Standard: fs.constants.F_OK

Testet synchron die Berechtigungen eines Benutzers für die Datei oder das Verzeichnis, die durch path angegeben ist. Das Argument mode ist eine optionale Ganzzahl, die die durchzuführenden Zugriffsprüfungen angibt. mode sollte entweder der Wert fs.constants.F_OK oder eine Maske sein, die aus dem bitweisen ODER von fs.constants.R_OK, fs.constants.W_OK und fs.constants.X_OK besteht (z. B. fs.constants.W_OK | fs.constants.R_OK). Überprüfen Sie Dateizugriffskonstanten für mögliche Werte von mode.

Wenn eine der Zugriffsprüfungen fehlschlägt, wird ein Error ausgelöst. Andernfalls gibt die Methode undefined zurück.

import { accessSync, constants } from 'node:fs'

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('Lese-/Schreibzugriff möglich')
} catch (err) {
  console.error('Kein Zugriff!')
}

fs.appendFileSync(path, data[, options])

[Verlauf]

Version	Änderungen
v21.1.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v7.0.0	Das übergebene options-Objekt wird niemals verändert.
v5.0.0	Der Parameter file kann jetzt ein File Descriptor sein.
v0.6.7	Hinzugefügt in: v0.6.7

• path <string> | <Buffer> | <URL> | <number> Dateiname oder File Descriptor
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> Standard: 'utf8'
  • mode <integer> Standard: 0o666
  • flag <string> Siehe Unterstützung von Dateisystem-Flags. Standard: 'a'.
  • flush <boolean> Wenn true, wird der zugrunde liegende File Descriptor vor dem Schließen geleert. Standard: false.

Fügt synchron Daten an eine Datei an und erstellt die Datei, wenn sie noch nicht existiert. data kann eine Zeichenkette oder ein <Buffer> sein.

Die Option mode wirkt sich nur auf die neu erstellte Datei aus. Weitere Informationen finden Sie unter fs.open().

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'anzuhängende Daten')
  console.log('Die "anzuhängende Daten" wurden an die Datei angehängt!')
} catch (err) {
  /* Fehlerbehandlung */
}

Wenn options eine Zeichenkette ist, gibt diese die Kodierung an:

import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'anzuhängende Daten', 'utf8')

Der path kann als numerischer File Descriptor angegeben werden, der zum Anhängen geöffnet wurde (mit fs.open() oder fs.openSync()). Der File Descriptor wird nicht automatisch geschlossen.

import { openSync, closeSync, appendFileSync } from 'node:fs'

let fd

try {
  fd = openSync('message.txt', 'a')
  appendFileSync(fd, 'anzuhängende Daten', 'utf8')
} catch (err) {
  /* Fehlerbehandlung */
} finally {
  if (fd !== undefined) closeSync(fd)
}

fs.chmodSync(path, mode)

[Verlauf]

Version	Änderungen
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.6.7	Hinzugefügt in: v0.6.7

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.chmod().

Weitere Details finden Sie in der POSIX chmod(2) Dokumentation.

fs.chownSync(path, uid, gid)

[Verlauf]

Version	Änderungen
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.97	Hinzugefügt in: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

Ändert synchron den Besitzer und die Gruppe einer Datei. Gibt undefined zurück. Dies ist die synchrone Version von fs.chown().

Weitere Details finden Sie in der POSIX chown(2) Dokumentation.

fs.closeSync(fd)

Hinzugefügt in: v0.1.21

• fd <integer>

Schließt den Datei-Descriptor. Gibt undefined zurück.

Das Aufrufen von fs.closeSync() auf einen beliebigen Datei-Descriptor (fd), der derzeit über eine andere fs-Operation verwendet wird, kann zu undefiniertem Verhalten führen.

Weitere Details finden Sie in der POSIX close(2) Dokumentation.

fs.copyFileSync(src, dest[, mode])

[Verlauf]

Version	Änderungen
v14.0.0	Argument flags wurde in mode geändert und eine strengere Typvalidierung eingeführt.
v8.5.0	Hinzugefügt in: v8.5.0

• src <string> | <Buffer> | <URL> Quelldateiname zum Kopieren
• dest <string> | <Buffer> | <URL> Zieldateiname des Kopiervorgangs
• mode <integer> Modifikatoren für den Kopiervorgang. Standard: 0.

Kopiert src synchron nach dest. Standardmäßig wird dest überschrieben, falls es bereits existiert. Gibt undefined zurück. Node.js gibt keine Garantie für die Atomizität des Kopiervorgangs. Falls ein Fehler auftritt, nachdem die Zieldatei zum Schreiben geöffnet wurde, versucht Node.js, die Zieldatei zu entfernen.

mode ist eine optionale Ganzzahl, die das Verhalten des Kopiervorgangs angibt. Es ist möglich, eine Maske zu erstellen, die aus dem bitweisen ODER von zwei oder mehr Werten besteht (z. B. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: Der Kopiervorgang schlägt fehl, wenn dest bereits existiert.
• fs.constants.COPYFILE_FICLONE: Der Kopiervorgang versucht, einen Copy-on-Write-Reflink zu erstellen. Wenn die Plattform Copy-on-Write nicht unterstützt, wird ein Fallback-Kopiermechanismus verwendet.
• fs.constants.COPYFILE_FICLONE_FORCE: Der Kopiervorgang versucht, einen Copy-on-Write-Reflink zu erstellen. Wenn die Plattform Copy-on-Write nicht unterstützt, schlägt der Vorgang fehl.

import { copyFileSync, constants } from 'node:fs'

// destination.txt wird standardmäßig erstellt oder überschrieben.
copyFileSync('source.txt', 'destination.txt')
console.log('source.txt wurde nach destination.txt kopiert')

// Mit COPYFILE_EXCL schlägt der Vorgang fehl, wenn destination.txt existiert.
copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL)

fs.cpSync(src, dest[, options])

[Verlauf]

Version	Änderungen
v22.3.0	Diese API ist nicht mehr experimentell.
v20.1.0, v18.17.0	Akzeptiert eine zusätzliche mode-Option, um das Kopierverhalten als mode-Argument von fs.copyFile() anzugeben.
v17.6.0, v16.15.0	Akzeptiert eine zusätzliche verbatimSymlinks-Option, um anzugeben, ob die Pfadauflösung für symbolische Links durchgeführt werden soll.
v16.7.0	Hinzugefügt in: v16.7.0

• src <string> | <URL> Quellpfad zum Kopieren.

• dest <string> | <URL> Zielpfad zum Kopieren.

• options <Object>

  • dereference <boolean> Symbolische Links auflösen. Standard: false.

  • errorOnExist <boolean> Wenn force false ist und das Ziel existiert, wird ein Fehler ausgegeben. Standard: false.

  • filter <Function> Funktion zum Filtern kopierter Dateien/Verzeichnisse. Gibt true zurück, um das Element zu kopieren, false, um es zu ignorieren. Beim Ignorieren eines Verzeichnisses werden auch alle seine Inhalte übersprungen. Standard: undefined

  • src <string> Quellpfad zum Kopieren.

  • dest <string> Zielpfad zum Kopieren.

  • Rückgabewert: <boolean> Jeder Nicht-Promise-Wert, der in boolean umgewandelt werden kann.

  • force <boolean> Bestehende Datei oder Verzeichnis überschreiben. Der Kopiervorgang ignoriert Fehler, wenn Sie dies auf false setzen und das Ziel existiert. Verwenden Sie die Option errorOnExist, um dieses Verhalten zu ändern. Standard: true.

  • mode <integer> Modifikatoren für den Kopiervorgang. Standard: 0. Siehe mode-Flag von fs.copyFileSync().

  • preserveTimestamps <boolean> Wenn true, werden Zeitstempel von src beibehalten. Standard: false.

  • recursive <boolean> Verzeichnisse rekursiv kopieren. Standard: false

  • verbatimSymlinks <boolean> Wenn true, wird die Pfadauflösung für symbolische Links übersprungen. Standard: false

Kopiert die gesamte Verzeichnisstruktur synchron von src nach dest, einschließlich Unterverzeichnisse und Dateien.

Beim Kopieren eines Verzeichnisses in ein anderes Verzeichnis werden keine Globs unterstützt, und das Verhalten ähnelt cp dir1/ dir2/.

fs.existsSync(path)

[Historie]

Version	Änderungen
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.21	Hinzugefügt in: v0.1.21

• path <string> | <Buffer> | <URL>
• Rückgabewert: <boolean>

Gibt true zurück, wenn der Pfad existiert, andernfalls false.

Für detaillierte Informationen siehe die Dokumentation der asynchronen Version dieser API: fs.exists().

fs.exists() ist veraltet, fs.existsSync() jedoch nicht. Der Parameter callback von fs.exists() akzeptiert Parameter, die mit anderen Node.js-Callbacks inkonsistent sind. fs.existsSync() verwendet keinen Callback.

import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('Der Pfad existiert.')

fs.fchmodSync(fd, mode)

Hinzugefügt in: v0.4.7

• fd <integer>
• mode <string> | <integer>

Setzt die Berechtigungen der Datei. Gibt undefined zurück.

Siehe die POSIX fchmod(2) Dokumentation für weitere Details.

fs.fchownSync(fd, uid, gid)

Hinzugefügt in: v0.4.7

• fd <integer>
• uid <integer> Die Benutzer-ID des neuen Besitzers der Datei.
• gid <integer> Die Gruppen-ID der neuen Gruppe der Datei.

Setzt den Besitzer der Datei. Gibt undefined zurück.

Siehe die POSIX fchown(2) Dokumentation für weitere Details.

fs.fdatasyncSync(fd)

Hinzugefügt in: v0.1.96

• fd <integer>

Zwingt alle aktuell gepufferten E/A-Operationen, die mit der Datei verbunden sind, in den synchronisierten E/A-Abschlusszustand des Betriebssystems. Einzelheiten finden Sie in der POSIX fdatasync(2) Dokumentation. Gibt undefined zurück.

fs.fstatSync(fd[, options])

[Verlauf]

Version	Änderungen
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte bigint sein sollen.
v0.1.95	Hinzugefügt in: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats> Objekt bigint sein sollen. Standard: false.

• Rückgabewert: <fs.Stats>

Ruft die <fs.Stats> für den Datei-Deskriptor ab.

Siehe die POSIX fstat(2) Dokumentation für weitere Details.

fs.fsyncSync(fd)

Hinzugefügt in: v0.1.96

• fd <integer>

Fordert an, dass alle Daten für den geöffneten Datei-Deskriptor auf das Speichergerät geschrieben werden. Die spezifische Implementierung ist betriebssystem- und gerätespezifisch. Weitere Einzelheiten finden Sie in der POSIX fsync(2) Dokumentation. Gibt undefined zurück.

fs.ftruncateSync(fd[, len])

Hinzugefügt in: v0.8.6

• fd <integer>
• len <integer> Standard: 0

Stutzt den Datei-Deskriptor. Gibt undefined zurück.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[Versionsgeschichte]

Version	Änderungen
v4.1.0	Numerische Zeichenketten, NaN und Infinity sind jetzt zulässige Zeitangaben.
v0.4.2	Hinzugefügt in: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Synchrone Version von fs.futimes(). Gibt undefined zurück.

fs.globSync(pattern[, options])

[Versionsgeschichte]

Version	Änderungen
v22.2.0	Unterstützung für withFileTypes als Option hinzugefügt.
v22.0.0	Hinzugefügt in: v22.0.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> aktuelles Arbeitsverzeichnis. Standard: process.cwd()
  • exclude <Function> Funktion zum Herausfiltern von Dateien/Verzeichnissen. Gibt true zurück, um das Element auszuschließen, false, um es einzuschließen. Standard: undefined.
  • withFileTypes <boolean> true, wenn der Glob Pfade als Dirents zurückgeben soll, andernfalls false. Standard: false.

• Rückgabewert: <string[]> Pfade der Dateien, die dem Muster entsprechen.

ESM

import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))

CJS

const { globSync } = require('node:fs')

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

Seit v0.4.7 veraltet

• path <string> | <Buffer> | <URL>
• mode <integer>

Ändert die Berechtigungen eines symbolischen Links. Gibt undefined zurück.

Diese Methode ist nur unter macOS implementiert.

Siehe die POSIX lchmod(2) Dokumentation für weitere Details.

fs.lchownSync(path, uid, gid)

[Verlauf]

Version	Änderungen
v10.6.0	Diese API ist nicht mehr veraltet.
v0.4.7	Nur Dokumentations-Veralterung.

• path <string> | <Buffer> | <URL>
• uid <integer> Die Benutzer-ID des neuen Besitzers der Datei.
• gid <integer> Die Gruppen-ID der neuen Gruppe der Datei.

Setzt den Besitzer für den Pfad. Gibt undefined zurück.

Siehe die POSIX lchown(2) Dokumentation für weitere Details.

fs.lutimesSync(path, atime, mtime)

Hinzugefügt in: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Ändert die Zeitstempel des Dateisystems des symbolischen Links, auf den path verweist. Gibt undefined zurück oder löst eine Ausnahme aus, wenn Parameter falsch sind oder der Vorgang fehlschlägt. Dies ist die synchrone Version von fs.lutimes().

fs.linkSync(existingPath, newPath)

[Verlauf]

Version	Änderungen
v7.6.0	Die Parameter existingPath und newPath können WHATWG URL-Objekte mit dem Protokoll file: sein. Die Unterstützung ist derzeit noch experimentell.
v0.1.31	Hinzugefügt in: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Erstellt einen neuen Link von existingPath zu newPath. Siehe die POSIX link(2) Dokumentation für weitere Details. Gibt undefined zurück.

fs.lstatSync(path[, options])

[Verlauf]

Version	Änderungen
v15.3.0, v14.17.0	Akzeptiert eine throwIfNoEntry-Option, um anzugeben, ob eine Ausnahme ausgelöst werden soll, wenn der Eintrag nicht existiert.
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte bigint sein sollen.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.30	Hinzugefügt in: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats>-Objekt bigint sein sollen. Standard: false.
  • throwIfNoEntry <boolean> Ob eine Ausnahme ausgelöst wird, wenn kein Dateisystemeintrag existiert, anstatt undefined zurückzugeben. Standard: true.

• Rückgabewert: <fs.Stats>

Ruft die <fs.Stats> für den symbolischen Link ab, auf den sich path bezieht.

Siehe die POSIX lstat(2) Dokumentation für weitere Details.

fs.mkdirSync(pfad[, optionen])

[Verlauf]

Version	Änderungen
v13.11.0, v12.17.0	Im recursive-Modus wird jetzt der zuerst erstellte Pfad zurückgegeben.
v10.12.0	Das zweite Argument kann jetzt ein optionen-Objekt mit den Eigenschaften recursive und mode sein.
v7.6.0	Der pfad-Parameter kann ein WHATWG URL-Objekt mit dem file:-Protokoll sein.
v0.1.21	Hinzugefügt in: v0.1.21

• pfad <string> | <Buffer> | <URL>

• optionen <Object> | <integer>

  • recursive <boolean> Standard: false
  • mode <string> | <integer> Nicht unter Windows unterstützt. Standard: 0o777.

• Gibt zurück: <string> | <undefined>

Erstellt synchron ein Verzeichnis. Gibt undefined zurück, oder, wenn recursive true ist, den zuerst erstellten Verzeichnispfad. Dies ist die synchrone Version von fs.mkdir().

Siehe die POSIX mkdir(2) Dokumentation für weitere Details.

fs.mkdtempSync(präfix[, optionen])

[Verlauf]

Version	Änderungen
v20.6.0, v18.19.0	Der präfix-Parameter akzeptiert jetzt Buffer und URLs.
v16.5.0, v14.18.0	Der präfix-Parameter akzeptiert jetzt einen leeren String.
v5.10.0	Hinzugefügt in: v5.10.0

• präfix <string> | <Buffer> | <URL>

• optionen <string> | <Object>

  • encoding <string> Standard: 'utf8'

• Gibt zurück: <string>

Gibt den Pfad des erstellten Verzeichnisses zurück.

Für detaillierte Informationen siehe die Dokumentation der asynchronen Version dieser API: fs.mkdtemp().

Das optionale optionen-Argument kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung angibt.

fs.opendirSync(path[, options])

[History]

Version	Änderungen
v20.1.0, v18.17.0	Option recursive hinzugefügt.
v13.1.0, v12.16.0	Die Option bufferSize wurde eingeführt.
v12.12.0	Hinzugefügt in: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> Standard: 'utf8'
  • bufferSize <number> Anzahl der Verzeichniseinträge, die intern beim Lesen aus dem Verzeichnis gepuffert werden. Höhere Werte führen zu besserer Leistung, aber höherem Speicherverbrauch. Standard: 32
  • recursive <boolean> Standard: false

• Rückgabewert: <fs.Dir>

Öffnet ein Verzeichnis synchron. Siehe opendir(3).

Erstellt ein <fs.Dir>, das alle weiteren Funktionen zum Lesen aus und Bereinigen des Verzeichnisses enthält.

Die Option encoding legt die Codierung für den path beim Öffnen des Verzeichnisses und bei nachfolgenden Leseoperationen fest.

fs.openSync(path[, flags[, mode]])

[History]

Version	Änderungen
v11.1.0	Das Argument flags ist jetzt optional und standardmäßig 'r'.
v9.9.0	Die Flags as und as+ werden jetzt unterstützt.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.21	Hinzugefügt in: v0.1.21

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Standard: 'r'. Siehe Unterstützung von Dateisystem-flags.
• mode <string> | <integer> Standard: 0o666
• Rückgabewert: <number>

Gibt eine ganze Zahl zurück, die den Dateideskriptor darstellt.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.open().

fs.readdirSync(path[, options])

[Verlauf]

Version	Änderungen
v20.1.0, v18.17.0	Option recursive hinzugefügt.
v10.10.0	Neue Option withFileTypes hinzugefügt.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem file:-Protokoll sein.
v0.1.21	Hinzugefügt in: v0.1.21

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'
  • withFileTypes <boolean> Standard: false
  • recursive <boolean> Wenn true, liest den Inhalt eines Verzeichnisses rekursiv. Im rekursiven Modus werden alle Dateien, Unterdateien und Verzeichnisse aufgelistet. Standard: false.

• Rückgabewert: <string[]> | <Buffer[]> | <fs.Dirent[]>

Liest den Inhalt des Verzeichnisses.

Siehe die POSIX readdir(3) Dokumentation für weitere Details.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer encoding-Eigenschaft, die die zu verwendende Zeichencodierung für die zurückgegebenen Dateinamen angibt. Wenn encoding auf 'buffer' gesetzt ist, werden die zurückgegebenen Dateinamen als <Buffer> Objekte übergeben.

Wenn options.withFileTypes auf true gesetzt ist, enthält das Ergebnis <fs.Dirent> Objekte.

fs.readFileSync(path[, options])

[Versionsgeschichte]

Version	Änderungen
v7.6.0	Der Parameter path kann nun ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v5.0.0	Der Parameter path kann nun ein Dateideskriptor sein.
v0.1.8	Hinzugefügt in: v0.1.8

• path <string> | <Buffer> | <URL> | <integer> Dateiname oder Dateideskriptor

• options <Object> | <string>

  • encoding <string> | <null> Standardwert: null
  • flag <string> Siehe Unterstützung von Dateisystem-Flags. Standardwert: 'r'.

• Rückgabewert: <string> | <Buffer>

Gibt den Inhalt von path zurück.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.readFile().

Wenn die Option encoding angegeben ist, gibt diese Funktion eine Zeichenkette zurück. Andernfalls wird ein Puffer zurückgegeben.

Ähnlich wie bei fs.readFile() ist das Verhalten von fs.readFileSync(), wenn der Pfad ein Verzeichnis ist, plattformabhängig.

import { readFileSync } from 'node:fs'

// macOS, Linux und Windows
readFileSync('<directory>')
// => [Error: EISDIR: ungültige Operation auf einem Verzeichnis, lesen <directory>]

// FreeBSD
readFileSync('<directory>') // => <data>

fs.readlinkSync(path[, options])

[History]

Version	Änderungen
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.31	Hinzugefügt in: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• Rückgabewert: <string> | <Buffer>

Gibt den Zeichenkettenwert des symbolischen Links zurück.

Weitere Details finden Sie in der POSIX-Dokumentation zu readlink(2).

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer Eigenschaft encoding, die die zu verwendende Zeichencodierung für den zurückgegebenen Linkpfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Linkpfad als <Buffer>-Objekt übergeben.

fs.readSync(fd, buffer, offset, length[, position])

[History]

Version	Änderungen
v10.10.0	Der Parameter buffer kann jetzt ein beliebiges TypedArray oder ein DataView sein.
v6.0.0	Der Parameter length kann jetzt 0 sein.
v0.1.21	Hinzugefügt in: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer> | <bigint> | <null> Standard: null
• Rückgabewert: <number>

Gibt die Anzahl der bytesRead zurück.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.read().

fs.readSync(fd, buffer[, options])

[Verlauf]

Version	Änderungen
v13.13.0, v12.17.0	Es kann ein Options-Objekt übergeben werden, um offset, length und position optional zu machen.
v13.13.0, v12.17.0	Hinzugefügt in: v13.13.0, v12.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Standardwert: 0
  • length <integer> Standardwert: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Standardwert: null

• Rückgabewert: <number>

Gibt die Anzahl der bytesRead zurück.

Ähnlich der obigen fs.readSync-Funktion nimmt diese Version ein optionales options-Objekt entgegen. Wenn kein options-Objekt angegeben wird, werden die oben genannten Werte als Standard verwendet.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.read().

fs.readvSync(fd, buffers[, position])

Hinzugefügt in: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Standardwert: null
• Rückgabewert: <number> Die Anzahl der gelesenen Bytes.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.readv().

fs.realpathSync(path[, options])

[Versionsgeschichte]

Version	Änderungen
v8.0.0	Unterstützung für Pipe/Socket-Auflösung hinzugefügt.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v6.4.0	realpathSync funktioniert jetzt wieder in verschiedenen Randfällen unter Windows.
v6.0.0	Der Parameter cache wurde entfernt.
v0.1.31	Hinzugefügt in: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• Rückgabewert: <string> | <Buffer>

Gibt den aufgelösten Pfadnamen zurück.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.realpath().

fs.realpathSync.native(path[, options])

Hinzugefügt in: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Standard: 'utf8'

• Rückgabewert: <string> | <Buffer>

Synchrones realpath(3).

Es werden nur Pfade unterstützt, die in UTF8-Strings konvertiert werden können.

Das optionale Argument options kann eine Zeichenkette sein, die eine Codierung angibt, oder ein Objekt mit einer Eigenschaft encoding, die die zu verwendende Zeichencodierung für den zurückgegebenen Pfad angibt. Wenn encoding auf 'buffer' gesetzt ist, wird der zurückgegebene Pfad als <Buffer>-Objekt übergeben.

Unter Linux muss, wenn Node.js mit musl libc verknüpft ist, das procfs-Dateisystem unter /proc eingehängt sein, damit diese Funktion funktioniert. Glibc hat diese Einschränkung nicht.

fs.renameSync(oldPath, newPath)

[Verlauf]

Version	Änderungen
v7.6.0	Die Parameter oldPath und newPath können WHATWG URL-Objekte mit dem Protokoll file: sein. Die Unterstützung ist derzeit noch experimentell.
v0.1.21	Hinzugefügt in: v0.1.21

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Benennt die Datei von oldPath in newPath um. Gibt undefined zurück.

Siehe die POSIX rename(2) Dokumentation für weitere Details.

fs.rmdirSync(path[, options])

[Verlauf]

Version	Änderungen
v16.0.0	Die Verwendung von fs.rmdirSync(path, { recursive: true }) für einen path, der eine Datei ist, ist nicht mehr zulässig und führt unter Windows zu einem ENOENT-Fehler und unter POSIX zu einem ENOTDIR-Fehler.
v16.0.0	Die Verwendung von fs.rmdirSync(path, { recursive: true }) für einen path, der nicht existiert, ist nicht mehr zulässig und führt zu einem ENOENT-Fehler.
v16.0.0	Die Option recursive ist veraltet; ihre Verwendung löst eine Veraltungswarnung aus.
v14.14.0	Die Option recursive ist veraltet; verwenden Sie stattdessen fs.rmSync.
v13.3.0, v12.16.0	Die Option maxBusyTries wurde in maxRetries umbenannt, und ihr Standardwert ist 0. Die Option emfileWait wurde entfernt, und EMFILE-Fehler verwenden dieselbe Wiederholungslogik wie andere Fehler. Die Option retryDelay wird jetzt unterstützt. ENFILE-Fehler werden jetzt wiederholt.
v12.10.0	Die Optionen recursive, maxBusyTries und emfileWait werden jetzt unterstützt.
v7.6.0	Der path-Parameter kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.21	Hinzugefügt in: v0.1.21

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Wenn ein EBUSY, EMFILE, ENFILE, ENOTEMPTY oder EPERM Fehler auftritt, wiederholt Node.js den Vorgang mit einer linearen Backoff-Wartezeit von retryDelay Millisekunden länger bei jedem Versuch. Diese Option gibt die Anzahl der Wiederholungsversuche an. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 0.
  • recursive <boolean> Wenn true, wird eine rekursive Verzeichnisentfernung durchgeführt. Im rekursiven Modus werden Operationen bei Fehlern wiederholt. Standard: false. Veraltet.
  • retryDelay <integer> Die Wartezeit in Millisekunden zwischen Wiederholungsversuchen. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 100.

Synchrone rmdir(2). Gibt undefined zurück.

Die Verwendung von fs.rmdirSync() auf einer Datei (kein Verzeichnis) führt unter Windows zu einem ENOENT-Fehler und unter POSIX zu einem ENOTDIR-Fehler.

Um ein ähnliches Verhalten wie der Unix-Befehl rm -rf zu erhalten, verwenden Sie fs.rmSync() mit den Optionen { recursive: true, force: true }.

fs.rmSync(path[, options])

[Verlauf]

Version	Änderungen
v17.3.0, v16.14.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v14.14.0	Hinzugefügt in: v14.14.0

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> Wenn true, werden Ausnahmen ignoriert, wenn path nicht existiert. Standard: false.
  • maxRetries <integer> Wenn ein EBUSY, EMFILE, ENFILE, ENOTEMPTY oder EPERM Fehler auftritt, wiederholt Node.js den Vorgang mit einer linearen Backoff-Wartezeit von retryDelay Millisekunden länger bei jedem Versuch. Diese Option gibt die Anzahl der Wiederholungsversuche an. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 0.
  • recursive <boolean> Wenn true, wird eine rekursive Verzeichnisentfernung durchgeführt. Im rekursiven Modus werden Operationen bei Fehlern wiederholt. Standard: false.
  • retryDelay <integer> Die Wartezeit in Millisekunden zwischen Wiederholungsversuchen. Diese Option wird ignoriert, wenn die Option recursive nicht true ist. Standard: 100.

Synchron entfernt Dateien und Verzeichnisse (modelliert nach dem Standard-POSIX rm-Dienstprogramm). Gibt undefined zurück.

fs.statSync(path[, options])

[Verlauf]

Version	Änderungen
v15.3.0, v14.17.0	Akzeptiert eine throwIfNoEntry-Option, um anzugeben, ob eine Ausnahme ausgelöst werden soll, wenn der Eintrag nicht existiert.
v10.5.0	Akzeptiert ein zusätzliches options-Objekt, um anzugeben, ob die zurückgegebenen numerischen Werte bigint sein sollen.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.21	Hinzugefügt in: v0.1.21

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.Stats>-Objekt bigint sein sollen. Standard: false.
  • throwIfNoEntry <boolean> Ob eine Ausnahme ausgelöst wird, wenn kein Dateisystemeintrag existiert, anstatt undefined zurückzugeben. Standard: true.

• Rückgabewert: <fs.Stats>

Ruft die <fs.Stats> für den Pfad ab.

fs.statfsSync(path[, options])

Hinzugefügt in: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Ob die numerischen Werte im zurückgegebenen <fs.StatFs>-Objekt bigint sein sollen. Standard: false.

• Rückgabewert: <fs.StatFs>

Synchrone statfs(2). Gibt Informationen über das gemountete Dateisystem zurück, das path enthält.

Im Fehlerfall ist err.code einer der Common System Errors.

fs.symlinkSync(target, path[, type])

[Verlauf]

Version	Änderungen
v12.0.0	Wenn das Argument type undefiniert bleibt, erkennt Node den target-Typ automatisch und wählt automatisch dir oder file.
v7.6.0	Die Parameter target und path können WHATWG URL-Objekte mit dem Protokoll file: sein. Die Unterstützung ist derzeit noch experimentell.
v0.1.31	Hinzugefügt in: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Standard: null

Gibt undefined zurück.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.symlink().

fs.truncateSync(path[, len])

Hinzugefügt in: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> Standard: 0

Kürzt die Datei. Gibt undefined zurück. Ein File Descriptor kann auch als erstes Argument übergeben werden. In diesem Fall wird fs.ftruncateSync() aufgerufen.

Die Übergabe eines File Descriptors ist veraltet und kann in Zukunft zu einem Fehler führen.

fs.unlinkSync(path)

[Verlauf]

Version	Änderungen
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v0.1.21	Hinzugefügt in: v0.1.21

• path <string> | <Buffer> | <URL>

Synchrones unlink(2). Gibt undefined zurück.

fs.utimesSync(path, atime, mtime)

[Verlauf]

Version	Änderungen
v8.0.0	NaN, Infinity und -Infinity sind keine gültigen Zeitangaben mehr.
v7.6.0	Der Parameter path kann ein WHATWG URL-Objekt mit dem Protokoll file: sein.
v4.1.0	Numerische Zeichenketten, NaN und Infinity sind jetzt zulässige Zeitangaben.
v0.4.2	Hinzugefügt in: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Gibt undefined zurück.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.utimes().

fs.writeFileSync(file, data[, options])

[Verlauf]

Version	Änderungen
v21.0.0, v20.10.0	Die Option flush wird jetzt unterstützt.
v19.0.0	Das Übergeben eines Objekts mit einer eigenen toString-Funktion an den Parameter data wird nicht mehr unterstützt.
v17.8.0	Das Übergeben eines Objekts mit einer eigenen toString-Funktion an den Parameter data ist veraltet.
v14.12.0	Der Parameter data serialisiert ein Objekt mit einer expliziten toString-Funktion.
v14.0.0	Der Parameter data konvertiert ungültige Eingaben nicht mehr in Strings.
v10.10.0	Der Parameter data kann nun ein beliebiger TypedArray oder ein DataView sein.
v7.4.0	Der Parameter data kann nun ein Uint8Array sein.
v5.0.0	Der Parameter file kann nun ein File Descriptor sein.
v0.1.29	Hinzugefügt in: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> Dateiname oder File Descriptor
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> Standard: 'utf8'
  • mode <integer> Standard: 0o666
  • flag <string> Siehe Unterstützung von Dateisystem-Flags. Standard: 'w'.
  • flush <boolean> Wenn alle Daten erfolgreich in die Datei geschrieben wurden und flush true ist, wird fs.fsyncSync() verwendet, um die Daten zu leeren.

Gibt undefined zurück.

Die Option mode wirkt sich nur auf die neu erstellte Datei aus. Weitere Details finden Sie unter fs.open().

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.writeFile().

fs.writeSync(fd, buffer, offset[, length[, position]])

[Verlauf]

Version	Änderungen
v14.0.0	Der Parameter buffer konvertiert nicht mehr nicht unterstützte Eingaben in Zeichenketten.
v10.10.0	Der Parameter buffer kann nun ein beliebiges TypedArray oder ein DataView sein.
v7.4.0	Der Parameter buffer kann nun ein Uint8Array sein.
v7.2.0	Die Parameter offset und length sind nun optional.
v0.1.21	Hinzugefügt in: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Standard: 0
• length <integer> Standard: buffer.byteLength - offset
• position <integer> | <null> Standard: null
• Rückgabewert: <number> Die Anzahl der geschriebenen Bytes.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

Hinzugefügt in: v18.3.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Standard: 0
  • length <integer> Standard: buffer.byteLength - offset
  • position <integer> Standard: null

• Rückgabewert: <number> Die Anzahl der geschriebenen Bytes.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

[Versionsverlauf]

Version	Änderungen
v14.0.0	Der Parameter string konvertiert nicht mehr nicht unterstützte Eingaben in Strings.
v7.2.0	Der Parameter position ist jetzt optional.
v0.11.5	Hinzugefügt in: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> Standard: null
• encoding <string> Standard: 'utf8'
• Rückgabewert: <number> Die Anzahl der geschriebenen Bytes.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.write(fd, string...).

fs.writevSync(fd, buffers[, position])

Hinzugefügt in: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Standard: null
• Rückgabewert: <number> Die Anzahl der geschriebenen Bytes.

Ausführliche Informationen finden Sie in der Dokumentation der asynchronen Version dieser API: fs.writev().

Gemeinsame Objekte

Die gemeinsamen Objekte werden von allen Varianten der Dateisystem-API (Promise, Callback und synchron) gemeinsam genutzt.

Klasse: fs.Dir

Hinzugefügt in: v12.12.0

Eine Klasse, die einen Verzeichnisstrom darstellt.

Erstellt von fs.opendir(), fs.opendirSync() oder fsPromises.opendir().

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)
}

Bei Verwendung des asynchronen Iterators wird das <fs.Dir>-Objekt automatisch geschlossen, nachdem der Iterator beendet wurde.

dir.close()

Hinzugefügt in: v12.12.0

• Rückgabewert: <Promise>

Schließt asynchron den zugrundeliegenden Ressourcen-Handle des Verzeichnisses. Nachfolgende Lesevorgänge führen zu Fehlern.

Es wird ein Promise zurückgegeben, das erfüllt wird, nachdem die Ressource geschlossen wurde.

dir.close(callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v12.12.0	Hinzugefügt in: v12.12.0

• callback <Function>
  • err <Error>

Schließt asynchron den zugrundeliegenden Ressourcen-Handle des Verzeichnisses. Nachfolgende Lesevorgänge führen zu Fehlern.

Der callback wird aufgerufen, nachdem der Ressourcen-Handle geschlossen wurde.

dir.closeSync()

Hinzugefügt in: v12.12.0

Schließt synchron den zugrundeliegenden Ressourcen-Handle des Verzeichnisses. Nachfolgende Lesevorgänge führen zu Fehlern.

dir.path

Hinzugefügt in: v12.12.0

• <string>

Der schreibgeschützte Pfad dieses Verzeichnisses, wie er an fs.opendir(), fs.opendirSync() oder fsPromises.opendir() übergeben wurde.

dir.read()

Hinzugefügt in: v12.12.0

• Rückgabewert: <Promise> Löst mit einem <fs.Dirent> | <null> auf

Liest asynchron den nächsten Verzeichniseintrag über readdir(3) als <fs.Dirent>.

Ein Promise wird zurückgegeben, das mit einem <fs.Dirent> erfüllt wird, oder mit null, wenn keine weiteren Verzeichniseinträge zum Lesen vorhanden sind.

Verzeichniseinträge, die von dieser Funktion zurückgegeben werden, sind in keiner bestimmten Reihenfolge, wie sie von den zugrunde liegenden Verzeichnismechanismen des Betriebssystems bereitgestellt werden. Einträge, die während der Iteration über das Verzeichnis hinzugefügt oder entfernt werden, sind möglicherweise nicht in den Iterationsergebnissen enthalten.

dir.read(callback)

Hinzugefügt in: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

Liest asynchron den nächsten Verzeichniseintrag über readdir(3) als <fs.Dirent>.

Nach Abschluss des Lesevorgangs wird der callback mit einem <fs.Dirent> oder null aufgerufen, wenn keine weiteren Verzeichniseinträge zum Lesen vorhanden sind.

Verzeichniseinträge, die von dieser Funktion zurückgegeben werden, sind in keiner bestimmten Reihenfolge, wie sie von den zugrunde liegenden Verzeichnismechanismen des Betriebssystems bereitgestellt werden. Einträge, die während der Iteration über das Verzeichnis hinzugefügt oder entfernt werden, sind möglicherweise nicht in den Iterationsergebnissen enthalten.

dir.readSync()

Hinzugefügt in: v12.12.0

• Rückgabewert: <fs.Dirent> | <null>

Liest synchron den nächsten Verzeichniseintrag als <fs.Dirent>. Weitere Informationen finden Sie in der POSIX readdir(3) Dokumentation.

Wenn keine weiteren Verzeichniseinträge zum Lesen vorhanden sind, wird null zurückgegeben.

Verzeichniseinträge, die von dieser Funktion zurückgegeben werden, sind in keiner bestimmten Reihenfolge, wie sie von den zugrunde liegenden Verzeichnismechanismen des Betriebssystems bereitgestellt werden. Einträge, die während der Iteration über das Verzeichnis hinzugefügt oder entfernt werden, sind möglicherweise nicht in den Iterationsergebnissen enthalten.

dir[Symbol.asyncIterator]()

Hinzugefügt in: v12.12.0

• Rückgabewert: <AsyncIterator> Ein AsyncIterator von <fs.Dirent>

Iteriert asynchron über das Verzeichnis, bis alle Einträge gelesen wurden. Weitere Details finden Sie in der POSIX readdir(3) Dokumentation.

Die vom asynchronen Iterator zurückgegebenen Einträge sind immer ein <fs.Dirent>. Der null-Fall von dir.read() wird intern behandelt.

Siehe <fs.Dir> für ein Beispiel.

Verzeichniseinträge, die von diesem Iterator zurückgegeben werden, befinden sich in keiner bestimmten Reihenfolge, wie sie von den zugrunde liegenden Verzeichnismechanismen des Betriebssystems bereitgestellt werden. Während der Iteration über das Verzeichnis hinzugefügte oder entfernte Einträge sind möglicherweise nicht in den Iterationsergebnissen enthalten.

Klasse: fs.Dirent

Hinzugefügt in: v10.10.0

Eine Darstellung eines Verzeichniseintrags, der eine Datei oder ein Unterverzeichnis innerhalb des Verzeichnisses sein kann, wie er durch das Lesen aus einem <fs.Dir> zurückgegeben wird. Der Verzeichniseintrag ist eine Kombination aus Dateinamen und Dateityp-Paaren.

Zusätzlich, wenn fs.readdir() oder fs.readdirSync() mit der Option withFileTypes auf true gesetzt aufgerufen wird, wird das resultierende Array mit <fs.Dirent> Objekten anstatt Strings oder <Buffer>s gefüllt.

dirent.isBlockDevice()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent> Objekt ein Blockgerät beschreibt.

dirent.isCharacterDevice()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent> Objekt ein Zeichengerät beschreibt.

dirent.isDirectory()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent>-Objekt ein Verzeichnis des Dateisystems beschreibt.

dirent.isFIFO()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent>-Objekt eine First-In-First-Out (FIFO)-Pipe beschreibt.

dirent.isFile()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent>-Objekt eine reguläre Datei beschreibt.

dirent.isSocket()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent>-Objekt einen Socket beschreibt.

dirent.isSymbolicLink()

Hinzugefügt in: v10.10.0

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Dirent>-Objekt einen symbolischen Link beschreibt.

dirent.name

Hinzugefügt in: v10.10.0

• <string> | <Buffer>

Der Dateiname, auf den sich dieses <fs.Dirent>-Objekt bezieht. Der Typ dieses Werts wird durch options.encoding bestimmt, der an fs.readdir() oder fs.readdirSync() übergeben wird.

dirent.parentPath

Hinzugefügt in: v21.4.0, v20.12.0, v18.20.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• <string>

Der Pfad zum übergeordneten Verzeichnis der Datei, auf die sich dieses <fs.Dirent>-Objekt bezieht.

dirent.path

[Verlauf]

Version	Änderungen
v23.2.0	Die Eigenschaft ist nicht mehr schreibgeschützt.
v23.0.0	Der Zugriff auf diese Eigenschaft löst eine Warnung aus. Sie ist jetzt schreibgeschützt.
v21.5.0, v20.12.0, v18.20.0	Veraltet seit: v21.5.0, v20.12.0, v18.20.0
v20.1.0, v18.17.0	Hinzugefügt in: v20.1.0, v18.17.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen dirent.parentPath.

• <string>

Alias für dirent.parentPath.

Klasse: fs.FSWatcher

Hinzugefügt in: v0.5.8

• Erweitert <EventEmitter>

Ein erfolgreicher Aufruf der Methode fs.watch() gibt ein neues <fs.FSWatcher>-Objekt zurück.

Alle <fs.FSWatcher>-Objekte emittieren ein 'change'-Ereignis, wenn eine bestimmte überwachte Datei geändert wird.

Ereignis: 'change'

Hinzugefügt in: v0.5.8

• eventType <string> Der Typ des aufgetretenen Änderungsereignisses
• filename <string> | <Buffer> Der geänderte Dateiname (falls relevant/verfügbar)

Wird ausgegeben, wenn sich etwas in einem überwachten Verzeichnis oder einer Datei ändert. Weitere Details finden Sie in fs.watch().

Das Argument filename wird möglicherweise nicht bereitgestellt, abhängig von der Unterstützung des Betriebssystems. Wenn filename bereitgestellt wird, wird es als <Buffer> bereitgestellt, wenn fs.watch() mit seiner encoding-Option auf 'buffer' aufgerufen wird, andernfalls ist filename eine UTF-8-Zeichenkette.

import { watch } from 'node:fs'
// Beispiel bei der Behandlung über den fs.watch()-Listener
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename)
    // Gibt aus: <Buffer ...>
  }
})

Ereignis: 'close'

Hinzugefügt in: v10.0.0

Wird ausgegeben, wenn der Watcher aufhört, auf Änderungen zu überwachen. Das geschlossene <fs.FSWatcher>-Objekt kann im Ereignishandler nicht mehr verwendet werden.

Ereignis: 'error'

Hinzugefügt in: v0.5.8

• error <Error>

Wird ausgegeben, wenn während der Überwachung der Datei ein Fehler auftritt. Das fehlerhafte <fs.FSWatcher>-Objekt kann im Ereignishandler nicht mehr verwendet werden.

watcher.close()

Hinzugefügt in: v0.5.8

Stoppt die Überwachung auf Änderungen an dem gegebenen <fs.FSWatcher>. Nach dem Stoppen kann das <fs.FSWatcher>-Objekt nicht mehr verwendet werden.

watcher.ref()

Hinzugefügt in: v14.3.0, v12.20.0

• Rückgabewert: <fs.FSWatcher>

Fordert beim Aufruf an, dass die Node.js-Ereignisschleife nicht beendet wird, solange der <fs.FSWatcher> aktiv ist. Mehrfaches Aufrufen von watcher.ref() hat keine Auswirkung.

Standardmäßig sind alle <fs.FSWatcher>-Objekte "referenziert", wodurch ein Aufruf von watcher.ref() normalerweise nicht notwendig ist, es sei denn, watcher.unref() wurde zuvor aufgerufen.

watcher.unref()

Hinzugefügt in: v14.3.0, v12.20.0

• Rückgabewert: <fs.FSWatcher>

Beim Aufruf benötigt das aktive <fs.FSWatcher>-Objekt nicht, dass die Node.js-Ereignisschleife aktiv bleibt. Wenn keine andere Aktivität die Ereignisschleife am Laufen hält, kann der Prozess beendet werden, bevor der Rückruf des <fs.FSWatcher>-Objekts aufgerufen wird. Mehrfaches Aufrufen von watcher.unref() hat keine Auswirkung.

Klasse: fs.StatWatcher

Hinzugefügt in: v14.3.0, v12.20.0

• Erweitert <EventEmitter>

Ein erfolgreicher Aufruf der Methode fs.watchFile() gibt ein neues <fs.StatWatcher>-Objekt zurück.

watcher.ref()

Hinzugefügt in: v14.3.0, v12.20.0

• Rückgabewert: <fs.StatWatcher>

Fordert beim Aufruf an, dass die Node.js-Ereignisschleife nicht beendet wird, solange der <fs.StatWatcher> aktiv ist. Mehrfaches Aufrufen von watcher.ref() hat keine Auswirkung.

Standardmäßig sind alle <fs.StatWatcher>-Objekte "referenziert", wodurch ein Aufruf von watcher.ref() normalerweise nicht notwendig ist, es sei denn, watcher.unref() wurde zuvor aufgerufen.

watcher.unref()

Hinzugefügt in: v14.3.0, v12.20.0

• Rückgabewert: <fs.StatWatcher>

Wenn aufgerufen, benötigt das aktive <fs.StatWatcher>-Objekt nicht, dass die Node.js-Ereignisschleife aktiv bleibt. Wenn keine andere Aktivität die Ereignisschleife am Laufen hält, kann der Prozess beendet werden, bevor der Rückruf des <fs.StatWatcher>-Objekts aufgerufen wird. Mehrmaliges Aufrufen von watcher.unref() hat keine Auswirkung.

Klasse: fs.ReadStream

Hinzugefügt in: v0.1.93

• Erweitert: <stream.Readable>

Instanzen von <fs.ReadStream> werden mit der Funktion fs.createReadStream() erstellt und zurückgegeben.

Ereignis: 'close'

Hinzugefügt in: v0.1.93

Wird ausgegeben, wenn der zugrunde liegende Datei-Descriptor des <fs.ReadStream> geschlossen wurde.

Ereignis: 'open'

Hinzugefügt in: v0.1.93

• fd <integer> Integer-Datei-Descriptor, der von <fs.ReadStream> verwendet wird.

Wird ausgegeben, wenn der Datei-Descriptor des <fs.ReadStream> geöffnet wurde.

Ereignis: 'ready'

Hinzugefügt in: v9.11.0

Wird ausgegeben, wenn der <fs.ReadStream> einsatzbereit ist.

Wird unmittelbar nach 'open' ausgelöst.

readStream.bytesRead

Hinzugefügt in: v6.4.0

• <number>

Die Anzahl der bisher gelesenen Bytes.

readStream.path

Hinzugefügt in: v0.1.93

• <string> | <Buffer>

Der Pfad zu der Datei, aus der der Stream liest, wie im ersten Argument von fs.createReadStream() angegeben. Wenn path als Zeichenkette übergeben wird, ist readStream.path eine Zeichenkette. Wenn path als <Buffer> übergeben wird, ist readStream.path ein <Buffer>. Wenn fd angegeben ist, ist readStream.path undefined.

readStream.pending

Hinzugefügt in: v11.2.0, v10.16.0

• <boolean>

Diese Eigenschaft ist true, wenn die zugrunde liegende Datei noch nicht geöffnet wurde, d. h. bevor das Ereignis 'ready' emittiert wird.

Klasse: fs.Stats

[Verlauf]

Version	Änderungen
v22.0.0, v20.13.0	Öffentlicher Konstruktor ist veraltet.
v8.1.0	Zeiten als Zahlen hinzugefügt.
v0.1.21	Hinzugefügt in: v0.1.21

Ein <fs.Stats>-Objekt liefert Informationen über eine Datei.

Objekte, die von fs.stat(), fs.lstat(), fs.fstat() und ihren synchronen Gegenstücken zurückgegeben werden, sind von diesem Typ. Wenn bigint in den an diese Methoden übergebenen options true ist, sind die numerischen Werte bigint anstelle von number, und das Objekt enthält zusätzliche Eigenschaften mit Nanosekunden-Genauigkeit, die mit Ns angehängt sind. Stat-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

bigint-Version:

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt ein Blockgerät beschreibt.

stats.isCharacterDevice()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt ein Zeichengerät beschreibt.

stats.isDirectory()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt ein Dateisystemverzeichnis beschreibt.

Wenn das <fs.Stats>-Objekt durch Aufruf von fs.lstat() auf einen symbolischen Link erhalten wurde, der auf ein Verzeichnis verweist, gibt diese Methode false zurück. Dies liegt daran, dass fs.lstat() Informationen über den symbolischen Link selbst und nicht den Pfad, auf den er verweist, zurückgibt.

stats.isFIFO()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt eine First-In-First-Out (FIFO)-Pipe beschreibt.

stats.isFile()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt eine reguläre Datei beschreibt.

stats.isSocket()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt einen Socket beschreibt.

stats.isSymbolicLink()

Hinzugefügt in: v0.1.10

• Rückgabewert: <boolean>

Gibt true zurück, wenn das <fs.Stats>-Objekt einen symbolischen Link beschreibt.

Diese Methode ist nur gültig, wenn fs.lstat() verwendet wird.

stats.dev

• <number> | <bigint>

Die numerische Kennung des Geräts, das die Datei enthält.

stats.ino

• <number> | <bigint>

Die dateisystemspezifische „Inode“-Nummer für die Datei.

stats.mode

• <number> | <bigint>

Ein Bitfeld, das den Dateityp und den Modus beschreibt.

stats.nlink

• <number> | <bigint>

Die Anzahl der Hardlinks, die für die Datei existieren.

stats.uid

• <number> | <bigint>

Die numerische Benutzerkennung des Benutzers, dem die Datei gehört (POSIX).

stats.gid

• <number> | <bigint>

Die numerische Gruppenkennung der Gruppe, der die Datei gehört (POSIX).

stats.rdev

• <number> | <bigint>

Eine numerische Gerätekennung, wenn die Datei ein Gerät darstellt.

stats.size

• <number> | <bigint>

Die Größe der Datei in Bytes.

Wenn das zugrunde liegende Dateisystem die Abfrage der Dateigröße nicht unterstützt, ist dies 0.

stats.blksize

• <number> | <bigint>

Die Blockgröße des Dateisystems für E/A-Operationen.

stats.blocks

• <number> | <bigint>

Die Anzahl der für diese Datei zugewiesenen Blöcke.

stats.atimeMs

Hinzugefügt in: v8.1.0

• <number> | <bigint>

Der Zeitstempel, der den Zeitpunkt des letzten Zugriffs auf diese Datei angibt, ausgedrückt in Millisekunden seit der POSIX-Epoche.

stats.mtimeMs

Hinzugefügt in: v8.1.0

• <number> | <bigint>

Der Zeitstempel, der den Zeitpunkt der letzten Änderung dieser Datei angibt, ausgedrückt in Millisekunden seit der POSIX-Epoche.

stats.ctimeMs

Hinzugefügt in: v8.1.0

• <number> | <bigint>

Der Zeitstempel, der den Zeitpunkt der letzten Änderung des Dateistatus angibt, ausgedrückt in Millisekunden seit der POSIX-Epoche.

stats.birthtimeMs

Hinzugefügt in: v8.1.0

• <number> | <bigint>

Der Zeitstempel, der den Erstellungszeitpunkt dieser Datei angibt, ausgedrückt in Millisekunden seit der POSIX-Epoche.

stats.atimeNs

Hinzugefügt in: v12.10.0

• <bigint>

Nur vorhanden, wenn bigint: true an die Methode übergeben wird, die das Objekt erzeugt. Der Zeitstempel, der den Zeitpunkt des letzten Zugriffs auf diese Datei angibt, ausgedrückt in Nanosekunden seit der POSIX-Epoche.

stats.mtimeNs

Hinzugefügt in: v12.10.0

• <bigint>

Nur vorhanden, wenn bigint: true an die Methode übergeben wird, die das Objekt erzeugt. Der Zeitstempel, der die letzte Änderung dieser Datei in Nanosekunden seit der POSIX-Epoche angibt.

stats.ctimeNs

Hinzugefügt in: v12.10.0

• <bigint>

Nur vorhanden, wenn bigint: true an die Methode übergeben wird, die das Objekt erzeugt. Der Zeitstempel, der die letzte Änderung des Dateistatus in Nanosekunden seit der POSIX-Epoche angibt.

stats.birthtimeNs

Hinzugefügt in: v12.10.0

• <bigint>

Nur vorhanden, wenn bigint: true an die Methode übergeben wird, die das Objekt erzeugt. Der Zeitstempel, der den Erstellungszeitpunkt dieser Datei in Nanosekunden seit der POSIX-Epoche angibt.

stats.atime

Hinzugefügt in: v0.11.13

• <Date>

Der Zeitstempel, der den Zeitpunkt des letzten Zugriffs auf diese Datei angibt.

stats.mtime

Hinzugefügt in: v0.11.13

• <Date>

Der Zeitstempel, der den Zeitpunkt der letzten Änderung dieser Datei angibt.

stats.ctime

Hinzugefügt in: v0.11.13

• <Date>

Der Zeitstempel, der den Zeitpunkt der letzten Änderung des Dateistatus angibt.

stats.birthtime

Hinzugefügt in: v0.11.13

• <Date>

Der Zeitstempel, der den Erstellungszeitpunkt dieser Datei angibt.

Stat-Zeitwerte

Die Eigenschaften atimeMs, mtimeMs, ctimeMs, birthtimeMs sind numerische Werte, die die entsprechenden Zeiten in Millisekunden enthalten. Ihre Genauigkeit ist plattformspezifisch. Wenn bigint: true an die Methode übergeben wird, die das Objekt erzeugt, sind die Eigenschaften BigInts, andernfalls sind sie Zahlen.

Die Eigenschaften atimeNs, mtimeNs, ctimeNs, birthtimeNs sind BigInts, die die entsprechenden Zeiten in Nanosekunden enthalten. Sie sind nur vorhanden, wenn bigint: true an die Methode übergeben wird, die das Objekt erzeugt. Ihre Genauigkeit ist plattformspezifisch.

atime, mtime, ctime und birthtime sind alternative Darstellungen der verschiedenen Zeiten als Date-Objekt. Die Date- und Zahlenwerte sind nicht miteinander verbunden. Das Zuweisen eines neuen Zahlenwerts oder das Ändern des Date-Werts wird sich nicht in der entsprechenden alternativen Darstellung widerspiegeln.

Die Zeiten im stat-Objekt haben die folgende Semantik:

• atime "Zugriffszeit": Zeitpunkt des letzten Zugriffs auf die Datei. Geändert durch die Systemaufrufe mknod(2), utimes(2) und read(2).
• mtime "Änderungszeit": Zeitpunkt der letzten Änderung der Datei. Geändert durch die Systemaufrufe mknod(2), utimes(2) und write(2).
• ctime "Änderungszeitpunkt": Zeitpunkt der letzten Änderung des Dateistatus (Änderung der Inode-Daten). Geändert durch die Systemaufrufe chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) und write(2).
• birthtime "Erstellungszeit": Zeitpunkt der Dateierstellung. Wird einmalig bei der Dateierstellung gesetzt. Auf Dateisystemen, auf denen birthtime nicht verfügbar ist, kann dieses Feld stattdessen entweder ctime oder 1970-01-01T00:00Z (d. h. Unix-Epoch-Zeitstempel 0) enthalten. Dieser Wert kann in diesem Fall größer als atime oder mtime sein. Unter Darwin und anderen FreeBSD-Varianten wird er auch gesetzt, wenn die atime mithilfe des Systemaufrufs utimes(2) explizit auf einen früheren Wert als die aktuelle birthtime gesetzt wird.

Vor Node.js 0.12 enthielt ctime unter Windows-Systemen die birthtime. Ab 0.12 ist ctime keine "Erstellungszeit", und unter Unix-Systemen war sie es auch nie.

Klasse: fs.StatFs

Hinzugefügt in: v19.6.0, v18.15.0

Liefert Informationen über ein gemountetes Dateisystem.

Objekte, die von fs.statfs() und seinem synchronen Gegenstück zurückgegeben werden, sind von diesem Typ. Wenn bigint in den an diese Methoden übergebenen options true ist, sind die numerischen Werte bigint anstelle von number.

StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

bigint Version:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Freie Blöcke, die für nicht privilegierte Benutzer verfügbar sind.

statfs.bfree

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Freie Blöcke im Dateisystem.

statfs.blocks

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Gesamtanzahl der Datenblöcke im Dateisystem.

statfs.bsize

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Optimale Blockgröße für die Datenübertragung.

statfs.ffree

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Freie Datei-Nodes im Dateisystem.

statfs.files

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Gesamtanzahl der Dateiknoten im Dateisystem.

statfs.type

Hinzugefügt in: v19.6.0, v18.15.0

• <number> | <bigint>

Dateisystemtyp.

Klasse: fs.WriteStream

Hinzugefügt in: v0.1.93

• Erweitert <stream.Writable>

Instanzen von <fs.WriteStream> werden mit der Funktion fs.createWriteStream() erstellt und zurückgegeben.

Ereignis: 'close'

Hinzugefügt in: v0.1.93

Wird ausgelöst, wenn der zugrunde liegende Dateideskriptor des <fs.WriteStream> geschlossen wurde.

Ereignis: 'open'

Hinzugefügt in: v0.1.93

• fd <integer> Integer-Dateideskriptor, der von <fs.WriteStream> verwendet wird.

Wird ausgelöst, wenn die Datei des <fs.WriteStream> geöffnet wird.

Ereignis: 'ready'

Hinzugefügt in: v9.11.0

Wird ausgelöst, wenn der <fs.WriteStream> einsatzbereit ist.

Wird unmittelbar nach 'open' ausgelöst.

writeStream.bytesWritten

Hinzugefügt in: v0.4.7

Die Anzahl der bisher geschriebenen Bytes. Enthält keine Daten, die noch zum Schreiben in der Warteschlange stehen.

writeStream.close([callback])

Hinzugefügt in: v0.9.4

• callback <Function>
  • err <Error>

Schließt writeStream. Optional wird ein Callback akzeptiert, der ausgeführt wird, sobald writeStream geschlossen ist.

writeStream.path

Hinzugefügt in: v0.1.93

Der Pfad zur Datei, in die der Stream schreibt, wie im ersten Argument von fs.createWriteStream() angegeben. Wenn path als Zeichenkette übergeben wird, ist writeStream.path eine Zeichenkette. Wenn path als <Buffer> übergeben wird, ist writeStream.path ein <Buffer>.

writeStream.pending

Hinzugefügt in: v11.2.0

• <boolean>

Diese Eigenschaft ist true, wenn die zugrunde liegende Datei noch nicht geöffnet wurde, d. h. bevor das Ereignis 'ready' emittiert wird.

fs.constants

• <Object>

Gibt ein Objekt zurück, das häufig verwendete Konstanten für Dateisystemoperationen enthält.

FS-Konstanten

Die folgenden Konstanten werden von fs.constants und fsPromises.constants exportiert.

Nicht jede Konstante ist auf jedem Betriebssystem verfügbar; dies ist besonders wichtig für Windows, wo viele der POSIX-spezifischen Definitionen nicht verfügbar sind. Für portable Anwendungen wird empfohlen, vor der Verwendung deren Vorhandensein zu überprüfen.

Um mehr als eine Konstante zu verwenden, verwenden Sie den bitweisen OR-Operator |.

Beispiel:

import { open, constants } from 'node:fs'

const { O_RDWR, O_CREAT, O_EXCL } = constants

open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
  // ...
})

Dateizugriffskonstanten

Die folgenden Konstanten sind für die Verwendung als mode-Parameter gedacht, der an fsPromises.access(), fs.access() und fs.accessSync() übergeben wird.

Konstante	Beschreibung
F_OK	Flag, das angibt, dass die Datei für den aufrufenden Prozess sichtbar ist. Dies ist nützlich, um festzustellen, ob eine Datei existiert, sagt aber nichts über rwx-Berechtigungen aus. Standardwert, wenn kein Modus angegeben ist.
R_OK	Flag, das angibt, dass die Datei vom aufrufenden Prozess gelesen werden kann.
W_OK	Flag, das angibt, dass die Datei vom aufrufenden Prozess geschrieben werden kann.
X_OK	Flag, das angibt, dass die Datei vom aufrufenden Prozess ausgeführt werden kann. Dies hat keine Auswirkung auf Windows (verhält sich wie fs.constants.F_OK).

Die Definitionen sind auch unter Windows verfügbar.

Dateikonstanten kopieren

Die folgenden Konstanten sind für die Verwendung mit fs.copyFile() vorgesehen.

Konstante	Beschreibung
COPYFILE_EXCL	Wenn vorhanden, schlägt der Kopiervorgang mit einem Fehler fehl, wenn der Zielpfad bereits existiert.
COPYFILE_FICLONE	Wenn vorhanden, versucht der Kopiervorgang, einen Copy-on-Write-Reflink zu erstellen. Wenn die zugrundeliegende Plattform Copy-on-Write nicht unterstützt, wird ein Fallback-Kopiermechanismus verwendet.
COPYFILE_FICLONE_FORCE	Wenn vorhanden, versucht der Kopiervorgang, einen Copy-on-Write-Reflink zu erstellen. Wenn die zugrundeliegende Plattform Copy-on-Write nicht unterstützt, schlägt der Vorgang mit einem Fehler fehl.

Die Definitionen sind auch unter Windows verfügbar.

Dateioffen-Konstanten

Die folgenden Konstanten sind für die Verwendung mit fs.open() vorgesehen.

Konstante	Beschreibung
O_RDONLY	Flag, das angibt, eine Datei für schreibgeschützten Zugriff zu öffnen.
O_WRONLY	Flag, das angibt, eine Datei für schreibgeschützten Zugriff zu öffnen.
O_RDWR	Flag, das angibt, eine Datei für Lese- und Schreibzugriff zu öffnen.
O_CREAT	Flag, das angibt, die Datei zu erstellen, wenn sie noch nicht existiert.
O_EXCL	Flag, das angibt, dass das Öffnen einer Datei fehlschlagen soll, wenn das Flag O_CREAT gesetzt ist und die Datei bereits existiert.
O_NOCTTY	Flag, das angibt, dass wenn der Pfad ein Terminalgerät identifiziert, das Öffnen des Pfads nicht dazu führen soll, dass dieses Terminal zum Steuerterminal für den Prozess wird (wenn der Prozess noch kein solches besitzt).
O_TRUNC	Flag, das angibt, dass wenn die Datei existiert und eine reguläre Datei ist und die Datei erfolgreich für den Schreibzugriff geöffnet wird, ihre Länge auf null gekürzt wird.
O_APPEND	Flag, das angibt, dass Daten an das Ende der Datei angehängt werden.
O_DIRECTORY	Flag, das angibt, dass das Öffnen fehlschlagen soll, wenn der Pfad kein Verzeichnis ist.
O_NOATIME	Flag, das angibt, dass Lesezugriffe auf das Dateisystem nicht mehr zu einer Aktualisierung der atime-Informationen führen, die der Datei zugeordnet sind. Dieses Flag ist nur auf Linux-Betriebssystemen verfügbar.
O_NOFOLLOW	Flag, das angibt, dass das Öffnen fehlschlagen soll, wenn der Pfad ein symbolischer Link ist.
O_SYNC	Flag, das angibt, dass die Datei für synchronisierte E/A geöffnet wird, wobei Schreibvorgänge auf die Dateiintegrität warten.
O_DSYNC	Flag, das angibt, dass die Datei für synchronisierte E/A geöffnet wird, wobei Schreibvorgänge auf die Datenintegrität warten.
O_SYMLINK	Flag, das angibt, den symbolischen Link selbst zu öffnen, anstatt die Ressource, auf die er verweist.
O_DIRECT	Wenn gesetzt, wird versucht, die Cache-Effekte der Datei-E/A zu minimieren.
O_NONBLOCK	Flag, das angibt, die Datei nach Möglichkeit im nicht blockierenden Modus zu öffnen.
UV_FS_O_FILEMAP	Wenn gesetzt, wird eine Dateizuordnung im Speicher verwendet, um auf die Datei zuzugreifen. Dieses Flag ist nur auf Windows-Betriebssystemen verfügbar. Auf anderen Betriebssystemen wird dieses Flag ignoriert.

Unter Windows sind nur O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY und UV_FS_O_FILEMAP verfügbar.

Dateityp-Konstanten

Die folgenden Konstanten sind für die Verwendung mit der mode-Eigenschaft des Objekts <fs.Stats> zur Bestimmung des Dateityps vorgesehen.

Konstante	Beschreibung
S_IFMT	Bitmaske zur Extraktion des Dateitypcodes.
S_IFREG	Dateityp-Konstante für eine reguläre Datei.
S_IFDIR	Dateityp-Konstante für ein Verzeichnis.
S_IFCHR	Dateityp-Konstante für eine zeichenorientierte Gerätedatei.
S_IFBLK	Dateityp-Konstante für eine blockorientierte Gerätedatei.
S_IFIFO	Dateityp-Konstante für ein FIFO/Pipe.
S_IFLNK	Dateityp-Konstante für einen symbolischen Link.
S_IFSOCK	Dateityp-Konstante für einen Socket.

Unter Windows sind nur S_IFCHR, S_IFDIR, S_IFLNK, S_IFMT und S_IFREG verfügbar.

Datei-Modus-Konstanten

Die folgenden Konstanten sind für die Verwendung mit der mode-Eigenschaft des Objekts <fs.Stats> zur Bestimmung der Zugriffsberechtigungen für eine Datei vorgesehen.

Konstante	Beschreibung
S_IRWXU	Dateimodus, der angibt, dass der Besitzer lesen, schreiben und ausführen kann.
S_IRUSR	Dateimodus, der angibt, dass der Besitzer lesen kann.
S_IWUSR	Dateimodus, der angibt, dass der Besitzer schreiben kann.
S_IXUSR	Dateimodus, der angibt, dass der Besitzer ausführen kann.
S_IRWXG	Dateimodus, der angibt, dass die Gruppe lesen, schreiben und ausführen kann.
S_IRGRP	Dateimodus, der angibt, dass die Gruppe lesen kann.
S_IWGRP	Dateimodus, der angibt, dass die Gruppe schreiben kann.
S_IXGRP	Dateimodus, der angibt, dass die Gruppe ausführen kann.
S_IRWXO	Dateimodus, der angibt, dass andere lesen, schreiben und ausführen können.
S_IROTH	Dateimodus, der angibt, dass andere lesen können.
S_IWOTH	Dateimodus, der angibt, dass andere schreiben können.
S_IXOTH	Dateimodus, der angibt, dass andere ausführen können.

Unter Windows sind nur S_IRUSR und S_IWUSR verfügbar.

Hinweise

Reihenfolge von callback- und promise-basierten Operationen

Da sie asynchron vom zugrunde liegenden Thread-Pool ausgeführt werden, gibt es keine garantierte Reihenfolge bei der Verwendung der callback- oder promise-basierten Methoden.

Beispielsweise ist das Folgende fehleranfällig, da der fs.stat()-Vorgang möglicherweise vor dem fs.rename()-Vorgang abgeschlossen wird:

const fs = require('node:fs')

fs.rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  console.log('renamed complete')
})
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err
  console.log(`stats: ${JSON.stringify(stats)}`)
})

Es ist wichtig, die Operationen korrekt zu ordnen, indem die Ergebnisse der einen abgewartet werden, bevor die andere aufgerufen wird:

ESM

import { rename, stat } from 'node:fs/promises'

const oldPath = '/tmp/hello'
const newPath = '/tmp/world'

try {
  await rename(oldPath, newPath)
  const stats = await stat(newPath)
  console.log(`stats: ${JSON.stringify(stats)}`)
} catch (error) {
  console.error('there was an error:', error.message)
}

CJS

const { rename, stat } = require('node:fs/promises')

;(async function (oldPath, newPath) {
  try {
    await rename(oldPath, newPath)
    const stats = await stat(newPath)
    console.log(`stats: ${JSON.stringify(stats)}`)
  } catch (error) {
    console.error('there was an error:', error.message)
  }
})('/tmp/hello', '/tmp/world')

Oder, wenn Sie die Callback-APIs verwenden, verschieben Sie den fs.stat()-Aufruf in den Callback des fs.rename()-Vorgangs:

ESM

import { rename, stat } from 'node:fs'

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

CJS

const { rename, stat } = require('node:fs/promises')

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

Dateipfade

Die meisten fs-Operationen akzeptieren Dateipfade, die als Zeichenkette, als <Buffer> oder als <URL>-Objekt mit dem Protokoll file: angegeben werden können.

Zeichenkettenpfade

Zeichenkettenpfade werden als UTF-8-Zeichenfolgen interpretiert, die den absoluten oder relativen Dateinamen identifizieren. Relative Pfade werden relativ zum aktuellen Arbeitsverzeichnis aufgelöst, das durch Aufrufen von process.cwd() bestimmt wird.

Beispiel mit absolutem Pfad unter POSIX:

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

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // Etwas mit der Datei machen
} finally {
  await fd?.close()
}

Beispiel mit relativem Pfad unter POSIX (relativ zu process.cwd()):

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

let fd
try {
  fd = await open('file.txt', 'r')
  // Etwas mit der Datei machen
} finally {
  await fd?.close()
}

Datei-URL-Pfade

Hinzugefügt in: v7.6.0

Für die meisten Funktionen des Moduls node:fs kann das Argument path oder filename als <URL>-Objekt mit dem Protokoll file: übergeben werden.

import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

file:-URLs sind immer absolute Pfade.

Plattform-spezifische Überlegungen

Unter Windows werden file: <URL>s mit einem Hostnamen in UNC-Pfade konvertiert, während file: <URL>s mit Laufwerksbuchstaben in lokale absolute Pfade konvertiert werden. file: <URL>s ohne Hostnamen und ohne Laufwerksbuchstaben führen zu einem Fehler:

import { readFileSync } from 'node:fs'
// Unter Windows:

// - WHATWG file URLs mit Hostname werden in UNC-Pfade konvertiert
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - WHATWG file URLs mit Laufwerksbuchstaben werden in absolute Pfade konvertiert
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - WHATWG file URLs ohne Hostname müssen einen Laufwerksbuchstaben haben
readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'))
readFileSync(new URL('file:///c/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

file: <URL>s mit Laufwerksbuchstaben müssen : als Trennzeichen direkt nach dem Laufwerksbuchstaben verwenden. Die Verwendung eines anderen Trennzeichens führt zu einem Fehler.

Auf allen anderen Plattformen werden file: <URL>s mit einem Hostnamen nicht unterstützt und führen zu einem Fehler:

import { readFileSync } from 'node:fs'
// Auf anderen Plattformen:

// - WHATWG file URLs mit Hostname werden nicht unterstützt
// file://hostname/p/a/t/h/file => throw!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG file URLs werden in absolute Pfade konvertiert
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

Ein file: <URL> mit kodierten Schrägstrichen führt auf allen Plattformen zu einem Fehler:

import { readFileSync } from 'node:fs'

// Unter Windows
readFileSync(new URL('file:///C:/p/a/t/h/%2F'))
readFileSync(new URL('file:///C:/p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

// Unter POSIX
readFileSync(new URL('file:///p/a/t/h/%2F'))
readFileSync(new URL('file:///p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
/ characters */

Unter Windows führen file: <URL>s mit kodierten Backslashes zu einem Fehler:

import { readFileSync } from 'node:fs'

// Unter Windows
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

Pufferpfade

Pfade, die mit einem <Buffer> angegeben werden, sind hauptsächlich auf bestimmten POSIX-Betriebssystemen nützlich, die Dateipfade als opake Bytefolgen behandeln. Auf solchen Systemen kann ein einzelner Dateipfad Untersequenzen enthalten, die mehrere Zeichenkodierungen verwenden. Wie bei String-Pfaden können <Buffer>-Pfade relativ oder absolut sein:

Beispiel mit einem absoluten Pfad unter POSIX:

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

let fd
try {
  fd = await open(Buffer.from('/open/some/file.txt'), 'r')
  // Datei verarbeiten
} finally {
  await fd?.close()
}

Arbeitsverzeichnisse pro Laufwerk unter Windows

Unter Windows folgt Node.js dem Konzept des Arbeitsverzeichnisses pro Laufwerk. Dieses Verhalten lässt sich beobachten, wenn ein Laufwerkspfad ohne Backslash verwendet wird. Beispielsweise kann fs.readdirSync('C:\\') möglicherweise ein anderes Ergebnis liefern als fs.readdirSync('C:'). Weitere Informationen finden Sie auf dieser MSDN-Seite.

Datei-Deskriptoren

Auf POSIX-Systemen verwaltet der Kernel für jeden Prozess eine Tabelle der aktuell geöffneten Dateien und Ressourcen. Jede geöffnete Datei erhält eine einfache numerische Kennung, einen sogenannten Datei-Deskriptor. Auf Systemebene verwenden alle Dateisystemoperationen diese Datei-Deskriptoren, um jede einzelne Datei zu identifizieren und zu verfolgen. Windows-Systeme verwenden einen anderen, aber konzeptionell ähnlichen Mechanismus zur Ressourcenverfolgung. Zur Vereinfachung für die Benutzer abstrahiert Node.js die Unterschiede zwischen den Betriebssystemen und weist allen geöffneten Dateien einen numerischen Datei-Deskriptor zu.

Die callback-basierten fs.open()- und synchronen fs.openSync()-Methoden öffnen eine Datei und weisen einen neuen Datei-Deskriptor zu. Nach der Zuweisung kann der Datei-Deskriptor verwendet werden, um Daten zu lesen, Daten zu schreiben oder Informationen über die Datei anzufordern.

Betriebssysteme beschränken die Anzahl der Datei-Deskriptoren, die gleichzeitig geöffnet sein dürfen. Daher ist es wichtig, den Deskriptor zu schließen, wenn die Operationen abgeschlossen sind. Andernfalls entsteht ein Speicherleck, das letztendlich zum Absturz der Anwendung führt.

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

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

open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err
  try {
    fstat(fd, (err, stat) => {
      if (err) {
        closeFd(fd)
        throw err
      }

      // stat verwenden

      closeFd(fd)
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

Die Promise-basierten APIs verwenden ein <FileHandle>-Objekt anstelle des numerischen Datei-Deskriptors. Diese Objekte werden vom System besser verwaltet, um sicherzustellen, dass keine Ressourcen verloren gehen. Es ist jedoch weiterhin erforderlich, sie zu schließen, wenn die Operationen abgeschlossen sind:

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

let file
try {
  file = await open('/open/some/file.txt', 'r')
  const stat = await file.stat()
  // stat verwenden
} finally {
  await file.close()
}

Threadpool-Nutzung

Alle Callback- und Promise-basierten Dateisystem-APIs (mit Ausnahme von fs.FSWatcher()) verwenden den Threadpool von libuv. Dies kann für einige Anwendungen überraschende und negative Auswirkungen auf die Leistung haben. Weitere Informationen finden Sie in der Dokumentation zu UV_THREADPOOL_SIZE.

Dateisystem-Flags

Die folgenden Flags sind überall dort verfügbar, wo die Option flag eine Zeichenkette akzeptiert.

• 'a': Datei zum Anhängen öffnen. Die Datei wird erstellt, wenn sie nicht existiert.
• 'ax': Wie 'a', schlägt aber fehl, wenn der Pfad existiert.
• 'a+': Datei zum Lesen und Anhängen öffnen. Die Datei wird erstellt, wenn sie nicht existiert.
• 'ax+': Wie 'a+', schlägt aber fehl, wenn der Pfad existiert.
• 'as': Datei zum Anhängen im synchronen Modus öffnen. Die Datei wird erstellt, wenn sie nicht existiert.
• 'as+': Datei zum Lesen und Anhängen im synchronen Modus öffnen. Die Datei wird erstellt, wenn sie nicht existiert.
• 'r': Datei zum Lesen öffnen. Es tritt eine Ausnahme auf, wenn die Datei nicht existiert.
• 'rs': Datei zum Lesen im synchronen Modus öffnen. Es tritt eine Ausnahme auf, wenn die Datei nicht existiert.
• 'r+': Datei zum Lesen und Schreiben öffnen. Es tritt eine Ausnahme auf, wenn die Datei nicht existiert.
• 'rs+': Datei zum Lesen und Schreiben im synchronen Modus öffnen. Weist das Betriebssystem an, den lokalen Dateisystemcache zu umgehen. Dies ist hauptsächlich nützlich zum Öffnen von Dateien auf NFS-Mounts, da der potenziell veraltete lokale Cache übersprungen werden kann. Dies hat sehr reale Auswirkungen auf die E/A-Leistung, daher wird die Verwendung dieses Flags nicht empfohlen, es sei denn, es ist erforderlich. Dies macht fs.open() oder fsPromises.open() nicht zu einem synchronen blockierenden Aufruf. Wenn ein synchroner Betrieb gewünscht wird, sollte etwas wie fs.openSync() verwendet werden.
• 'w': Datei zum Schreiben öffnen. Die Datei wird erstellt (falls sie nicht existiert) oder abgeschnitten (falls sie existiert).
• 'wx': Wie 'w', schlägt aber fehl, wenn der Pfad existiert.
• 'w+': Datei zum Lesen und Schreiben öffnen. Die Datei wird erstellt (falls sie nicht existiert) oder abgeschnitten (falls sie existiert).
• 'wx+': Wie 'w+', schlägt aber fehl, wenn der Pfad existiert.

flag kann auch eine Zahl sein, wie in open(2) dokumentiert; häufig verwendete Konstanten sind von fs.constants verfügbar. Unter Windows werden Flags nach Bedarf in ihre Äquivalente übersetzt, z. B. O_WRONLY in FILE_GENERIC_WRITE oder O_EXCL|O_CREAT in CREATE_NEW, wie von CreateFileW akzeptiert.

Das exklusive Flag 'x' (Flag O_EXCL in open(2)) führt dazu, dass der Vorgang einen Fehler zurückgibt, wenn der Pfad bereits existiert. Unter POSIX gibt die Verwendung von O_EXCL einen Fehler zurück, selbst wenn der Link auf einen Pfad verweist, der nicht existiert, wenn der Pfad ein symbolischer Link ist. Das exklusive Flag funktioniert möglicherweise nicht mit Netzwerkdateisystemen.

Unter Linux funktionieren positionale Schreibvorgänge nicht, wenn die Datei im Anhängemodus geöffnet wird. Der Kernel ignoriert das Positionsargument und hängt die Daten immer an das Ende der Datei an.

Das Ändern einer Datei anstelle des Ersetzens erfordert möglicherweise, dass die Option flag auf 'r+' anstatt auf den Standardwert 'w' gesetzt wird.

Das Verhalten einiger Flags ist plattformspezifisch. Daher gibt das Öffnen eines Verzeichnisses unter macOS und Linux mit dem Flag 'a+', wie im folgenden Beispiel, einen Fehler zurück. Im Gegensatz dazu wird unter Windows und FreeBSD ein Dateideskriptor oder ein FileHandle zurückgegeben.

// macOS und Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: ungültige Operation auf einem Verzeichnis, open <directory>]
})

// Windows und FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
})

Unter Windows schlägt das Öffnen einer vorhandenen versteckten Datei mit dem Flag 'w' (entweder über fs.open(), fs.writeFile() oder fsPromises.open()) mit EPERM fehl. Vorhandene versteckte Dateien können mit dem Flag 'r+' zum Schreiben geöffnet werden.

Ein Aufruf von fs.ftruncate() oder filehandle.truncate() kann verwendet werden, um den Dateiinhalt zurückzusetzen.