File system

[Stable: 2 - Stabile]

Stable: 2 Stabilità: 2 - Stabile

Codice sorgente: lib/fs.js

Il modulo node:fs consente di interagire con il file system in un modo modellato sulle funzioni POSIX standard.

Per utilizzare le API basate su promise:

ESM

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

CJS

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

Per utilizzare le API di callback e sincrone:

ESM

import * as fs from 'node:fs'

CJS

const fs = require('node:fs')

Tutte le operazioni del file system hanno forme sincrone, di callback e basate su promise e sono accessibili sia utilizzando la sintassi CommonJS che i moduli ES6 (ESM).

Esempio di promise

Le operazioni basate su promise restituiscono una promise che viene soddisfatta quando l'operazione asincrona è completata.

ESM

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

try {
  await unlink('/tmp/hello')
  console.log('eliminato correttamente /tmp/hello')
} catch (error) {
  console.error('si è verificato un errore:', error.message)
}

CJS

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

;(async function (path) {
  try {
    await unlink(path)
    console.log(`eliminato correttamente ${path}`)
  } catch (error) {
    console.error('si è verificato un errore:', error.message)
  }
})('/tmp/hello')

Esempio di callback

La forma di callback prende una funzione di callback di completamento come ultimo argomento e invoca l'operazione in modo asincrono. Gli argomenti passati al callback di completamento dipendono dal metodo, ma il primo argomento è sempre riservato a un'eccezione. Se l'operazione viene completata correttamente, il primo argomento è null o undefined.

ESM

import { unlink } from 'node:fs'

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

CJS

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

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

Le versioni basate su callback delle API del modulo node:fs sono preferibili all'uso delle API promise quando è richiesta la massima performance (sia in termini di tempo di esecuzione che di allocazione di memoria).

Esempio sincrono

Le API sincrone bloccano il ciclo di eventi di Node.js e l'ulteriore esecuzione di JavaScript fino al completamento dell'operazione. Le eccezioni vengono generate immediatamente e possono essere gestite utilizzando try…catch, oppure possono essere lasciate propagare.

ESM

import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('eliminato correttamente /tmp/hello')
} catch (err) {
  // gestisci l'errore
}

CJS

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

try {
  unlinkSync('/tmp/hello')
  console.log('eliminato correttamente /tmp/hello')
} catch (err) {
  // gestisci l'errore
}

API Promises

[Cronologia]

Versione	Modifiche
v14.0.0	Esposta come require('fs/promises').
v11.14.0, v10.17.0	Questa API non è più sperimentale.
v10.1.0	L'API è accessibile solo tramite require('fs').promises.
v10.0.0	Aggiunta in: v10.0.0

L'API fs/promises fornisce metodi asincroni del file system che restituiscono promises.

Le API promises utilizzano il threadpool sottostante di Node.js per eseguire operazioni sul file system al di fuori del thread del ciclo di eventi. Queste operazioni non sono sincronizzate o threadsafe. È necessario prestare attenzione quando si eseguono più modifiche simultanee sullo stesso file, altrimenti si possono verificare danni ai dati.

Classe: FileHandle

Aggiunta in: v10.0.0

Un oggetto <FileHandle> è un wrapper oggetto per un descrittore di file numerico.

Le istanze dell'oggetto <FileHandle> vengono create dal metodo fsPromises.open().

Tutti gli oggetti <FileHandle> sono <EventEmitter>s.

Se un <FileHandle> non viene chiuso utilizzando il metodo filehandle.close(), cercherà di chiudere automaticamente il descrittore di file ed emetterà un avviso di processo, aiutando a prevenire perdite di memoria. Si prega di non fare affidamento su questo comportamento perché può essere inaffidabile e il file potrebbe non essere chiuso. Invece, chiudere sempre esplicitamente i <FileHandle>s. Node.js potrebbe cambiare questo comportamento in futuro.

Evento: 'close'

Aggiunto in: v15.4.0

L'evento 'close' viene emesso quando il <FileHandle> è stato chiuso e non può più essere utilizzato.

filehandle.appendFile(data[, options])

[Cronologia]

Versione	Modifiche
v21.1.0, v20.10.0	L'opzione flush è ora supportata.
v15.14.0, v14.18.0	L'argomento data supporta AsyncIterable, Iterable e Stream.
v14.0.0	Il parametro data non converte più input non supportati in stringhe.
v10.0.0	Aggiunto in: v10.0.0

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

• options <Oggetto> | <stringa>

  • encoding <stringa> | <null> Predefinito: 'utf8'
  • flush <boolean> Se true, il descrittore del file sottostante viene svuotato prima di chiuderlo. Predefinito: false.

• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Alias di filehandle.writeFile().

Quando si opera su handle di file, la modalità non può essere modificata rispetto a quella impostata con fsPromises.open(). Pertanto, questo è equivalente a filehandle.writeFile().

filehandle.chmod(mode)

Aggiunto in: v10.0.0

• mode <integer> la maschera dei bit della modalità file.
• Restituisce: <Promise> Si adempie con undefined in caso di successo.

Modifica le autorizzazioni sul file. Vedi chmod(2).

filehandle.chown(uid, gid)

Aggiunto in: v10.0.0

• uid <integer> L'ID utente del nuovo proprietario del file.
• gid <integer> L'ID del gruppo del nuovo gruppo del file.
• Restituisce: <Promise> Si adempie con undefined in caso di successo.

Cambia la proprietà del file. Un wrapper per chown(2).

filehandle.close()

Aggiunto in: v10.0.0

• Restituisce: <Promise> Si adempie con undefined in caso di successo.

Chiude l'handle del file dopo aver atteso il completamento di qualsiasi operazione in sospeso sull'handle.

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

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

filehandle.createReadStream([options])

Aggiunto in: v16.11.0

• options <Object>

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

• Restituisce: <fs.ReadStream>

options può includere i valori start e end per leggere un intervallo di byte dal file invece dell'intero file. Sia start che end sono inclusivi e iniziano a contare da 0, i valori consentiti sono nell'intervallo [0, Number.MAX_SAFE_INTEGER]. Se start viene omesso o è undefined, filehandle.createReadStream() legge in sequenza dalla posizione corrente del file. encoding può essere uno qualsiasi di quelli accettati da <Buffer>.

Se FileHandle punta a un dispositivo a caratteri che supporta solo letture bloccanti (come la tastiera o la scheda audio), le operazioni di lettura non terminano finché i dati non sono disponibili. Ciò può impedire al processo di uscire e allo stream di chiudersi naturalmente.

Per impostazione predefinita, lo stream emetterà un evento 'close' dopo essere stato distrutto. Imposta l'opzione emitClose su false per modificare questo comportamento.

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

const fd = await open('/dev/input/event0')
// Crea uno stream da un dispositivo a caratteri.
const stream = fd.createReadStream()
setTimeout(() => {
  stream.close() // Questo potrebbe non chiudere lo stream.
  // Contrassegnare artificialmente la fine dello stream, come se la risorsa sottostante avesse
  // indicato la fine del file da sola, consente allo stream di chiudersi.
  // Ciò non annulla le operazioni di lettura in sospeso e, se ce n'è una
  // operazione, il processo potrebbe comunque non essere in grado di uscire correttamente
  // finché non termina.
  stream.push(null)
  stream.read(0)
}, 100)

Se autoClose è false, il descrittore del file non verrà chiuso, anche se si verifica un errore. È responsabilità dell'applicazione chiuderlo e assicurarsi che non vi siano perdite di descrittori di file. Se autoClose è impostato su true (comportamento predefinito), su 'error' o 'end' il descrittore del file verrà chiuso automaticamente.

Un esempio per leggere gli ultimi 10 byte di un file di 100 byte:

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

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

filehandle.createWriteStream([options])

[Cronologia]

Versione	Modifiche
v21.0.0, v20.10.0	L'opzione flush è ora supportata.
v16.11.0	Aggiunto in: v16.11.0

• options <Object>

  • encoding <string> Predefinito: 'utf8'
  • autoClose <boolean> Predefinito: true
  • emitClose <boolean> Predefinito: true
  • start <integer>
  • highWaterMark <number> Predefinito: 16384
  • flush <boolean> Se true, il descrittore di file sottostante viene scaricato prima di chiuderlo. Predefinito: false.

• Restituisce: <fs.WriteStream>

options può anche includere un'opzione start per consentire la scrittura di dati in una posizione successiva all'inizio del file, i valori consentiti sono nell'intervallo [0, Number.MAX_SAFE_INTEGER]. La modifica di un file anziché la sua sostituzione potrebbe richiedere che l'opzione flags open sia impostata su r+ anziché sul valore predefinito r. La encoding può essere una qualsiasi di quelle accettate da <Buffer>.

Se autoClose è impostato su true (comportamento predefinito) su 'error' o 'finish', il descrittore del file verrà chiuso automaticamente. Se autoClose è false, il descrittore del file non verrà chiuso, anche in caso di errore. È responsabilità dell'applicazione chiuderlo e assicurarsi che non ci siano perdite del descrittore di file.

Per impostazione predefinita, lo stream emetterà un evento 'close' dopo che è stato distrutto. Imposta l'opzione emitClose su false per modificare questo comportamento.

filehandle.datasync()

Aggiunto in: v10.0.0

• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Forza tutte le operazioni di I/O attualmente in coda associate al file allo stato di completamento I/O sincronizzato del sistema operativo. Fare riferimento alla documentazione POSIX fdatasync(2) per i dettagli.

A differenza di filehandle.sync, questo metodo non esegue il flush dei metadati modificati.

filehandle.fd

Aggiunto in: v10.0.0

• <number> Il descrittore di file numerico gestito dall'oggetto <FileHandle>.

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

[Cronologia]

Versione	Modifiche
v21.0.0	Accetta valori bigint come position.
v10.0.0	Aggiunto in: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView> Un buffer che verrà riempito con i dati del file letti.
• offset <integer> La posizione nel buffer in cui iniziare il riempimento. Predefinito: 0
• length <integer> Il numero di byte da leggere. Predefinito: buffer.byteLength - offset
• position <integer> | <bigint> | <null> La posizione da cui iniziare a leggere i dati dal file. Se null o -1, i dati verranno letti dalla posizione corrente del file e la posizione verrà aggiornata. Se position è un intero non negativo, la posizione corrente del file rimarrà invariata. Predefinito: null
• Restituisce: <Promise> Si risolve in caso di successo con un oggetto con due proprietà:
  • bytesRead <integer> Il numero di byte letti
  • buffer <Buffer> | <TypedArray> | <DataView> Un riferimento all'argomento buffer passato.

Legge i dati dal file e li memorizza nel buffer specificato.

Se il file non viene modificato contemporaneamente, la fine del file viene raggiunta quando il numero di byte letti è zero.

filehandle.read([options])

[Cronologia]

Versione	Modifiche
v21.0.0	Accetta valori bigint come position.
v13.11.0, v12.17.0	Aggiunto in: v13.11.0, v12.17.0

• options <Oggetto>
  • buffer <Buffer> | <TypedArray> | <DataView> Un buffer che verrà riempito con i dati del file letti. Predefinito: Buffer.alloc(16384)
  • offset <integer> La posizione nel buffer in cui iniziare a riempire. Predefinito: 0
  • length <integer> Il numero di byte da leggere. Predefinito: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> La posizione da cui iniziare la lettura dei dati dal file. Se null o -1, i dati verranno letti dalla posizione corrente del file e la posizione verrà aggiornata. Se position è un numero intero non negativo, la posizione corrente del file rimarrà invariata. Predefinito: null
• Restituisce: <Promise> Si risolve in caso di successo con un oggetto con due proprietà:
  • bytesRead <integer> Il numero di byte letti
  • buffer <Buffer> | <TypedArray> | <DataView> Un riferimento all'argomento buffer passato.

Legge i dati dal file e li memorizza nel buffer specificato.

Se il file non viene modificato contemporaneamente, la fine del file viene raggiunta quando il numero di byte letti è zero.

filehandle.read(buffer[, options])

[Cronologia]

Versione	Modifiche
v21.0.0	Accetta valori bigint come position.
v18.2.0, v16.17.0	Aggiunto in: v18.2.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView> Un buffer che verrà riempito con i dati del file letti.

• options <Object>

  • offset <integer> La posizione nel buffer in cui iniziare a riempire. Predefinito: 0
  • length <integer> Il numero di byte da leggere. Predefinito: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> La posizione da cui iniziare a leggere i dati dal file. Se null o -1, i dati verranno letti dalla posizione corrente del file e la posizione verrà aggiornata. Se position è un numero intero non negativo, la posizione corrente del file rimarrà invariata. Predefinito: null

• Restituisce: <Promise> Si risolve in caso di successo con un oggetto con due proprietà:

  • bytesRead <integer> Il numero di byte letti
  • buffer <Buffer> | <TypedArray> | <DataView> Un riferimento all'argomento buffer passato.

Legge i dati dal file e li memorizza nel buffer specificato.

Se il file non viene modificato contemporaneamente, la fine del file viene raggiunta quando il numero di byte letti è zero.

filehandle.readableWebStream([options])

[Cronologia]

Versione	Modifiche
v20.0.0, v18.17.0	Aggiunta opzione per creare uno stream 'bytes'.
v17.0.0	Aggiunto in: v17.0.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• options <Oggetto>

  • type <stringa> | <undefined> Indica se aprire uno stream normale o uno stream 'bytes'. Predefinito: undefined

• Restituisce: <ReadableStream>

Restituisce un ReadableStream che può essere usato per leggere i dati dei file.

Verrà generato un errore se questo metodo viene chiamato più di una volta o se viene chiamato dopo che il FileHandle è stato chiuso o è in fase di chiusura.

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

Mentre il ReadableStream leggerà il file fino al completamento, non chiuderà automaticamente il FileHandle. Il codice utente deve comunque chiamare il metodo fileHandle.close().

filehandle.readFile(options)

Aggiunto in: v10.0.0

• options <Oggetto> | <stringa>

  • encoding <stringa> | <null> Predefinito: null
  • signal <AbortSignal> consente di interrompere un readFile in corso

• Restituisce: <Promise> Si completa con successo con il contenuto del file. Se non viene specificata alcuna codifica (utilizzando options.encoding), i dati vengono restituiti come un oggetto <Buffer>. Altrimenti, i dati saranno una stringa.

Legge in modo asincrono l'intero contenuto di un file.

Se options è una stringa, allora specifica la encoding.

Il <FileHandle> deve supportare la lettura.

Se vengono effettuate una o più chiamate filehandle.read() su un handle di file e poi viene effettuata una chiamata filehandle.readFile(), i dati verranno letti dalla posizione corrente fino alla fine del file. Non legge sempre dall'inizio del file.

filehandle.readLines([options])

Aggiunto in: v18.11.0

• options <Object>

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

• Restituisce: <readline.InterfaceConstructor>

Metodo pratico per creare un'interfaccia readline e trasmettere in streaming il file. Vedere filehandle.createReadStream() per le opzioni.

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

Aggiunto in: v13.13.0, v12.17.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> L'offset dall'inizio del file da cui devono essere letti i dati. Se position non è un number, i dati verranno letti dalla posizione corrente. Predefinito: null
• Restituisce: <Promise> Si risolve in caso di successo con un oggetto contenente due proprietà:
  • bytesRead <integer> il numero di byte letti
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> proprietà contenente un riferimento all'input buffers.

Legge da un file e scrive in un array di <ArrayBufferView>s

filehandle.stat([options])

[Cronologia]

Versione	Modifiche
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti debbano essere bigint.
v10.0.0	Aggiunto in: v10.0.0

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.

• Restituisce: <Promise> Si risolve con un <fs.Stats> per il file.

filehandle.sync()

Aggiunto in: v10.0.0

• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Richiede che tutti i dati per il descrittore di file aperto vengano scaricati sul dispositivo di archiviazione. L'implementazione specifica è specifica per il sistema operativo e il dispositivo. Fare riferimento alla documentazione POSIX fsync(2) per maggiori dettagli.

filehandle.truncate(len)

Aggiunto in: v10.0.0

• len <integer> Predefinito: 0
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Tronca il file.

Se il file era più grande di len byte, nel file verranno conservati solo i primi len byte.

L'esempio seguente conserva solo i primi quattro byte del file:

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

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

Se il file era precedentemente più corto di len byte, viene esteso e la parte estesa viene riempita con byte null ('\0'):

Se len è negativo, verrà utilizzato 0.

filehandle.utimes(atime, mtime)

Aggiunto in: v10.0.0

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Restituisce: <Promise>

Cambia i timestamp del file system dell'oggetto a cui fa riferimento il <FileHandle>, quindi soddisfa la promise senza argomenti in caso di successo.

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

[Storia]

Versione	Modifiche
v14.0.0	Il parametro buffer non forzerà più l'input non supportato nei buffer.
v10.0.0	Aggiunto in: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> La posizione iniziale all'interno di buffer in cui iniziano i dati da scrivere.
• length <integer> Il numero di byte da scrivere da buffer. Predefinito: buffer.byteLength - offset
• position <integer> | <null> L'offset dall'inizio del file in cui devono essere scritti i dati da buffer. Se position non è un number, i dati verranno scritti nella posizione corrente. Per maggiori dettagli, consultare la documentazione POSIX pwrite(2). Predefinito: null
• Restituisce: <Promise>

Scrive buffer nel file.

La promise viene soddisfatta con un oggetto contenente due proprietà:

• bytesWritten <integer> il numero di byte scritti
• buffer <Buffer> | <TypedArray> | <DataView> un riferimento al buffer scritto.

Non è sicuro usare filehandle.write() più volte sullo stesso file senza attendere che la promise venga soddisfatta (o rifiutata). Per questo scenario, usa filehandle.createWriteStream().

Su Linux, le scritture posizionali non funzionano quando il file è aperto in modalità di accodamento. Il kernel ignora l'argomento della posizione e aggiunge sempre i dati alla fine del file.

filehandle.write(buffer[, options])

Aggiunto in: v18.3.0, v16.17.0

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

• options <Object>

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

• Restituisce: <Promise>

Scrive buffer nel file.

Simile alla funzione filehandle.write sopra, questa versione accetta un oggetto options opzionale. Se non viene specificato alcun oggetto options, verranno utilizzati i valori predefiniti sopra.

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

[Cronologia]

Versione	Modifiche
v14.0.0	Il parametro string non converte più input non supportati in stringhe.
v10.0.0	Aggiunto in: v10.0.0

• string <string>
• position <integer> | <null> L'offset dall'inizio del file dove devono essere scritti i dati da string. Se position non è un numero, i dati verranno scritti nella posizione corrente. Vedere la documentazione POSIX pwrite(2) per maggiori dettagli. Predefinito: null
• encoding <string> La codifica stringa prevista. Predefinito: 'utf8'
• Restituisce: <Promise>

Scrive string nel file. Se string non è una stringa, la promise viene rifiutata con un errore.

La promise viene soddisfatta con un oggetto contenente due proprietà:

• bytesWritten <integer> il numero di byte scritti
• buffer <string> un riferimento alla string scritta.

Non è sicuro utilizzare filehandle.write() più volte sullo stesso file senza attendere che la promise sia soddisfatta (o rifiutata). Per questo scenario, utilizzare filehandle.createWriteStream().

Su Linux, le scritture posizionali non funzionano quando il file viene aperto in modalità di accodamento. Il kernel ignora l'argomento di posizione e aggiunge sempre i dati alla fine del file.

filehandle.writeFile(data, options)

[Cronologia]

Versione	Modifiche
v15.14.0, v14.18.0	L'argomento data supporta AsyncIterable, Iterable e Stream.
v14.0.0	Il parametro data non converte più input non supportati in stringhe.
v10.0.0	Aggiunto in: v10.0.0

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

• options <Oggetto> | <stringa>

  • encoding <stringa> | <null> La codifica dei caratteri prevista quando data è una stringa. Predefinito: 'utf8'

• Restituisce: <Promise>

Scrive in modo asincrono i dati in un file, sostituendo il file se esiste già. data può essere una stringa, un buffer, un oggetto <AsyncIterable> o un oggetto <Iterable>. La promise viene risolta senza argomenti in caso di successo.

Se options è una stringa, specifica la codifica.

Il <FileHandle> deve supportare la scrittura.

Non è sicuro utilizzare filehandle.writeFile() più volte sullo stesso file senza attendere che la promise venga risolta (o rifiutata).

Se una o più chiamate filehandle.write() vengono effettuate su un handle di file e quindi viene effettuata una chiamata filehandle.writeFile(), i dati verranno scritti dalla posizione corrente fino alla fine del file. Non scrive sempre dall'inizio del file.

filehandle.writev(buffers[, position])

Aggiunto in: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> L'offset dall'inizio del file dove devono essere scritti i dati da buffers. Se position non è un number, i dati saranno scritti nella posizione corrente. Predefinito: null
• Restituisce: <Promise>

Scrive un array di <ArrayBufferView> nel file.

La promise viene risolta con un oggetto contenente due proprietà:

• bytesWritten <integer> il numero di byte scritti
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> un riferimento all'input buffers.

Non è sicuro chiamare writev() più volte sullo stesso file senza attendere che la promise sia risolta (o rifiutata).

Su Linux, le scritture posizionali non funzionano quando il file viene aperto in modalità di aggiunta. Il kernel ignora l'argomento position e aggiunge sempre i dati alla fine del file.

filehandle[Symbol.asyncDispose]()

Aggiunto in: v20.4.0, v18.18.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Un alias per filehandle.close().

fsPromises.access(path[, mode])

Aggiunto in: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> Predefinito: fs.constants.F_OK
• Restituisce: <Promise> Soddisfa con undefined in caso di successo.

Verifica le autorizzazioni di un utente per il file o la directory specificata da path. L'argomento mode è un numero intero facoltativo che specifica i controlli di accessibilità da eseguire. mode dovrebbe essere il valore fs.constants.F_OK o una maschera composta dall'OR bit a bit di uno qualsiasi tra fs.constants.R_OK, fs.constants.W_OK e fs.constants.X_OK (ad es. fs.constants.W_OK | fs.constants.R_OK). Controlla Costanti di accesso ai file per i valori possibili di mode.

Se il controllo di accessibilità ha successo, la promise viene soddisfatta senza valore. Se uno qualsiasi dei controlli di accessibilità fallisce, la promise viene rifiutata con un oggetto <Error>. L'esempio seguente verifica se il file /etc/passwd può essere letto e scritto dal processo corrente.

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

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK)
  console.log('può accedere')
} catch {
  console.error('non può accedere')
}

Non è consigliato l'utilizzo di fsPromises.access() per verificare l'accessibilità di un file prima di chiamare fsPromises.open(). Ciò introduce una race condition, poiché altri processi potrebbero modificare lo stato del file tra le due chiamate. Invece, il codice utente dovrebbe aprire/leggere/scrivere il file direttamente e gestire l'errore generato se il file non è accessibile.

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

[Cronologia]

Versione	Modifiche
v21.1.0, v20.10.0	L'opzione flush è ora supportata.
v10.0.0	Aggiunto in: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> nomefile o <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Predefinito: 'utf8'
  • mode <integer> Predefinito: 0o666
  • flag <string> Consulta supporto dei flag del file system. Predefinito: 'a'.
  • flush <boolean> Se true, il descrittore di file sottostante viene svuotato prima della chiusura. Predefinito: false.

• Restituisce: <Promise> Soddisfa con undefined in caso di successo.

Aggiunge in modo asincrono dati a un file, creando il file se non esiste ancora. data può essere una stringa o un <Buffer>.

Se options è una stringa, allora specifica la encoding.

L'opzione mode influisce solo sul file appena creato. Consulta fs.open() per maggiori dettagli.

Il path può essere specificato come un <FileHandle> che è stato aperto per l'aggiunta (utilizzando fsPromises.open()).

fsPromises.chmod(path, mode)

Aggiunto in: v10.0.0

• path <stringa> | <Buffer> | <URL>
• mode <stringa> | <intero>
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Modifica i permessi di un file.

fsPromises.chown(path, uid, gid)

Aggiunto in: v10.0.0

• path <stringa> | <Buffer> | <URL>
• uid <intero>
• gid <intero>
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Modifica la proprietà di un file.

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

[Cronologia]

Versione	Modifiche
v14.0.0	L'argomento flags è stato modificato in mode ed è stata imposta una validazione del tipo più rigorosa.
v10.0.0	Aggiunto in: v10.0.0

• src <stringa> | <Buffer> | <URL> nome del file sorgente da copiare

• dest <stringa> | <Buffer> | <URL> nome del file di destinazione dell'operazione di copia

• mode <intero> Modificatori opzionali che specificano il comportamento dell'operazione di copia. È possibile creare una maschera composta dall'OR bit a bit di due o più valori (ad es. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) Predefinito: 0.

  • fs.constants.COPYFILE_EXCL: L'operazione di copia fallirà se dest esiste già.
  • fs.constants.COPYFILE_FICLONE: L'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma non supporta il copy-on-write, viene utilizzato un meccanismo di copia di fallback.
  • fs.constants.COPYFILE_FICLONE_FORCE: L'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma non supporta il copy-on-write, l'operazione fallirà.

• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Copia in modo asincrono src in dest. Per impostazione predefinita, dest viene sovrascritto se esiste già.

Non viene fornita alcuna garanzia sull'atomicità dell'operazione di copia. Se si verifica un errore dopo che il file di destinazione è stato aperto per la scrittura, verrà effettuato un tentativo di rimuovere la destinazione.

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

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('source.txt è stato copiato in destination.txt')
} catch {
  console.error('Impossibile copiare il file')
}

// Utilizzando COPYFILE_EXCL, l'operazione fallirà se destination.txt esiste.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('source.txt è stato copiato in destination.txt')
} catch {
  console.error('Impossibile copiare il file')
}

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

[Cronologia]

Versione	Modifiche
v22.3.0	Questa API non è più sperimentale.
v20.1.0, v18.17.0	Accetta un'opzione mode aggiuntiva per specificare il comportamento di copia come argomento mode di fs.copyFile().
v17.6.0, v16.15.0	Accetta un'opzione verbatimSymlinks aggiuntiva per specificare se eseguire la risoluzione del percorso per i link simbolici.
v16.7.0	Aggiunto in: v16.7.0

• src <string> | <URL> percorso di origine da copiare.

• dest <string> | <URL> percorso di destinazione in cui copiare.

• options <Object>

  • dereference <boolean> dereferenzia i link simbolici. Predefinito: false.
  • errorOnExist <boolean> quando force è false e la destinazione esiste, genera un errore. Predefinito: false.
  • filter <Function> Funzione per filtrare i file/directory copiati. Restituisce true per copiare l'elemento, false per ignorarlo. Quando si ignora una directory, anche tutto il suo contenuto verrà saltato. Può anche restituire una Promise che si risolve in true o false Predefinito: undefined.
  • src <string> percorso di origine da copiare.
  • dest <string> percorso di destinazione in cui copiare.
  • Restituisce: <boolean> | <Promise> Un valore che può essere convertito in boolean o una Promise che si risolve con tale valore.
  • force <boolean> sovrascrive il file o la directory esistente. L'operazione di copia ignorerà gli errori se si imposta questo valore su false e la destinazione esiste. Utilizzare l'opzione errorOnExist per modificare questo comportamento. Predefinito: true.
  • mode <integer> modificatori per l'operazione di copia. Predefinito: 0. Vedere il flag mode di fsPromises.copyFile().
  • preserveTimestamps <boolean> Quando è true, i timestamp di src verranno conservati. Predefinito: false.
  • recursive <boolean> copia le directory in modo ricorsivo Predefinito: false
  • verbatimSymlinks <boolean> Quando è true, la risoluzione del percorso per i link simbolici verrà saltata. Predefinito: false

• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Copia in modo asincrono l'intera struttura di directory da src a dest, incluse sottodirectory e file.

Quando si copia una directory in un'altra directory, i glob non sono supportati e il comportamento è simile a cp dir1/ dir2/.

fsPromises.glob(pattern[, options])

[Cronologia]

Versione	Modifiche
v22.2.0	Aggiunto il supporto per withFileTypes come opzione.
v22.0.0	Aggiunto in: v22.0.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> directory di lavoro corrente. Predefinito: process.cwd()
  • exclude <Function> Funzione per filtrare file/directory. Restituisce true per escludere l'elemento, false per includerlo. Predefinito: undefined.
  • withFileTypes <boolean> true se il glob dovrebbe restituire i percorsi come Dirent, false altrimenti. Predefinito: false.

• Restituisce: <AsyncIterator> Un AsyncIterator che restituisce i percorsi dei file che corrispondono al pattern.

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)

Deprecato da: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer>
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Cambia le autorizzazioni su un collegamento simbolico.

Questo metodo è implementato solo su macOS.

fsPromises.lchown(path, uid, gid)

[Cronologia]

Versione	Modifiche
v10.6.0	Questa API non è più deprecata.
v10.0.0	Aggiunta in: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Modifica la proprietà di un collegamento simbolico.

fsPromises.lutimes(path, atime, mtime)

Aggiunta in: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Modifica gli orari di accesso e modifica di un file nello stesso modo di fsPromises.utimes(), con la differenza che se il percorso si riferisce a un collegamento simbolico, il collegamento non viene dereferenziato: al contrario, vengono modificati i timestamp del collegamento simbolico stesso.

fsPromises.link(existingPath, newPath)

Aggiunto in: v10.0.0

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Crea un nuovo collegamento da existingPath a newPath. Per maggiori dettagli, vedere la documentazione POSIX link(2).

fsPromises.lstat(path[, options])

[Cronologia]

Versione	Modifiche
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti debbano essere bigint.
v10.0.0	Aggiunto in: v10.0.0

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

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito debbano essere bigint. Predefinito: false.

• Restituisce: <Promise> Si risolve con l'oggetto <fs.Stats> per il percorso di collegamento simbolico specificato path.

Equivalente a fsPromises.stat() a meno che path non si riferisca a un collegamento simbolico, nel qual caso viene eseguito lo stat sul collegamento stesso, non sul file a cui si riferisce. Per maggiori dettagli, consultare il documento POSIX lstat(2).

fsPromises.mkdir(path[, options])

Aggiunto in: v10.0.0

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

• options <Object> | <integer>

  • recursive <boolean> Predefinito: false
  • mode <string> | <integer> Non supportato su Windows. Predefinito: 0o777.

• Restituisce: <Promise> In caso di successo, si completa con undefined se recursive è false, o con il primo percorso di directory creato se recursive è true.

Crea una directory in modo asincrono.

L'argomento opzionale options può essere un numero intero che specifica mode (permessi e bit sticky), o un oggetto con una proprietà mode e una proprietà recursive che indica se le directory padre devono essere create. Chiamare fsPromises.mkdir() quando path è una directory esistente comporta un rifiuto solo quando recursive è false.

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(`creata ${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])

[Cronologia]

Versione	Modifiche
v20.6.0, v18.19.0	Il parametro prefix ora accetta buffer e URL.
v16.5.0, v14.18.0	Il parametro prefix ora accetta una stringa vuota.
v10.0.0	Aggiunto in: v10.0.0

• prefix <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • encoding <stringa> Predefinito: 'utf8'

• Restituisce: <Promise> Si risolve con una stringa contenente il percorso del file system della directory temporanea appena creata.

Crea una directory temporanea univoca. Un nome di directory univoco viene generato aggiungendo sei caratteri casuali alla fine del prefix fornito. A causa di incongruenze della piattaforma, evitare caratteri X finali in prefix. Alcune piattaforme, in particolare i BSD, possono restituire più di sei caratteri casuali e sostituire i caratteri X finali in prefix con caratteri casuali.

L'argomento opzionale options può essere una stringa che specifica una codifica o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare.

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

Il metodo fsPromises.mkdtemp() aggiungerà i sei caratteri selezionati casualmente direttamente alla stringa prefix. Ad esempio, data una directory /tmp, se l'intenzione è quella di creare una directory temporanea all'interno di /tmp, il prefix deve terminare con un separatore di percorso specifico della piattaforma (require('node:path').sep).

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

[Cronologia]

Versione	Modifiche
v11.1.0	L'argomento flags ora è opzionale e di default è impostato a 'r'.
v10.0.0	Aggiunto in: v10.0.0

• path <stringa> | <Buffer> | <URL>
• flags <stringa> | <numero> Vedi supporto per i flag del file system. Default: 'r'.
• mode <stringa> | <intero> Imposta la modalità del file (permessi e bit sticky) se il file viene creato. Default: 0o666 (leggibile e scrivibile)
• Restituisce: <Promise> Si risolve con un oggetto <FileHandle>.

Apre un <FileHandle>.

Fare riferimento alla documentazione POSIX open(2) per maggiori dettagli.

Alcuni caratteri (\< \> : " / \ | ? *) sono riservati in Windows come documentato in Denominazione di file, percorsi e spazi dei nomi. In NTFS, se il nome del file contiene un due punti, Node.js aprirà uno stream del file system, come descritto in questa pagina MSDN.

fsPromises.opendir(path[, options])

[Cronologia]

Versione	Modifiche
v20.1.0, v18.17.0	Aggiunta l'opzione recursive.
v13.1.0, v12.16.0	Introdotta l'opzione bufferSize.
v12.12.0	Aggiunto in: v12.12.0

• path <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • encoding <stringa> | <null> Default: 'utf8'
  • bufferSize <numero> Numero di voci di directory che vengono memorizzate internamente nel buffer durante la lettura dalla directory. Valori più alti portano a prestazioni migliori ma a un maggiore utilizzo di memoria. Default: 32
  • recursive <booleano> L'oggetto Dir risolto sarà un <AsyncIterable> contenente tutti i file e le directory secondarie. Default: false

• Restituisce: <Promise> Si risolve con un <fs.Dir>.

Apre in modo asincrono una directory per la scansione iterativa. Vedere la documentazione POSIX opendir(3) per maggiori dettagli.

Crea un <fs.Dir>, che contiene tutte le funzioni successive per la lettura e la pulizia della directory.

L'opzione encoding imposta la codifica per il path durante l'apertura della directory e le successive operazioni di lettura.

Esempio di utilizzo dell'iterazione asincrona:

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

Quando si utilizza l'iteratore asincrono, l'oggetto <fs.Dir> verrà automaticamente chiuso dopo l'uscita dell'iteratore.

fsPromises.readdir(path[, options])

[Cronologia]

Versione	Cambiamenti
v20.1.0, v18.17.0	Aggiunta l'opzione recursive.
v10.11.0	Aggiunta la nuova opzione withFileTypes.
v10.0.0	Aggiunta in: v10.0.0

• path <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • encoding <stringa> Predefinito: 'utf8'
  • withFileTypes <booleano> Predefinito: false
  • recursive <booleano> Se true, legge ricorsivamente il contenuto di una directory. In modalità ricorsiva, elencherà tutti i file, i sottofile e le directory. Predefinito: false.

• Restituisce: <Promise> Si risolve con un array dei nomi dei file nella directory escludendo '.' e '..'.

Legge il contenuto di una directory.

L'argomento opzionale options può essere una stringa che specifica una codifica, oppure un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per i nomi dei file. Se encoding è impostato su 'buffer', i nomi dei file restituiti saranno passati come oggetti <Buffer>.

Se options.withFileTypes è impostato su true, l'array restituito conterrà oggetti <fs.Dirent>.

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

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

fsPromises.readFile(path[, options])

[Cronologia]

Versione	Modifiche
v15.2.0, v14.17.0	L'argomento options può includere un AbortSignal per interrompere una richiesta readFile in corso.
v10.0.0	Aggiunto in: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> nomefile o FileHandle

• options <Object> | <string>

  • encoding <string> | <null> Predefinito: null
  • flag <string> Vedi supporto dei flag del file system. Predefinito: 'r'.
  • signal <AbortSignal> consente di interrompere una readFile in corso

• Restituisce: <Promise> Si risolve con i contenuti del file.

Legge in modo asincrono l'intero contenuto di un file.

Se non viene specificata alcuna codifica (usando options.encoding), i dati vengono restituiti come un oggetto <Buffer>. Altrimenti, i dati saranno una stringa.

Se options è una stringa, allora specifica la codifica.

Quando path è una directory, il comportamento di fsPromises.readFile() è specifico della piattaforma. Su macOS, Linux e Windows, la promise verrà rifiutata con un errore. Su FreeBSD, verrà restituita una rappresentazione del contenuto della directory.

Un esempio di lettura di un file package.json situato nella stessa directory del codice in esecuzione:

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

È possibile interrompere una readFile in corso usando un <AbortSignal>. Se una richiesta viene interrotta, la promise restituita viene rifiutata con un AbortError:

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

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

  // Interrompe la richiesta prima che la promise si risolva.
  controller.abort()

  await promise
} catch (err) {
  // Quando una richiesta viene interrotta - err è un AbortError
  console.error(err)
}

L'interruzione di una richiesta in corso non interrompe le singole richieste del sistema operativo, ma piuttosto il buffering interno che fs.readFile esegue.

Qualsiasi <FileHandle> specificato deve supportare la lettura.

fsPromises.readlink(path[, options])

Aggiunto in: v10.0.0

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'

• Restituisce: <Promise> Si completa con linkString in caso di successo.

Legge il contenuto del collegamento simbolico a cui fa riferimento path. Consulta la documentazione POSIX readlink(2) per maggiori dettagli. La promise viene completata con la linkString in caso di successo.

L'argomento opzionale options può essere una stringa che specifica una codifica, o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso del collegamento restituito. Se la encoding è impostata su 'buffer', il percorso del collegamento restituito verrà passato come oggetto <Buffer>.

fsPromises.realpath(path[, options])

Aggiunto in: v10.0.0

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'

• Restituisce: <Promise> Si completa con il percorso risolto in caso di successo.

Determina la posizione effettiva di path utilizzando la stessa semantica della funzione fs.realpath.native().

Sono supportati solo i percorsi che possono essere convertiti in stringhe UTF8.

L'argomento opzionale options può essere una stringa che specifica una codifica, o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso. Se la encoding è impostata su 'buffer', il percorso restituito verrà passato come oggetto <Buffer>.

Su Linux, quando Node.js è collegato a musl libc, il file system procfs deve essere montato su /proc affinché questa funzione funzioni. Glibc non ha questa restrizione.

fsPromises.rename(oldPath, newPath)

Aggiunto in: v10.0.0

• oldPath <stringa> | <Buffer> | <URL>
• newPath <stringa> | <Buffer> | <URL>
• Restituisce: <Promise> Si completa con undefined in caso di successo.

Rinomina oldPath in newPath.

fsPromises.rmdir(path[, options])

[Cronologia]

Versione	Modifiche
v16.0.0	L'utilizzo di fsPromises.rmdir(path, { recursive: true }) su un path che è un file non è più consentito e genera un errore ENOENT su Windows e un errore ENOTDIR su POSIX.
v16.0.0	L'utilizzo di fsPromises.rmdir(path, { recursive: true }) su un path che non esiste non è più consentito e genera un errore ENOENT.
v16.0.0	L'opzione recursive è obsoleta, il suo utilizzo attiva un avviso di deprecazione.
v14.14.0	L'opzione recursive è obsoleta, utilizzare fsPromises.rm invece.
v13.3.0, v12.16.0	L'opzione maxBusyTries è stata rinominata in maxRetries e il suo valore predefinito è 0. L'opzione emfileWait è stata rimossa e gli errori EMFILE utilizzano la stessa logica di riprova degli altri errori. L'opzione retryDelay è ora supportata. Gli errori ENFILE ora vengono ritentati.
v12.10.0	Le opzioni recursive, maxBusyTries e emfileWait sono ora supportate.
v10.0.0	Aggiunto in: v10.0.0

• path <stringa> | <Buffer> | <URL>
• options <Oggetto>
  • maxRetries <numero intero> Se viene rilevato un errore EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js riprova l'operazione con un'attesa di backoff lineare di retryDelay millisecondi più lunga ad ogni tentativo. Questa opzione rappresenta il numero di tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 0.
  • recursive <booleano> Se true, esegue una rimozione ricorsiva della directory. In modalità ricorsiva, le operazioni vengono ritentate in caso di errore. Predefinito: false. Obsoleto.
  • retryDelay <numero intero> La quantità di tempo in millisecondi da attendere tra i tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 100.
• Restituisce: <Promise> Si completa con undefined in caso di successo.

Rimuove la directory identificata da path.

L'utilizzo di fsPromises.rmdir() su un file (non una directory) fa sì che la promise venga rifiutata con un errore ENOENT su Windows e un errore ENOTDIR su POSIX.

Per ottenere un comportamento simile al comando Unix rm -rf, utilizzare fsPromises.rm() con le opzioni { recursive: true, force: true }.

fsPromises.rm(path[, options])

Aggiunto in: v14.14.0

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

• options <Object>

  • force <boolean> Quando true, le eccezioni verranno ignorate se path non esiste. Predefinito: false.
  • maxRetries <integer> Se si verifica un errore EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js ritenterà l'operazione con un'attesa lineare di backoff di retryDelay millisecondi in più ad ogni tentativo. Questa opzione rappresenta il numero di tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 0.
  • recursive <boolean> Se true, esegue una rimozione ricorsiva della directory. In modalità ricorsiva le operazioni vengono ritentate in caso di errore. Predefinito: false.
  • retryDelay <integer> La quantità di tempo in millisecondi da attendere tra i tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 100.

• Restituisce: <Promise> Adempie con undefined in caso di successo.

Rimuove file e directory (modellato sull'utility POSIX standard rm).

fsPromises.stat(path[, options])

[Cronologia]

Versione	Cambiamenti
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti devono essere bigint.
v10.0.0	Aggiunto in: v10.0.0

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

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.

• Restituisce: <Promise> Adempie con l'oggetto <fs.Stats> per il path specificato.

fsPromises.statfs(path[, options])

Aggiunto in: v19.6.0, v18.15.0

• path <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • bigint <booleano> Indica se i valori numerici nell'oggetto <fs.StatFs> restituito devono essere bigint. Predefinito: false.

• Restituisce: <Promise> Adempie con l'oggetto <fs.StatFs> per il path dato.

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

[Cronologia]

Versione	Modifiche
v19.0.0	Se l'argomento type è null o omesso, Node.js rileva automaticamente il tipo di target e seleziona automaticamente dir o file.
v10.0.0	Aggiunto in: v10.0.0

• target <stringa> | <Buffer> | <URL>
• path <stringa> | <Buffer> | <URL>
• type <stringa> | <null> Predefinito: null
• Restituisce: <Promise> Adempie con undefined in caso di successo.

Crea un collegamento simbolico.

L'argomento type viene utilizzato solo sulle piattaforme Windows e può essere 'dir', 'file' o 'junction'. Se l'argomento type è null, Node.js rileverà automaticamente il tipo di target e utilizzerà 'file' o 'dir'. Se target non esiste, verrà utilizzato 'file'. I junction point di Windows richiedono che il percorso di destinazione sia assoluto. Quando si utilizza 'junction', l'argomento target verrà normalizzato automaticamente in un percorso assoluto. I junction point sui volumi NTFS possono puntare solo alle directory.

fsPromises.truncate(path[, len])

Aggiunto in: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> Predefinito: 0
• Restituisce: <Promise> Si completa con undefined in caso di successo.

Tronca (accorcia o estende la lunghezza) il contenuto in path a len byte.

fsPromises.unlink(path)

Aggiunto in: v10.0.0

• path <string> | <Buffer> | <URL>
• Restituisce: <Promise> Si completa con undefined in caso di successo.

Se path si riferisce a un collegamento simbolico, il collegamento viene rimosso senza interessare il file o la directory a cui tale collegamento si riferisce. Se il path si riferisce a un percorso file che non è un collegamento simbolico, il file viene eliminato. Vedi la documentazione POSIX unlink(2) per maggiori dettagli.

fsPromises.utimes(path, atime, mtime)

Aggiunto in: v10.0.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Restituisce: <Promise> Si completa con undefined in caso di successo.

Cambia i timestamp del file system dell'oggetto a cui fa riferimento path.

Gli argomenti atime e mtime seguono queste regole:

• I valori possono essere numeri che rappresentano il tempo Unix epoch, Date o una stringa numerica come '123456789.0'.
• Se il valore non può essere convertito in un numero, o è NaN, Infinity o -Infinity, verrà generato un Error.

fsPromises.watch(filename[, options])

Aggiunto in: v15.9.0, v14.18.0

• filename <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • persistent <boolean> Indica se il processo deve continuare a essere eseguito finché i file sono monitorati. Predefinito: true.
  • recursive <boolean> Indica se tutte le sottodirectory devono essere monitorate o solo la directory corrente. Ciò si applica quando viene specificata una directory e solo su piattaforme supportate (vedere avvertenze). Predefinito: false.
  • encoding <stringa> Specifica la codifica dei caratteri da utilizzare per il nome file passato al listener. Predefinito: 'utf8'.
  • signal <AbortSignal> Un <AbortSignal> utilizzato per segnalare quando il watcher deve interrompersi.

• Restituisce: <AsyncIterator> di oggetti con le proprietà:

  • eventType <stringa> Il tipo di cambiamento
  • filename <stringa> | <Buffer> | <null> Il nome del file modificato.

Restituisce un iteratore asincrono che osserva le modifiche su filename, dove filename è un file o una directory.

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

Sulla maggior parte delle piattaforme, 'rename' viene emesso ogni volta che un nome file appare o scompare nella directory.

Tutte le avvertenze per fs.watch() si applicano anche a fsPromises.watch().

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

[Cronologia]

Versione	Modifiche
v21.0.0, v20.10.0	L'opzione flush è ora supportata.
v15.14.0, v14.18.0	L'argomento data supporta AsyncIterable, Iterable e Stream.
v15.2.0, v14.17.0	L'argomento options può includere un AbortSignal per interrompere una richiesta writeFile in corso.
v14.0.0	Il parametro data non forzerà più l'input non supportato a stringhe.
v10.0.0	Aggiunto in: v10.0.0

• file <string> | <Buffer> | <URL> | <FileHandle> nomefile o FileHandle

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

• options <Object> | <string>

  • encoding <string> | <null> Predefinito: 'utf8'
  • mode <integer> Predefinito: 0o666
  • flag <string> Vedere supporto dei flag del file system. Predefinito: 'w'.
  • flush <boolean> Se tutti i dati vengono scritti correttamente nel file e flush è true, viene utilizzato filehandle.sync() per scaricare i dati. Predefinito: false.
  • signal <AbortSignal> consente di interrompere un writeFile in corso

• Restituisce: <Promise> Si risolve con undefined in caso di successo.

Scrive in modo asincrono i dati in un file, sostituendo il file se esiste già. data può essere una stringa, un buffer, un oggetto <AsyncIterable> o un oggetto <Iterable>.

L'opzione encoding viene ignorata se data è un buffer.

Se options è una stringa, specifica la codifica.

L'opzione mode interessa solo il file appena creato. Per ulteriori dettagli, vedere fs.open().

Qualsiasi <FileHandle> specificato deve supportare la scrittura.

Non è sicuro utilizzare fsPromises.writeFile() più volte sullo stesso file senza attendere che la promise sia stata risolta.

Analogamente a fsPromises.readFile - fsPromises.writeFile è un metodo pratico che esegue internamente più chiamate write per scrivere il buffer passato. Per il codice sensibile alle prestazioni, considerare l'utilizzo di fs.createWriteStream() o filehandle.createWriteStream().

È possibile utilizzare un <AbortSignal> per annullare un fsPromises.writeFile(). L'annullamento è "il meglio possibile" ed è probabile che una certa quantità di dati venga ancora scritta.

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

  // Annulla la richiesta prima che la promise venga risolta.
  controller.abort()

  await promise
} catch (err) {
  // Quando una richiesta viene annullata - err è un AbortError
  console.error(err)
}

L'annullamento di una richiesta in corso non annulla le singole richieste del sistema operativo, ma piuttosto il buffering interno eseguito da fs.writeFile.

fsPromises.constants

Aggiunto in: v18.4.0, v16.17.0

• <Object>

Restituisce un oggetto contenente costanti di uso comune per le operazioni del file system. L'oggetto è lo stesso di fs.constants. Vedi Costanti FS per maggiori dettagli.

API Callback

Le API callback eseguono tutte le operazioni in modo asincrono, senza bloccare il ciclo di eventi, quindi invocano una funzione di callback al completamento o in caso di errore.

Le API callback utilizzano il threadpool Node.js sottostante per eseguire le operazioni del file system al di fuori del thread del ciclo di eventi. Queste operazioni non sono sincronizzate o threadsafe. È necessario prestare attenzione quando si eseguono più modifiche simultanee sullo stesso file o potrebbe verificarsi un danneggiamento dei dati.

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

[Cronologia]

Versione	Cambiamenti
v20.8.0	Le costanti fs.F_OK, fs.R_OK, fs.W_OK e fs.X_OK che erano presenti direttamente su fs sono deprecate.
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL utilizzando il protocollo file:.
v6.3.0	Le costanti come fs.R_OK, ecc. che erano presenti direttamente su fs sono state spostate in fs.constants come deprecazione soft. Pertanto, per Node.js \< v6.3.0 utilizzare fs per accedere a tali costanti, o fare qualcosa come `(fs.constants
v0.11.15	Aggiunto in: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> Predefinito: fs.constants.F_OK
• callback <Function>
  • err <Error>

Verifica le autorizzazioni di un utente per il file o la directory specificata da path. L'argomento mode è un numero intero opzionale che specifica le verifiche di accessibilità da eseguire. mode dovrebbe essere il valore fs.constants.F_OK o una maschera costituita dall'OR bit a bit di qualsiasi tra fs.constants.R_OK, fs.constants.W_OK e fs.constants.X_OK (ad es. fs.constants.W_OK | fs.constants.R_OK). Controlla Costanti di accesso ai file per i possibili valori di mode.

L'argomento finale, callback, è una funzione di callback che viene invocata con un possibile argomento di errore. Se una qualsiasi delle verifiche di accessibilità fallisce, l'argomento di errore sarà un oggetto Error. Gli esempi seguenti verificano se package.json esiste e se è leggibile o scrivibile.

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

const file = 'package.json'

// Verifica se il file esiste nella directory corrente.
access(file, constants.F_OK, err => {
  console.log(`${file} ${err ? 'non esiste' : 'esiste'}`)
})

// Verifica se il file è leggibile.
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? 'non è leggibile' : 'è leggibile'}`)
})

// Verifica se il file è scrivibile.
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? 'non è scrivibile' : 'è scrivibile'}`)
})

// Verifica se il file è leggibile e scrivibile.
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? 'non è' : 'è'} leggibile e scrivibile`)
})

Non utilizzare fs.access() per verificare l'accessibilità di un file prima di chiamare fs.open(), fs.readFile() o fs.writeFile(). Ciò introduce una condizione di race, poiché altri processi potrebbero modificare lo stato del file tra le due chiamate. Invece, il codice utente dovrebbe aprire/leggere/scrivere direttamente il file e gestire l'errore generato se il file non è accessibile.

Scrittura (NON CONSIGLIATO)

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

access('myfile', err => {
  if (!err) {
    console.error('myfile esiste già')
    return
  }

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

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

Scrittura (CONSIGLIATO)

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

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

    throw err
  }

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

Lettura (NON CONSIGLIATO)

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

    throw err
  }

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

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

Lettura (CONSIGLIATO)

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

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

    throw err
  }

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

Gli esempi "non consigliati" sopra verificano l'accessibilità e quindi utilizzano il file; gli esempi "consigliati" sono migliori perché utilizzano il file direttamente e gestiscono l'errore, se presente.

In generale, verifica l'accessibilità di un file solo se il file non verrà utilizzato direttamente, ad esempio quando la sua accessibilità è un segnale proveniente da un altro processo.

Su Windows, le policy di controllo degli accessi (ACL) su una directory possono limitare l'accesso a un file o una directory. La funzione fs.access(), tuttavia, non verifica l'ACL e pertanto potrebbe segnalare che un percorso è accessibile anche se l'ACL impedisce all'utente di leggere o scrivervi.

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

[Cronologia]

Versione	Modifiche
v21.1.0, v20.10.0	L'opzione flush è ora supportata.
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più facoltativo. Non passarlo genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più facoltativo. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v7.0.0	L'oggetto options passato non verrà mai modificato.
v5.0.0	Il parametro file può essere ora un descrittore di file.
v0.6.7	Aggiunto in: v0.6.7

• path <string> | <Buffer> | <URL> | <number> nome del file o descrittore del file

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Predefinito: 'utf8'
  • mode <integer> Predefinito: 0o666
  • flag <string> Vedere supporto dei flag del file system. Predefinito: 'a'.
  • flush <boolean> Se true, il descrittore di file sottostante viene svuotato prima di chiuderlo. Predefinito: false.

• callback <Function>

  • err <Error>

Aggiunge dati in modo asincrono a un file, creando il file se non esiste ancora. data può essere una stringa o un <Buffer>.

L'opzione mode influisce solo sul file appena creato. Vedere fs.open() per maggiori dettagli.

import { appendFile } from 'node:fs'

appendFile('message.txt', 'dati da aggiungere', err => {
  if (err) throw err
  console.log('I "dati da aggiungere" sono stati aggiunti al file!')
})

Se options è una stringa, specifica la codifica:

import { appendFile } from 'node:fs'

appendFile('message.txt', 'dati da aggiungere', 'utf8', callback)

Il path può essere specificato come un descrittore di file numerico che è stato aperto per l'aggiunta (usando fs.open() o fs.openSync()). Il descrittore di file non verrà chiuso automaticamente.

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, 'dati da aggiungere', 'utf8', err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

fs.chmod(path, mode, callback)

[Cronologia]

Versione	Cambiamenti
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Il mancato passaggio di esso genererà un TypeError in fase di runtime.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Il mancato passaggio di esso emetterà un avviso di deprecazione con id DEP0013.
v0.1.30	Aggiunto in: v0.1.30

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

Modifica in modo asincrono le autorizzazioni di un file. Non vengono forniti altri argomenti alla callback di completamento oltre a una possibile eccezione.

Vedere la documentazione POSIX chmod(2) per maggiori dettagli.

import { chmod } from 'node:fs'

chmod('my_file.txt', 0o775, err => {
  if (err) throw err
  console.log('Le autorizzazioni per il file "my_file.txt" sono state modificate!')
})

Modalità file

L'argomento mode utilizzato sia nel metodo fs.chmod() sia nel metodo fs.chmodSync() è una maschera di bit numerica creata utilizzando un OR logico delle seguenti costanti:

Costante	Ottale	Descrizione
fs.constants.S_IRUSR	0o400	lettura da parte del proprietario
fs.constants.S_IWUSR	0o200	scrittura da parte del proprietario
fs.constants.S_IXUSR	0o100	esecuzione/ricerca da parte del proprietario
fs.constants.S_IRGRP	0o40	lettura da parte del gruppo
fs.constants.S_IWGRP	0o20	scrittura da parte del gruppo
fs.constants.S_IXGRP	0o10	esecuzione/ricerca da parte del gruppo
fs.constants.S_IROTH	0o4	lettura da parte di altri
fs.constants.S_IWOTH	0o2	scrittura da parte di altri
fs.constants.S_IXOTH	0o1	esecuzione/ricerca da parte di altri

Un metodo più semplice per costruire la mode consiste nell'utilizzare una sequenza di tre cifre ottali (es. 765). La cifra più a sinistra (7 nell'esempio), specifica le autorizzazioni per il proprietario del file. La cifra centrale (6 nell'esempio), specifica le autorizzazioni per il gruppo. La cifra più a destra (5 nell'esempio), specifica le autorizzazioni per gli altri.

Numero	Descrizione
7	lettura, scrittura ed esecuzione
6	lettura e scrittura
5	lettura ed esecuzione
4	solo lettura
3	scrittura ed esecuzione
2	solo scrittura
1	solo esecuzione
0	nessuna autorizzazione

Ad esempio, il valore ottale 0o765 significa:

• Il proprietario può leggere, scrivere ed eseguire il file.
• Il gruppo può leggere e scrivere il file.
• Altri possono leggere ed eseguire il file.

Quando si utilizzano numeri raw laddove sono previste le modalità file, qualsiasi valore maggiore di 0o777 può comportare comportamenti specifici della piattaforma che non sono supportati per funzionare in modo coerente. Pertanto, costanti come S_ISVTX, S_ISGID o S_ISUID non sono esposte in fs.constants.

Avvertenze: su Windows è possibile modificare solo l'autorizzazione di scrittura e la distinzione tra le autorizzazioni di gruppo, proprietario o altri non è implementata.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di runtime.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v0.1.97	Aggiunto in: v0.1.97

• path <stringa> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Errore>

Modifica in modo asincrono il proprietario e il gruppo di un file. Nessun argomento, ad eccezione di una possibile eccezione, viene fornito al callback di completamento.

Vedere la documentazione POSIX chown(2) per maggiori dettagli.

fs.close(fd[, callback])

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v15.9.0, v14.17.0	Un callback predefinito viene ora utilizzato se non ne viene fornito uno.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di runtime.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v0.0.2	Aggiunto in: v0.0.2

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

Chiude il descrittore di file. Nessun argomento, ad eccezione di una possibile eccezione, viene fornito al callback di completamento.

Chiamare fs.close() su qualsiasi descrittore di file (fd) attualmente in uso tramite qualsiasi altra operazione fs può portare a un comportamento indefinito.

Vedere la documentazione POSIX close(2) per maggiori dettagli.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v14.0.0	L'argomento flags è stato cambiato in mode ed è stata imposta una validazione del tipo più rigorosa.
v8.5.0	Aggiunto in: v8.5.0

• src <string> | <Buffer> | <URL> nome file di origine da copiare
• dest <string> | <Buffer> | <URL> nome file di destinazione dell'operazione di copia
• mode <integer> modificatori per l'operazione di copia. Predefinito: 0.
• callback <Function>
  • err <Error>

Copia asincronamente src in dest. Per impostazione predefinita, dest viene sovrascritto se esiste già. Alla funzione di callback non vengono forniti argomenti diversi da una possibile eccezione. Node.js non fornisce alcuna garanzia sull'atomicità dell'operazione di copia. Se si verifica un errore dopo che il file di destinazione è stato aperto per la scrittura, Node.js tenterà di rimuovere la destinazione.

mode è un numero intero facoltativo che specifica il comportamento dell'operazione di copia. È possibile creare una maschera costituita dall'OR bit a bit di due o più valori (ad esempio fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: L'operazione di copia fallirà se dest esiste già.
• fs.constants.COPYFILE_FICLONE: L'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma non supporta copy-on-write, viene utilizzato un meccanismo di copia di fallback.
• fs.constants.COPYFILE_FICLONE_FORCE: L'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma non supporta copy-on-write, l'operazione fallirà.

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

function callback(err) {
  if (err) throw err
  console.log('source.txt è stato copiato in destination.txt')
}

// destination.txt verrà creato o sovrascritto per impostazione predefinita.
copyFile('source.txt', 'destination.txt', callback)

// Utilizzando COPYFILE_EXCL, l'operazione fallirà se destination.txt esiste.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback)

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

[Cronologia]

Versione	Modifiche
v22.3.0	Questa API non è più sperimentale.
v20.1.0, v18.17.0	Accetta un'opzione mode aggiuntiva per specificare il comportamento di copia come argomento mode di fs.copyFile().
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v17.6.0, v16.15.0	Accetta un'opzione verbatimSymlinks aggiuntiva per specificare se eseguire la risoluzione del percorso per i collegamenti simbolici.
v16.7.0	Aggiunto in: v16.7.0

• src <stringa> | <URL> percorso di origine da copiare.
• dest <stringa> | <URL> percorso di destinazione in cui copiare.
• options <Oggetto>
  • dereference <booleano> dereferenzia i collegamenti simbolici. Predefinito: false.
  • errorOnExist <booleano> quando force è false e la destinazione esiste, genera un errore. Predefinito: false.
  • filter <Funzione> Funzione per filtrare file/directory copiati. Restituisce true per copiare l'elemento, false per ignorarlo. Quando si ignora una directory, anche tutto il suo contenuto verrà saltato. Può anche restituire una Promise che si risolve in true o false Predefinito: undefined.
  • src <stringa> percorso di origine da copiare.
  • dest <stringa> percorso di destinazione in cui copiare.
  • Restituisce: <booleano> | <Promise> Un valore coercibile in booleano o una Promise che si completa con tale valore.
  • force <booleano> sovrascrive file o directory esistenti. L'operazione di copia ignorerà gli errori se lo imposti su false e la destinazione esiste. Utilizza l'opzione errorOnExist per modificare questo comportamento. Predefinito: true.
  • mode <intero> modificatori per l'operazione di copia. Predefinito: 0. Consulta il flag mode di fs.copyFile().
  • preserveTimestamps <booleano> Quando true i timestamp da src verranno conservati. Predefinito: false.
  • recursive <booleano> copia le directory in modo ricorsivo Predefinito: false
  • verbatimSymlinks <booleano> Quando true, la risoluzione del percorso per i collegamenti simbolici verrà saltata. Predefinito: false
• callback <Funzione>
  • err <Errore>

Copia in modo asincrono l'intera struttura della directory da src a dest, incluse sottodirectory e file.

Quando si copia una directory in un'altra directory, i glob non sono supportati e il comportamento è simile a cp dir1/ dir2/.

fs.createReadStream(path[, options])

[Cronologia]

Versione	Cambiamenti
v16.10.0	L'opzione fs non necessita del metodo open se è stato fornito un fd.
v16.10.0	L'opzione fs non necessita del metodo close se autoClose è false.
v15.5.0	Aggiunto il supporto per AbortSignal.
v15.4.0	L'opzione fd accetta argomenti FileHandle.
v14.0.0	Cambiato il valore predefinito di emitClose a true.
v13.6.0, v12.17.0	Le opzioni fs consentono di sovrascrivere l'implementazione fs utilizzata.
v12.10.0	Abilitata l'opzione emitClose.
v11.0.0	Imposte nuove restrizioni su start e end, lanciando errori più appropriati nei casi in cui non possiamo gestire ragionevolmente i valori di input.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	L'oggetto options passato non sarà mai modificato.
v2.3.0	L'oggetto options passato può ora essere una stringa.
v0.1.31	Aggiunto in: v0.1.31

• path <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • flags <stringa> Vedi supporto dei flags del file system. Predefinito: 'r'.
  • encoding <stringa> Predefinito: null
  • fd <numero intero> | <FileHandle> Predefinito: null
  • mode <numero intero> Predefinito: 0o666
  • autoClose <booleano> Predefinito: true
  • emitClose <booleano> Predefinito: true
  • start <numero intero>
  • end <numero intero> Predefinito: Infinity
  • highWaterMark <numero intero> Predefinito: 64 * 1024
  • fs <Oggetto> | <null> Predefinito: null
  • signal <AbortSignal> | <null> Predefinito: null

• Restituisce: <fs.ReadStream>

options può includere valori start e end per leggere un intervallo di byte dal file anziché l'intero file. Sia start che end sono inclusivi e iniziano a contare da 0, i valori consentiti sono nell'intervallo [0, Number.MAX_SAFE_INTEGER]. Se fd è specificato e start è omesso o undefined, fs.createReadStream() legge in sequenza dalla posizione corrente del file. La encoding può essere una qualsiasi di quelle accettate da <Buffer>.

Se fd è specificato, ReadStream ignorerà l'argomento path e utilizzerà il descrittore di file specificato. Ciò significa che non verrà emesso alcun evento 'open'. fd dovrebbe essere bloccante; i fd non bloccanti dovrebbero essere passati a <net.Socket>.

Se fd punta a un dispositivo a caratteri che supporta solo letture bloccanti (come tastiera o scheda audio), le operazioni di lettura non terminano finché i dati non sono disponibili. Ciò può impedire al processo di terminare e allo stream di chiudersi naturalmente.

Per impostazione predefinita, lo stream emetterà un evento 'close' dopo essere stato distrutto. Imposta l'opzione emitClose su false per modificare questo comportamento.

Fornendo l'opzione fs, è possibile sovrascrivere le corrispondenti implementazioni fs per open, read e close. Quando si fornisce l'opzione fs, è richiesto un override per read. Se non viene fornito alcun fd, è richiesto anche un override per open. Se autoClose è true, è richiesto anche un override per close.

import { createReadStream } from 'node:fs'

// Crea uno stream da un dispositivo a caratteri.
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
  stream.close() // Questo potrebbe non chiudere lo stream.
  // Contrassegnare artificialmente la fine dello stream, come se la risorsa sottostante avesse
  // indicato la fine del file di per sé, consente allo stream di chiudersi.
  // Questo non annulla le operazioni di lettura in sospeso e, se presente una tale
  // operazione, il processo potrebbe non essere ancora in grado di terminare correttamente
  // finché non termina.
  stream.push(null)
  stream.read(0)
}, 100)

Se autoClose è false, il descrittore di file non verrà chiuso, anche in caso di errore. È responsabilità dell'applicazione chiuderlo e assicurarsi che non vi siano perdite di descrittori di file. Se autoClose è impostato su true (comportamento predefinito), al verificarsi di 'error' o 'end' il descrittore di file verrà chiuso automaticamente.

mode imposta la modalità del file (permessi e bit di sticky), ma solo se il file è stato creato.

Un esempio per leggere gli ultimi 10 byte di un file lungo 100 byte:

import { createReadStream } from 'node:fs'

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

Se options è una stringa, specifica la codifica.

fs.createWriteStream(path[, options])

[Cronologia]

Versione	Modifiche
v21.0.0, v20.10.0	L'opzione flush è ora supportata.
v16.10.0	L'opzione fs non ha bisogno del metodo open se è stato fornito un fd.
v16.10.0	L'opzione fs non ha bisogno del metodo close se autoClose è false.
v15.5.0	Aggiunto il supporto per AbortSignal.
v15.4.0	L'opzione fd accetta argomenti FileHandle.
v14.0.0	Cambiato il valore predefinito di emitClose a true.
v13.6.0, v12.17.0	Le opzioni fs consentono di sovrascrivere l'implementazione fs utilizzata.
v12.10.0	Abilitata l'opzione emitClose.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	L'oggetto options passato non verrà mai modificato.
v5.5.0	L'opzione autoClose è ora supportata.
v2.3.0	L'oggetto options passato può essere ora una stringa.
v0.1.31	Aggiunto in: v0.1.31

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

• options <string> | <Object>

  • flags <string> Vedi supporto di flags del file system. Predefinito: 'w'.
  • encoding <string> Predefinito: 'utf8'
  • fd <integer> | <FileHandle> Predefinito: null
  • mode <integer> Predefinito: 0o666
  • autoClose <boolean> Predefinito: true
  • emitClose <boolean> Predefinito: true
  • start <integer>
  • fs <Object> | <null> Predefinito: null
  • signal <AbortSignal> | <null> Predefinito: null
  • highWaterMark <number> Predefinito: 16384
  • flush <boolean> Se true, il descrittore di file sottostante viene scaricato prima di chiuderlo. Predefinito: false.

• Restituisce: <fs.WriteStream>

options può includere anche un'opzione start per consentire la scrittura di dati in una posizione successiva all'inizio del file, i valori consentiti sono nell'intervallo [0, Number.MAX_SAFE_INTEGER]. La modifica di un file anziché la sua sostituzione può richiedere che l'opzione flags sia impostata su r+ anziché sul valore predefinito w. La encoding può essere una qualsiasi di quelle accettate da <Buffer>.

Se autoClose è impostato su true (comportamento predefinito) su 'error' o 'finish', il descrittore di file verrà chiuso automaticamente. Se autoClose è false, il descrittore di file non verrà chiuso, anche se si verifica un errore. È responsabilità dell'applicazione chiuderlo e assicurarsi che non ci siano perdite del descrittore di file.

Per impostazione predefinita, lo stream emetterà un evento 'close' dopo che è stato distrutto. Imposta l'opzione emitClose su false per modificare questo comportamento.

Fornendo l'opzione fs è possibile sovrascrivere le corrispondenti implementazioni fs per open, write, writev e close. La sovrascrittura di write() senza writev() può ridurre le prestazioni in quanto alcune ottimizzazioni (_writev()) saranno disabilitate. Quando si fornisce l'opzione fs, sono necessarie le sovrascritture per almeno uno tra write e writev. Se non viene fornita l'opzione fd, è richiesta anche una sovrascrittura per open. Se autoClose è true, è richiesta anche una sovrascrittura per close.

Come <fs.ReadStream>, se fd è specificato, <fs.WriteStream> ignorerà l'argomento path e utilizzerà il descrittore di file specificato. Ciò significa che non verrà emesso alcun evento 'open'. fd deve essere bloccante; i fd non bloccanti devono essere passati a <net.Socket>.

Se options è una stringa, specifica la codifica.

fs.exists(path, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v1.0.0	Deprecato da: v1.0.0
v0.0.2	Aggiunto in: v0.0.2

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare invece fs.stat() o fs.access().

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

Verifica se l'elemento al path indicato esiste controllando con il file system. Quindi chiama l'argomento callback con true o false:

import { exists } from 'node:fs'

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

I parametri di questa callback non sono coerenti con le altre callback di Node.js. Normalmente, il primo parametro di una callback di Node.js è un parametro err, facoltativamente seguito da altri parametri. La callback fs.exists() ha un solo parametro booleano. Questo è uno dei motivi per cui si consiglia fs.access() invece di fs.exists().

Se path è un collegamento simbolico, viene seguito. Pertanto, se path esiste ma punta a un elemento inesistente, la callback riceverà il valore false.

Non è consigliabile utilizzare fs.exists() per verificare l'esistenza di un file prima di chiamare fs.open(), fs.readFile() o fs.writeFile(). Ciò introduce una race condition, poiché altri processi potrebbero modificare lo stato del file tra le due chiamate. Invece, il codice utente deve aprire/leggere/scrivere il file direttamente e gestire l'errore generato se il file non esiste.

scrittura (NON CONSIGLIATO)

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

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

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

scrittura (CONSIGLIATO)

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

    throw err
  }

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

lettura (NON CONSIGLIATO)

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

lettura (CONSIGLIATO)

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

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

    throw err
  }

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

Gli esempi "non consigliati" sopra verificano l'esistenza e quindi utilizzano il file; gli esempi "consigliati" sono migliori perché utilizzano il file direttamente e gestiscono l'errore, se presente.

In generale, verifica l'esistenza di un file solo se il file non verrà utilizzato direttamente, ad esempio quando la sua esistenza è un segnale da un altro processo.

fs.fchmod(fd, mode, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Il non passarlo genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più opzionale. Il non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.4.7	Aggiunto in: v0.4.7

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

Imposta le autorizzazioni sul file. Nessun argomento oltre a una possibile eccezione viene fornito al callback di completamento.

Vedi la documentazione POSIX fchmod(2) per maggiori dettagli.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Il non passarlo genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più opzionale. Il non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.4.7	Aggiunto in: v0.4.7

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

Imposta il proprietario del file. Nessun argomento oltre a una possibile eccezione viene fornito al callback di completamento.

Vedi la documentazione POSIX fchown(2) per maggiori dettagli.

fs.fdatasync(fd, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più facoltativo. Il mancato passaggio genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più facoltativo. Il mancato passaggio genererà un avviso di deprecazione con ID DEP0013.
v0.1.96	Aggiunto in: v0.1.96

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

Forza tutte le operazioni I/O attualmente in coda associate al file allo stato di completamento I/O sincronizzato del sistema operativo. Fare riferimento alla documentazione POSIX fdatasync(2) per i dettagli. Nessun argomento diverso da una possibile eccezione viene fornito al callback di completamento.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti devono essere bigint.
v10.0.0	Il parametro callback non è più facoltativo. Il mancato passaggio genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più facoltativo. Il mancato passaggio genererà un avviso di deprecazione con ID DEP0013.
v0.1.95	Aggiunto in: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.

• callback <Function>

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

Richiama il callback con <fs.Stats> per il descrittore di file.

Vedere la documentazione POSIX fstat(2) per maggiori dettagli.

fs.fsync(fd, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più facoltativo. Non passarlo genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più facoltativo. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.1.96	Aggiunto in: v0.1.96

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

Richiede che tutti i dati per il descrittore di file aperto vengano scaricati sul dispositivo di archiviazione. L'implementazione specifica è specifica del sistema operativo e del dispositivo. Fare riferimento alla documentazione POSIX fsync(2) per maggiori dettagli. Alla callback di completamento non vengono forniti argomenti diversi da una possibile eccezione.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più facoltativo. Non passarlo genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più facoltativo. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.8.6	Aggiunto in: v0.8.6

• fd <integer>
• len <integer> Predefinito: 0
• callback <Function>
  • err <Error>

Tronca il descrittore di file. Alla callback di completamento non vengono forniti argomenti diversi da una possibile eccezione.

Vedere la documentazione POSIX ftruncate(2) per maggiori dettagli.

Se il file a cui si fa riferimento tramite il descrittore di file era più grande di len byte, nel file verranno mantenuti solo i primi len byte.

Ad esempio, il seguente programma conserva solo i primi quattro byte del file:

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

Se il file in precedenza era più corto di len byte, viene esteso e la parte estesa viene riempita con byte null ('\0'):

Se len è negativo, verrà utilizzato 0.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Il mancato passaggio causerà un errore TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più opzionale. Il mancato passaggio genererà un avviso di deprecazione con id DEP0013.
v4.1.0	Stringhe numeriche, NaN e Infinity ora sono consentiti come specificatori di tempo.
v0.4.2	Aggiunto in: v0.4.2

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

Modifica i timestamp del file system dell'oggetto referenziato dal descrittore di file fornito. Vedi fs.utimes().

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

[Cronologia]

Versione	Modifiche
v22.2.0	Aggiunto il supporto per withFileTypes come opzione.
v22.0.0	Aggiunto in: v22.0.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> directory di lavoro corrente. Predefinito: process.cwd()
  • exclude <Function> Funzione per filtrare file/directory. Restituisce true per escludere l'elemento, false per includerlo. Predefinito: undefined.
  • withFileTypes <boolean> true se il glob deve restituire i percorsi come Dirents, false altrimenti. Predefinito: false.

• callback <Function>

  • err <Error>

• Recupera i file corrispondenti al pattern specificato.

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)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v16.0.0	L'errore restituito può essere un AggregateError se viene restituito più di un errore.
v10.0.0	Il parametro callback non è più facoltativo. Il non passaggio di esso genererà un TypeError in fase di runtime.
v7.0.0	Il parametro callback non è più facoltativo. Il non passaggio di esso emetterà un avviso di deprecazione con id DEP0013.
v0.4.7	Deprecato a partire da: v0.4.7

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

Modifica le autorizzazioni su un link simbolico. Alla callback di completamento non vengono forniti altri argomenti se non una possibile eccezione.

Questo metodo è implementato solo su macOS.

Vedere la documentazione POSIX lchmod(2) per maggiori dettagli.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.6.0	Questa API non è più deprecata.
v10.0.0	Il parametro callback non è più facoltativo. Il non passaggio di esso genererà un TypeError in fase di runtime.
v7.0.0	Il parametro callback non è più facoltativo. Il non passaggio di esso emetterà un avviso di deprecazione con id DEP0013.
v0.4.7	Deprecazione solo di documentazione.

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

Imposta il proprietario del link simbolico. Alla callback di completamento non vengono forniti altri argomenti se non una possibile eccezione.

Vedere la documentazione POSIX lchown(2) per maggiori dettagli.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v14.5.0, v12.19.0	Aggiunto in: v14.5.0, v12.19.0

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

Modifica i tempi di accesso e modifica di un file nello stesso modo di fs.utimes(), con la differenza che se il percorso si riferisce a un collegamento simbolico, il collegamento non viene dereferenziato: invece, vengono modificati i timestamp del collegamento simbolico stesso.

Nessun argomento oltre a una possibile eccezione viene fornito al callback di completamento.

fs.link(existingPath, newPath, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v7.6.0	I parametri existingPath e newPath possono essere oggetti URL WHATWG che utilizzano il protocollo file:. Il supporto è attualmente ancora sperimentale.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v0.1.31	Aggiunto in: v0.1.31

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

Crea un nuovo collegamento da existingPath a newPath. Consulta la documentazione POSIX link(2) per maggiori dettagli. Nessun argomento oltre a una possibile eccezione viene fornito al callback di completamento.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti devono essere bigint.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError a runtime.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v0.1.30	Aggiunto in: v0.1.30

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

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.

• callback <Function>

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

Recupera le <fs.Stats> per il collegamento simbolico a cui si fa riferimento tramite il percorso. La callback ottiene due argomenti (err, stats) dove stats è un oggetto <fs.Stats>. lstat() è identico a stat(), tranne per il fatto che se path è un collegamento simbolico, viene applicato stat-ed al collegamento stesso, non al file a cui fa riferimento.

Vedere la documentazione POSIX lstat(2) per maggiori dettagli.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v13.11.0, v12.17.0	In modalità recursive, il callback ora riceve il primo percorso creato come argomento.
v10.12.0	Il secondo argomento ora può essere un oggetto options con proprietà recursive e mode.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.1.8	Aggiunto in: v0.1.8

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

• options <Object> | <integer>

  • recursive <boolean> Predefinito: false
  • mode <string> | <integer> Non supportato su Windows. Predefinito: 0o777.

• callback <Function>

  • err <Error>
  • path <string> | <undefined> Presente solo se una directory viene creata con recursive impostato su true.

Crea una directory in modo asincrono.

Il callback riceve una possibile eccezione e, se recursive è true, il primo percorso di directory creato, (err[, path]). path può comunque essere undefined quando recursive è true, se non è stata creata alcuna directory (ad esempio, se è stata creata in precedenza).

L'argomento opzionale options può essere un intero che specifica mode (permessi e sticky bit), oppure un oggetto con una proprietà mode e una proprietà recursive che indica se le directory padre devono essere create. La chiamata a fs.mkdir() quando path è una directory esistente genera un errore solo quando recursive è false. Se recursive è false e la directory esiste, si verifica un errore EEXIST.

import { mkdir } from 'node:fs'

// Crea ./tmp/a/apple, indipendentemente dal fatto che ./tmp e ./tmp/a esistano.
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

Su Windows, l'utilizzo di fs.mkdir() sulla directory root, anche con la ricorsione, genererà un errore:

import { mkdir } from 'node:fs'

mkdir('/', { recursive: true }, err => {
  // => [Error: EPERM: operazione non consentita, mkdir 'C:\']
})

Consulta la documentazione POSIX mkdir(2) per maggiori dettagli.

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

[Cronologia]

Versione	Modifiche
v20.6.0, v18.19.0	Il parametro prefix ora accetta buffer e URL.
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v16.5.0, v14.18.0	Il parametro prefix ora accetta una stringa vuota.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError a runtime.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v6.2.1	Il parametro callback ora è opzionale.
v5.10.0	Aggiunto in: v5.10.0

• prefix <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • encoding <stringa> Predefinito: 'utf8'

• callback <Funzione>

  • err <Errore>
  • directory <stringa>

Crea una directory temporanea univoca.

Genera sei caratteri casuali da aggiungere dietro un prefisso richiesto per creare una directory temporanea univoca. A causa di incongruenze tra le piattaforme, evita i caratteri X finali in prefisso. Alcune piattaforme, in particolare i BSD, possono restituire più di sei caratteri casuali e sostituire i caratteri X finali in prefisso con caratteri casuali.

Il percorso della directory creata viene passato come stringa al secondo parametro del callback.

L'argomento opzionale options può essere una stringa che specifica una codifica, o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare.

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

Il metodo fs.mkdtemp() aggiungerà i sei caratteri selezionati casualmente direttamente alla stringa prefix. Ad esempio, data una directory /tmp, se l'intenzione è quella di creare una directory temporanea all'interno di /tmp, il prefix deve terminare con un separatore di percorso specifico della piattaforma (require('node:path').sep).

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

// La directory principale per la nuova directory temporanea
const tmpDir = tmpdir()

// Questo metodo è *INCORRETTO*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Stamperà qualcosa di simile a `/tmpabc123`.
  // Una nuova directory temporanea viene creata nella root del file system
  // anziché *all'interno* della directory /tmp.
})

// Questo metodo è *CORRETTO*:
import { sep } from 'node:path'
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Stamperà qualcosa di simile a `/tmp/abc123`.
  // Una nuova directory temporanea viene creata all'interno
  // della directory /tmp.
})

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v11.1.0	L'argomento flags ora è opzionale e il valore predefinito è 'r'.
v9.9.0	Ora sono supportati i flag as e as+.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v0.0.2	Aggiunto in: v0.0.2

• path <stringa> | <Buffer> | <URL>
• flags <stringa> | <numero> Vedere supporto dei flags del file system. Predefinito: 'r'.
• mode <stringa> | <intero> Predefinito: 0o666 (leggibile e scrivibile)
• callback <Funzione>
  • err <Errore>
  • fd <intero>

Apertura asincrona del file. Per maggiori dettagli, vedere la documentazione POSIX open(2).

mode imposta la modalità del file (permessi e sticky bit), ma solo se il file è stato creato. Su Windows, è possibile manipolare solo il permesso di scrittura; vedere fs.chmod().

La callback riceve due argomenti (err, fd).

Alcuni caratteri (\< \> : " / \ | ? *) sono riservati in Windows, come documentato in Denominazione di file, percorsi e spazi dei nomi. Sotto NTFS, se il nome del file contiene i due punti, Node.js aprirà uno stream del file system, come descritto in questa pagina MSDN.

Anche le funzioni basate su fs.open() presentano questo comportamento: fs.writeFile(), fs.readFile(), ecc.

fs.openAsBlob(path[, options])

Aggiunto in: v19.8.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• path <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • type <stringa> Un tipo MIME opzionale per il blob.

• Restituisce: <Promise> Si risolve con un <Blob> in caso di successo.

Restituisce un <Blob> i cui dati sono supportati dal file specificato.

Il file non deve essere modificato dopo la creazione del <Blob>. Qualsiasi modifica farà sì che la lettura dei dati <Blob> non riesca con un errore DOMException. Operazioni stat sincrone sul file quando viene creato il Blob e prima di ogni lettura per rilevare se i dati del file sono stati modificati sul disco.

ESM

import { openAsBlob } from 'node:fs'

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

CJS

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

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

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

[Cronologia]

Versione	Modifiche
v20.1.0, v18.17.0	Aggiunta l'opzione recursive.
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v13.1.0, v12.16.0	È stata introdotta l'opzione bufferSize.
v12.12.0	Aggiunto in: v12.12.0

• path <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • encoding <stringa> | <null> Predefinito: 'utf8'
  • bufferSize <numero> Numero di voci di directory che vengono memorizzate internamente nel buffer durante la lettura dalla directory. Valori più alti portano a prestazioni migliori ma a un maggiore utilizzo della memoria. Predefinito: 32
  • recursive <boolean> Predefinito: false

• callback <Funzione>

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

Apre in modo asincrono una directory. Vedere la documentazione POSIX opendir(3) per maggiori dettagli.

Crea un <fs.Dir>, che contiene tutte le ulteriori funzioni per la lettura e la pulizia della directory.

L'opzione encoding imposta la codifica per il path durante l'apertura della directory e le successive operazioni di lettura.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.10.0	Il parametro buffer ora può essere un qualsiasi TypedArray o un DataView.
v7.4.0	Il parametro buffer ora può essere un Uint8Array.
v6.0.0	Il parametro length ora può essere 0.
v0.0.2	Aggiunto in: v0.0.2

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> Il buffer in cui verranno scritti i dati.
• offset <integer> La posizione in buffer in cui scrivere i dati.
• length <integer> Il numero di byte da leggere.
• position <integer> | <bigint> | <null> Specifica da dove iniziare la lettura nel file. Se position è null o -1, i dati verranno letti dalla posizione corrente del file e la posizione del file verrà aggiornata. Se position è un numero intero non negativo, la posizione del file rimarrà invariata.
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Legge i dati dal file specificato da fd.

Il callback riceve tre argomenti, (err, bytesRead, buffer).

Se il file non viene modificato contemporaneamente, la fine del file viene raggiunta quando il numero di byte letti è zero.

Se questo metodo viene richiamato come la sua versione util.promisify(), restituisce una promise per un Object con le proprietà bytesRead e buffer.

Il metodo fs.read() legge i dati dal file specificato dal descrittore di file (fd). L'argomento length indica il numero massimo di byte che Node.js tenterà di leggere dal kernel. Tuttavia, il numero effettivo di byte letti (bytesRead) può essere inferiore alla length specificata per vari motivi.

Ad esempio:

• Se il file è più corto della length specificata, bytesRead verrà impostato sul numero effettivo di byte letti.
• Se il file incontra EOF (Fine File) prima che il buffer possa essere riempito, Node.js leggerà tutti i byte disponibili fino a quando non viene incontrato EOF e il parametro bytesRead nel callback indicherà il numero effettivo di byte letti, che potrebbe essere inferiore alla length specificata.
• Se il file si trova su un filesystem di rete lento o riscontra qualsiasi altro problema durante la lettura, bytesRead può essere inferiore alla length specificata.

Pertanto, quando si utilizza fs.read(), è importante controllare il valore di bytesRead per determinare quanti byte sono stati effettivamente letti dal file. A seconda della logica dell'applicazione, potrebbe essere necessario gestire i casi in cui bytesRead è inferiore alla length specificata, ad esempio racchiudendo la chiamata di lettura in un ciclo se è necessaria una quantità minima di byte.

Questo comportamento è simile alla funzione POSIX preadv2.

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

[Cronologia]

Versione	Modifiche
v13.11.0, v12.17.0	L'oggetto options può essere passato per rendere facoltativi buffer, offset, length e position.
v13.11.0, v12.17.0	Aggiunto in: v13.11.0, v12.17.0

• fd <integer>

• options <Object>

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

• callback <Function>

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

Simile alla funzione fs.read(), questa versione accetta un oggetto options facoltativo. Se non viene specificato alcun oggetto options, verranno utilizzati i valori predefiniti sopra indicati.

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

Aggiunto in: v18.2.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView> Il buffer in cui verranno scritti i dati.

• options <Object>

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

• callback <Function>

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

Simile alla funzione fs.read(), questa versione accetta un oggetto options opzionale. Se non viene specificato alcun oggetto options, verranno utilizzati i valori predefiniti sopra indicati.

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

[Cronologia]

Versione	Modifiche
v20.1.0, v18.17.0	Aggiunta l'opzione recursive.
v18.0.0	L'invio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.10.0	Aggiunta una nuova opzione withFileTypes.
v10.0.0	Il parametro callback non è più opzionale. Il mancato passaggio genererà un TypeError in fase di esecuzione.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Il mancato passaggio emetterà un avviso di deprecazione con l'ID DEP0013.
v6.0.0	Aggiunto il parametro options.
v0.1.8	Aggiunto in: v0.1.8

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'
  • withFileTypes <boolean> Predefinito: false
  • recursive <boolean> Se true, legge ricorsivamente il contenuto di una directory. In modalità ricorsiva, elencherà tutti i file, i sottodirectory e le sottocartelle. Predefinito: false.

• callback <Function>

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

Legge il contenuto di una directory. La callback ottiene due argomenti (err, files) dove files è un array dei nomi dei file nella directory esclusi '.' e '..'.

Vedere la documentazione POSIX readdir(3) per maggiori dettagli.

L'argomento opzionale options può essere una stringa che specifica una codifica o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per i nomi di file passati alla callback. Se encoding è impostato su 'buffer', i nomi di file restituiti verranno passati come oggetti <Buffer>.

Se options.withFileTypes è impostato su true, l'array files conterrà oggetti <fs.Dirent>.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora lancia ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v16.0.0	L'errore restituito potrebbe essere un AggregateError se viene restituito più di un errore.
v15.2.0, v14.17.0	L'argomento options può includere un AbortSignal per annullare una richiesta di lettura del file in corso.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v5.1.0	Il callback verrà sempre chiamato con null come parametro error in caso di successo.
v5.0.0	Il parametro path può ora essere un descrittore di file.
v0.1.29	Aggiunto in: v0.1.29

• path <string> | <Buffer> | <URL> | <integer> nome file o descrittore di file

• options <Object> | <string>

  • encoding <string> | <null> Predefinito: null
  • flag <string> Vedere supporto dei flag del file system. Predefinito: 'r'.
  • signal <AbortSignal> consente di interrompere una lettura di file in corso

• callback <Function>

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

Legge in modo asincrono l'intero contenuto di un file.

import { readFile } from 'node:fs'

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

Il callback riceve due argomenti (err, data), dove data è il contenuto del file.

Se non viene specificata alcuna codifica, viene restituito il buffer raw.

Se options è una stringa, specifica la codifica:

import { readFile } from 'node:fs'

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

Quando il percorso è una directory, il comportamento di fs.readFile() e fs.readFileSync() è specifico della piattaforma. Su macOS, Linux e Windows, verrà restituito un errore. Su FreeBSD, verrà restituita una rappresentazione del contenuto della directory.

import { readFile } from 'node:fs'

// macOS, Linux e Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: operazione non consentita su una directory, read <directory>]
})

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

È possibile interrompere una richiesta in corso utilizzando un AbortSignal. Se una richiesta viene interrotta, il callback viene chiamato con un AbortError:

import { readFile } from 'node:fs'

const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
})
// Quando si desidera interrompere la richiesta
controller.abort()

La funzione fs.readFile() memorizza nel buffer l'intero file. Per ridurre al minimo i costi di memoria, quando possibile, preferire lo streaming tramite fs.createReadStream().

L'interruzione di una richiesta in corso non interrompe le singole richieste del sistema operativo, ma piuttosto il buffering interno eseguito da fs.readFile.

Descrittori di file

Considerazioni sulle prestazioni

Il metodo fs.readFile() legge in modo asincrono il contenuto di un file in memoria un blocco alla volta, consentendo al ciclo di eventi di alternarsi tra un blocco e l'altro. Ciò consente all'operazione di lettura di avere un impatto minore su altre attività che potrebbero utilizzare il thread pool sottostante di libuv, ma significa che ci vorrà più tempo per leggere un file completo in memoria.

L'overhead di lettura aggiuntivo può variare notevolmente su sistemi diversi e dipende dal tipo di file in fase di lettura. Se il tipo di file non è un file regolare (ad esempio una pipe) e Node.js non è in grado di determinare una dimensione effettiva del file, ogni operazione di lettura caricherà 64 KiB di dati. Per i file regolari, ogni lettura elaborerà 512 KiB di dati.

Per le applicazioni che richiedono una lettura il più veloce possibile del contenuto dei file, è meglio utilizzare direttamente fs.read() e fare in modo che il codice dell'applicazione gestisca la lettura completa del file stesso.

Il problema di Node.js su GitHub #25741 fornisce maggiori informazioni e un'analisi dettagliata sulle prestazioni di fs.readFile() per più dimensioni di file in diverse versioni di Node.js.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più facoltativo. Se non viene passato, verrà generato un TypeError in fase di runtime.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più facoltativo. Se non viene passato, verrà emesso un avviso di deprecazione con id DEP0013.
v0.1.31	Aggiunto in: v0.1.31

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'

• callback <Function>

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

Legge il contenuto del collegamento simbolico a cui fa riferimento path. Il callback ottiene due argomenti (err, linkString).

Vedere la documentazione POSIX readlink(2) per maggiori dettagli.

L'argomento facoltativo options può essere una stringa che specifica una codifica o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso del collegamento passato al callback. Se encoding è impostato su 'buffer', il percorso del collegamento restituito verrà passato come oggetto <Buffer>.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v13.13.0, v12.17.0	Aggiunto in: v13.13.0, v12.17.0

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

Legge da un file specificato da fd e scrive in un array di ArrayBufferView utilizzando readv().

position è l'offset dall'inizio del file da cui i dati devono essere letti. Se typeof position !== 'number', i dati verranno letti dalla posizione corrente.

La callback riceverà tre argomenti: err, bytesRead e buffers. bytesRead indica quanti byte sono stati letti dal file.

Se questo metodo viene invocato come versione util.promisify(), restituisce una promise per un Object con le proprietà bytesRead e buffers.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v8.0.0	È stato aggiunto il supporto per la risoluzione di Pipe/Socket.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v6.4.0	La chiamata a realpath ora funziona di nuovo per vari casi limite su Windows.
v6.0.0	Il parametro cache è stato rimosso.
v0.1.31	Aggiunto in: v0.1.31

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> Predefinito: 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

Calcola in modo asincrono il nome del percorso canonico risolvendo ., .. e i collegamenti simbolici.

Un nome di percorso canonico non è necessariamente univoco. I collegamenti rigidi e i mount di collegamento possono esporre un'entità del file system attraverso molti nomi di percorso.

Questa funzione si comporta come realpath(3), con alcune eccezioni:

La callback riceve due argomenti (err, resolvedPath). Può utilizzare process.cwd per risolvere i percorsi relativi.

Sono supportati solo i percorsi che possono essere convertiti in stringhe UTF8.

L'argomento opzionale options può essere una stringa che specifica una codifica o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso passato alla callback. Se la encoding è impostata su 'buffer', il percorso restituito verrà passato come oggetto <Buffer>.

Se path si risolve in un socket o in una pipe, la funzione restituirà un nome dipendente dal sistema per quell'oggetto.

Un percorso che non esiste restituisce un errore ENOENT. error.path è il percorso assoluto del file.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v9.2.0	Aggiunto in: v9.2.0

• path <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • encoding <stringa> Predefinito: 'utf8'

• callback <Funzione>

  • err <Errore>
  • resolvedPath <stringa> | <Buffer>

realpath(3) asincrono.

La callback riceve due argomenti (err, resolvedPath).

Sono supportati solo i percorsi che possono essere convertiti in stringhe UTF8.

L'argomento options opzionale può essere una stringa che specifica una codifica o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso passato alla callback. Se encoding è impostato su 'buffer', il percorso restituito verrà passato come oggetto <Buffer>.

Su Linux, quando Node.js è collegato a musl libc, il file system procfs deve essere montato su /proc affinché questa funzione funzioni. Glibc non ha questa restrizione.

fs.rename(oldPath, newPath, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError a runtime.
v7.6.0	I parametri oldPath e newPath possono essere oggetti WHATWG URL che utilizzano il protocollo file:. Il supporto è attualmente ancora sperimentale.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v0.0.2	Aggiunto in: v0.0.2

• oldPath <stringa> | <Buffer> | <URL>
• newPath <stringa> | <Buffer> | <URL>
• callback <Funzione>
  • err <Errore>

Rinomina in modo asincrono il file in oldPath nel nome di percorso fornito come newPath. Nel caso in cui newPath esista già, verrà sovrascritto. Se esiste una directory in newPath, verrà generato un errore. Non vengono forniti altri argomenti alla callback di completamento oltre a una possibile eccezione.

Vedi anche: rename(2).

import { rename } from 'node:fs'

rename('vecchioFile.txt', 'nuovoFile.txt', err => {
  if (err) throw err
  console.log('Rinomina completata!')
})

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v16.0.0	L'utilizzo di fs.rmdir(path, { recursive: true }) su un path che è un file non è più consentito e restituisce un errore ENOENT su Windows e un errore ENOTDIR su POSIX.
v16.0.0	L'utilizzo di fs.rmdir(path, { recursive: true }) su un path che non esiste non è più consentito e restituisce un errore ENOENT.
v16.0.0	L'opzione recursive è obsoleta, il suo utilizzo attiva un avviso di deprecazione.
v14.14.0	L'opzione recursive è obsoleta, utilizzare invece fs.rm.
v13.3.0, v12.16.0	L'opzione maxBusyTries è stata rinominata in maxRetries e il suo valore predefinito è 0. L'opzione emfileWait è stata rimossa e gli errori EMFILE utilizzano la stessa logica di riprova degli altri errori. Ora è supportata l'opzione retryDelay. Ora vengono ritentati gli errori ENFILE.
v12.10.0	Ora sono supportate le opzioni recursive, maxBusyTries e emfileWait.
v10.0.0	Il parametro callback non è più facoltativo. Non passarlo genererà un TypeError in fase di esecuzione.
v7.6.0	I parametri path possono essere un oggetto URL WHATWG utilizzando il protocollo file:.
v7.0.0	Il parametro callback non è più facoltativo. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.0.2	Aggiunto in: v0.0.2

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Se si verifica un errore EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js ritenta l'operazione con un'attesa di backoff lineare di retryDelay millisecondi più lunga a ogni tentativo. Questa opzione rappresenta il numero di tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 0.
  • recursive <boolean> Se true, esegue una rimozione ricorsiva della directory. In modalità ricorsiva, le operazioni vengono ritentate in caso di errore. Predefinito: false. Obsoleto.
  • retryDelay <integer> La quantità di tempo in millisecondi da attendere tra i tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 100.
• callback <Function>
  • err <Error>

rmdir(2) asincrono. Alla callback di completamento non vengono forniti altri argomenti oltre a una possibile eccezione.

L'utilizzo di fs.rmdir() su un file (non una directory) restituisce un errore ENOENT su Windows e un errore ENOTDIR su POSIX.

Per ottenere un comportamento simile al comando Unix rm -rf, utilizzare fs.rm() con le opzioni { recursive: true, force: true }.

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

[Cronologia]

Versione	Modifiche
v17.3.0, v16.14.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v14.14.0	Aggiunto in: v14.14.0

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

• options <Object>

  • force <boolean> Quando true, le eccezioni verranno ignorate se path non esiste. Predefinito: false.
  • maxRetries <integer> Se si verifica un errore EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js ritenterà l'operazione con un'attesa di backoff lineare di retryDelay millisecondi più lunga a ogni tentativo. Questa opzione rappresenta il numero di tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 0.
  • recursive <boolean> Se true, esegui una rimozione ricorsiva. In modalità ricorsiva le operazioni vengono ritentate in caso di fallimento. Predefinito: false.
  • retryDelay <integer> La quantità di tempo in millisecondi da attendere tra i tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 100.

• callback <Function>

  • err <Error>

Rimuove in modo asincrono file e directory (modellato sull'utility POSIX standard rm). Nessun argomento diverso da una possibile eccezione viene fornito alla callback di completamento.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti devono essere bigint.
v10.0.0	Il parametro callback non è più opzionale. Il mancato passaggio genererà un TypeError in fase di esecuzione.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Il mancato passaggio emetterà un avviso di deprecazione con ID DEP0013.
v0.0.2	Aggiunto in: v0.0.2

• path <stringa> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.

• callback <Function>

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

stat(2) asincrono. Il callback ottiene due argomenti (err, stats) dove stats è un oggetto <fs.Stats>.

In caso di errore, err.code sarà uno degli Errori di sistema comuni.

fs.stat() segue i link simbolici. Utilizzare fs.lstat() per esaminare i link stessi.

Non è consigliabile utilizzare fs.stat() per verificare l'esistenza di un file prima di chiamare fs.open(), fs.readFile() o fs.writeFile(). Invece, il codice utente dovrebbe aprire/leggere/scrivere il file direttamente e gestire l'errore generato se il file non è disponibile.

Per verificare se un file esiste senza manipolarlo in seguito, si consiglia fs.access().

Ad esempio, data la seguente struttura di directory:

- txtDir
-- file.txt
- app.js

Il programma successivo verificherà le statistiche dei percorsi forniti:

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

L'output risultante sarà simile a:

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)

Aggiunto in: v19.6.0, v18.15.0

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

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.StatFs> restituito devono essere bigint. Predefinito: false.

• callback <Function>

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

Asincrono statfs(2). Restituisce informazioni sul file system montato che contiene path. Il callback riceve due argomenti (err, stats) dove stats è un oggetto <fs.StatFs>.

In caso di errore, err.code sarà uno dei Errori di Sistema Comuni.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v12.0.0	Se l'argomento type viene lasciato indefinito, Node rileva automaticamente il tipo di target e seleziona automaticamente dir o file.
v7.6.0	I parametri target e path possono essere oggetti WHATWG URL che utilizzano il protocollo file:. Il supporto è attualmente ancora sperimentale.
v0.1.31	Aggiunto in: v0.1.31

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

Crea il link chiamato path che punta a target. Nessun argomento oltre a una possibile eccezione viene fornito al callback di completamento.

Vedi la documentazione POSIX symlink(2) per maggiori dettagli.

L'argomento type è disponibile solo su Windows e ignorato su altre piattaforme. Può essere impostato su 'dir', 'file' o 'junction'. Se l'argomento type è null, Node.js rileverà automaticamente il tipo di target e utilizzerà 'file' o 'dir'. Se target non esiste, verrà utilizzato 'file'. I punti di giunzione di Windows richiedono che il percorso di destinazione sia assoluto. Quando si utilizza 'junction', l'argomento target verrà automaticamente normalizzato al percorso assoluto. I punti di giunzione sui volumi NTFS possono puntare solo alle directory.

I target relativi sono relativi alla directory principale del link.

import { symlink } from 'node:fs'

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

L'esempio sopra crea un collegamento simbolico mewtwo che punta a mew nella stessa directory:

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

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v16.0.0	L'errore restituito può essere un AggregateError se viene restituito più di un errore.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.8.6	Aggiunto in: v0.8.6

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

Tronca il file. Alla callback di completamento non vengono forniti argomenti oltre a una possibile eccezione. È anche possibile passare un descrittore di file come primo argomento. In questo caso, viene chiamato fs.ftruncate().

ESM

import { truncate } from 'node:fs'
// Supponendo che 'path/file.txt' sia un file normale.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt è stato troncato')
})

CJS

const { truncate } = require('node:fs')
// Supponendo che 'path/file.txt' sia un file normale.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt è stato troncato')
})

Passare un descrittore di file è deprecato e in futuro potrebbe causare la generazione di un errore.

Vedere la documentazione POSIX truncate(2) per maggiori dettagli.

fs.unlink(path, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.0.2	Aggiunto in: v0.0.2

• path <stringa> | <Buffer> | <URL>
• callback <Funzione>
  • err <Errore>

Rimuove in modo asincrono un file o un collegamento simbolico. Al callback di completamento non vengono forniti argomenti diversi da una possibile eccezione.

import { unlink } from 'node:fs'
// Supponendo che 'path/file.txt' sia un file regolare.
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt è stato eliminato')
})

fs.unlink() non funzionerà su una directory, vuota o meno. Per rimuovere una directory, usa fs.rmdir().

Vedi la documentazione POSIX unlink(2) per maggiori dettagli.

fs.unwatchFile(filename[, listener])

Aggiunto in: v0.1.31

• filename <stringa> | <Buffer> | <URL>
• listener <Funzione> Opzionale, un listener precedentemente allegato usando fs.watchFile()

Interrompe il monitoraggio delle modifiche su filename. Se viene specificato listener, viene rimosso solo quel particolare listener. Altrimenti, tutti i listener vengono rimossi, interrompendo di fatto il monitoraggio di filename.

Chiamare fs.unwatchFile() con un nome file che non è in fase di monitoraggio è un no-op, non un errore.

L'uso di fs.watch() è più efficiente di fs.watchFile() e fs.unwatchFile(). fs.watch() dovrebbe essere utilizzato al posto di fs.watchFile() e fs.unwatchFile() quando possibile.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di runtime.
v8.0.0	NaN, Infinity e -Infinity non sono più specificatori di tempo validi.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v4.1.0	Stringhe numeriche, NaN e Infinity sono ora specificatori di tempo consentiti.
v0.4.2	Aggiunto in: v0.4.2

• path <stringa> | <Buffer> | <URL>
• atime <numero> | <stringa> | <Date>
• mtime <numero> | <stringa> | <Date>
• callback <Funzione>
  • err <Errore>

Cambia i timestamp del file system dell'oggetto referenziato da path.

Gli argomenti atime e mtime seguono queste regole:

• I valori possono essere numeri che rappresentano il tempo Unix epoch in secondi, Date o una stringa numerica come '123456789.0'.
• Se il valore non può essere convertito in un numero, o è NaN, Infinity o -Infinity, verrà generato un Error.

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

[Cronologia]

Versione	Modifiche
v19.1.0	Aggiunto il supporto ricorsivo per Linux, AIX e IBMi.
v15.9.0, v14.17.0	Aggiunto il supporto per la chiusura del watcher con un AbortSignal.
v7.6.0	Il parametro filename può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v7.0.0	L'oggetto options passato non verrà mai modificato.
v0.5.10	Aggiunto in: v0.5.10

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

• options <string> | <Object>

  • persistent <boolean> Indica se il processo deve continuare a essere eseguito finché i file sono in fase di monitoraggio. Predefinito: true.
  • recursive <boolean> Indica se tutte le sottodirectory devono essere monitorate, o solo la directory corrente. Questo si applica quando viene specificata una directory, e solo su piattaforme supportate (Vedi avvertenze). Predefinito: false.
  • encoding <string> Specifica la codifica dei caratteri da utilizzare per il nome del file passato al listener. Predefinito: 'utf8'.
  • signal <AbortSignal> consente di chiudere il watcher con un AbortSignal.

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

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

• Restituisce: <fs.FSWatcher>

Monitora le modifiche a filename, dove filename è un file o una directory.

Il secondo argomento è facoltativo. Se options viene fornito come stringa, specifica la codifica. Altrimenti options deve essere passato come oggetto.

La callback del listener riceve due argomenti (eventType, filename). eventType è 'rename' o 'change', e filename è il nome del file che ha attivato l'evento.

Sulla maggior parte delle piattaforme, 'rename' viene emesso ogni volta che un nome di file compare o scompare nella directory.

La callback del listener è collegata all'evento 'change' attivato da <fs.FSWatcher>, ma non è la stessa cosa del valore 'change' di eventType.

Se viene passato un signal, l'interruzione del corrispondente AbortController chiuderà il <fs.FSWatcher> restituito.

Avvertenze

L'API fs.watch non è coerente al 100% tra le piattaforme e non è disponibile in alcune situazioni.

Su Windows, non verranno emessi eventi se la directory monitorata viene spostata o rinominata. Viene segnalato un errore EPERM quando la directory monitorata viene eliminata.

Disponibilità

Questa funzionalità dipende dal sistema operativo sottostante che fornisce un modo per essere informati delle modifiche al file system.

• Sui sistemi Linux, utilizza inotify(7).
• Sui sistemi BSD, utilizza kqueue(2).
• Su macOS, utilizza kqueue(2) per i file e FSEvents per le directory.
• Sui sistemi SunOS (inclusi Solaris e SmartOS), utilizza le porte eventi.
• Sui sistemi Windows, questa funzionalità dipende da ReadDirectoryChangesW.
• Sui sistemi AIX, questa funzionalità dipende da AHAFS, che deve essere abilitato.
• Sui sistemi IBM i, questa funzionalità non è supportata.

Se la funzionalità sottostante non è disponibile per qualche motivo, allora fs.watch() non sarà in grado di funzionare e potrebbe generare un'eccezione. Ad esempio, il monitoraggio di file o directory può essere inaffidabile e, in alcuni casi, impossibile su file system di rete (NFS, SMB, ecc.) o file system host quando si utilizza software di virtualizzazione come Vagrant o Docker.

È ancora possibile utilizzare fs.watchFile(), che utilizza il polling stat, ma questo metodo è più lento e meno affidabile.

Inodi

Sui sistemi Linux e macOS, fs.watch() risolve il percorso in un inode e monitora l'inode. Se il percorso monitorato viene eliminato e ricreato, gli viene assegnato un nuovo inode. Il monitoraggio emetterà un evento per l'eliminazione, ma continuerà a monitorare l'inode originale. Gli eventi per il nuovo inode non verranno emessi. Questo è il comportamento previsto.

I file AIX mantengono lo stesso inode per tutta la durata di un file. Il salvataggio e la chiusura di un file monitorato su AIX comporterà due notifiche (una per l'aggiunta di nuovi contenuti e una per il troncamento).

Argomento filename

Fornire l'argomento filename nel callback è supportato solo su Linux, macOS, Windows e AIX. Anche sulle piattaforme supportate, non è sempre garantito che filename venga fornito. Pertanto, non dare per scontato che l'argomento filename venga sempre fornito nel callback e prevedi una logica di fallback se è null.

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`il tipo di evento è: ${eventType}`)
  if (filename) {
    console.log(`filename fornito: ${filename}`)
  } else {
    console.log('filename non fornito')
  }
})

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

[Cronologia]

Versione	Cambiamenti
v10.5.0	L'opzione bigint è ora supportata.
v7.6.0	Il parametro filename può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v0.1.31	Aggiunto in: v0.1.31

• filename <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • bigint <boolean> Predefinito: false
  • persistent <boolean> Predefinito: true
  • interval <intero> Predefinito: 5007

• listener <Funzione>

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

• Restituisce: <fs.StatWatcher>

Monitora le modifiche su filename. Il callback listener verrà chiamato ogni volta che si accede al file.

L'argomento options può essere omesso. Se fornito, deve essere un oggetto. L'oggetto options può contenere un booleano denominato persistent che indica se il processo deve continuare a essere eseguito finché i file sono monitorati. L'oggetto options può specificare una proprietà interval che indica la frequenza con cui il target deve essere interrogato in millisecondi.

Il listener riceve due argomenti: l'oggetto stat corrente e l'oggetto stat precedente:

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`l'mtime corrente è: ${curr.mtime}`)
  console.log(`l'mtime precedente era: ${prev.mtime}`)
})

Questi oggetti stat sono istanze di fs.Stat. Se l'opzione bigint è true, i valori numerici in questi oggetti sono specificati come BigInts.

Per essere avvisato quando il file è stato modificato, non solo acceduto, è necessario confrontare curr.mtimeMs e prev.mtimeMs.

Quando un'operazione fs.watchFile genera un errore ENOENT, richiamerà il listener una volta, con tutti i campi azzerati (o, per le date, l'epoca Unix). Se il file viene creato successivamente, il listener verrà richiamato di nuovo, con gli ultimi oggetti stat. Questo è un cambiamento nella funzionalità rispetto alla v0.10.

L'utilizzo di fs.watch() è più efficiente di fs.watchFile e fs.unwatchFile. fs.watch dovrebbe essere utilizzato al posto di fs.watchFile e fs.unwatchFile quando possibile.

Quando un file monitorato da fs.watchFile() scompare e riappare, il contenuto di previous nel secondo evento di callback (la ricomparsa del file) sarà lo stesso del contenuto di previous nel primo evento di callback (la sua scomparsa).

Questo accade quando:

• il file viene eliminato, seguito da un ripristino
• il file viene rinominato e poi rinominato una seconda volta con il suo nome originale

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v14.0.0	Il parametro buffer non forza più l'input non supportato a stringhe.
v10.10.0	Il parametro buffer ora può essere qualsiasi TypedArray o DataView.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError durante l'esecuzione.
v7.4.0	Il parametro buffer ora può essere un Uint8Array.
v7.2.0	I parametri offset e length ora sono opzionali.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v0.0.2	Aggiunto in: v0.0.2

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Predefinito: 0
• length <integer> Predefinito: buffer.byteLength - offset
• position <integer> | <null> Predefinito: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

Scrive buffer nel file specificato da fd.

offset determina la parte del buffer da scrivere, e length è un intero che specifica il numero di byte da scrivere.

position si riferisce all'offset dall'inizio del file dove questi dati dovrebbero essere scritti. Se typeof position !== 'number', i dati saranno scritti nella posizione corrente. Vedere pwrite(2).

Il callback riceverà tre argomenti (err, bytesWritten, buffer) dove bytesWritten specifica quanti byte sono stati scritti da buffer.

Se questo metodo viene invocato come la sua versione util.promisify()ed, restituisce una promise per un Object con proprietà bytesWritten e buffer.

Non è sicuro usare fs.write() più volte sullo stesso file senza attendere il callback. Per questo scenario, è raccomandato fs.createWriteStream().

Su Linux, le scritture posizionali non funzionano quando il file viene aperto in modalità append. Il kernel ignora l'argomento position e aggiunge sempre i dati alla fine del file.

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

Aggiunto in: v18.3.0, v16.17.0

• fd <integer>

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

• options <Object>

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

• callback <Function>

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

Scrive buffer nel file specificato da fd.

Simile alla funzione fs.write precedente, questa versione accetta un oggetto options facoltativo. Se non viene specificato alcun oggetto options, utilizzerà i valori predefiniti sopra indicati.

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

[Cronologia]

Versione	Modifiche
v19.0.0	Non è più supportato passare al parametro string un oggetto con una funzione toString propria.
v17.8.0	Passare al parametro string un oggetto con una funzione toString propria è deprecato.
v14.12.0	Il parametro string serializzerà un oggetto con una funzione toString esplicita.
v14.0.0	Il parametro string non forzerà più l'input non supportato a stringhe.
v10.0.0	Il parametro callback non è più facoltativo. Non passarlo genererà un TypeError in fase di esecuzione.
v7.2.0	Il parametro position ora è facoltativo.
v7.0.0	Il parametro callback non è più facoltativo. Non passarlo emetterà un avviso di deprecazione con ID DEP0013.
v0.11.5	Aggiunto in: v0.11.5

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

Scrive string nel file specificato da fd. Se string non è una stringa, viene generata un'eccezione.

position si riferisce all'offset dall'inizio del file in cui questi dati devono essere scritti. Se typeof position !== 'number' i dati verranno scritti nella posizione corrente. Vedere pwrite(2).

encoding è la codifica di stringa prevista.

La callback riceverà gli argomenti (err, written, string) dove written specifica quanti byte sono stati necessari per scrivere la stringa passata. I byte scritti non sono necessariamente uguali ai caratteri della stringa scritti. Vedere Buffer.byteLength.

Non è sicuro utilizzare fs.write() più volte sullo stesso file senza attendere la callback. Per questo scenario, è consigliabile fs.createWriteStream().

Su Linux, le scritture posizionali non funzionano quando il file viene aperto in modalità di accodamento. Il kernel ignora l'argomento di posizione e aggiunge sempre i dati alla fine del file.

Su Windows, se il descrittore del file è connesso alla console (ad es. fd == 1 o stdout), una stringa contenente caratteri non ASCII non verrà visualizzata correttamente per impostazione predefinita, indipendentemente dalla codifica utilizzata. È possibile configurare la console per visualizzare correttamente UTF-8 modificando la code page attiva con il comando chcp 65001. Vedere la documentazione di chcp per maggiori dettagli.

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

[Cronologia]

Versione	Cambiamenti
v21.0.0, v20.10.0	L'opzione flush è ora supportata.
v19.0.0	Non è più supportato il passaggio al parametro string di un oggetto con una funzione toString propria.
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v17.8.0	Il passaggio al parametro string di un oggetto con una funzione toString propria è deprecato.
v16.0.0	L'errore restituito può essere un AggregateError se viene restituito più di un errore.
v15.2.0, v14.17.0	L'argomento options può includere un AbortSignal per interrompere una richiesta writeFile in corso.
v14.12.0	Il parametro data convertirà in stringa un oggetto con una funzione toString esplicita.
v14.0.0	Il parametro data non convertirà più forzatamente l'input non supportato in stringhe.
v10.10.0	Il parametro data può ora essere qualsiasi TypedArray o un DataView.
v10.0.0	Il parametro callback non è più opzionale. Non passarlo genererà un TypeError in fase di esecuzione.
v7.4.0	Il parametro data può ora essere un Uint8Array.
v7.0.0	Il parametro callback non è più opzionale. Non passarlo emetterà un avviso di deprecazione con id DEP0013.
v5.0.0	Il parametro file può ora essere un descrittore di file.
v0.1.29	Aggiunto in: v0.1.29

• file <stringa> | <Buffer> | <URL> | <numero intero> nome file o descrittore di file
• data <stringa> | <Buffer> | <TypedArray> | <DataView>
• options <Oggetto> | <stringa>
  • encoding <stringa> | <null> Predefinito: 'utf8'
  • mode <numero intero> Predefinito: 0o666
  • flag <stringa> Vedi supporto per le flag del file system. Predefinito: 'w'.
  • flush <booleano> Se tutti i dati vengono scritti correttamente nel file e flush è true, viene utilizzato fs.fsync() per scaricare i dati. Predefinito: false.
  • signal <AbortSignal> consente di interrompere una scrittura writeFile in corso
• callback <Funzione>
  • err <Errore> | <AggregateError>

Quando file è un nome file, scrive in modo asincrono i dati nel file, sostituendo il file se esiste già. data può essere una stringa o un buffer.

Quando file è un descrittore di file, il comportamento è simile alla chiamata diretta di fs.write() (che è raccomandato). Vedi le note seguenti sull'uso di un descrittore di file.

L'opzione encoding viene ignorata se data è un buffer.

L'opzione mode influisce solo sul file appena creato. Vedi fs.open() per maggiori dettagli.

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('Il file è stato salvato!')
})

Se options è una stringa, specifica la codifica:

import { writeFile } from 'node:fs'

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

Non è sicuro utilizzare fs.writeFile() più volte sullo stesso file senza attendere la callback. Per questo scenario, si consiglia fs.createWriteStream().

Analogamente a fs.readFile - fs.writeFile è un metodo di convenienza che esegue internamente più chiamate write per scrivere il buffer che gli viene passato. Per codice sensibile alle prestazioni, considera l'utilizzo di fs.createWriteStream().

È possibile utilizzare un <AbortSignal> per annullare una fs.writeFile(). L'annullamento è "il meglio possibile" ed è probabile che venga comunque scritta una certa quantità di dati.

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 => {
  // Quando una richiesta viene interrotta - la callback viene chiamata con un AbortError
})
// Quando la richiesta deve essere interrotta
controller.abort()

L'interruzione di una richiesta in corso non interrompe le singole richieste del sistema operativo, ma piuttosto il buffering interno che fs.writeFile esegue.

Utilizzo di fs.writeFile() con descrittori di file

Quando file è un descrittore di file, il comportamento è quasi identico alla chiamata diretta di fs.write() come:

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

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

La differenza rispetto alla chiamata diretta di fs.write() è che in alcune condizioni insolite, fs.write() potrebbe scrivere solo una parte del buffer e potrebbe essere necessario riprovare a scrivere i dati rimanenti, mentre fs.writeFile() riprova fino a quando i dati non vengono scritti interamente (o si verifica un errore).

Le implicazioni di ciò sono una fonte comune di confusione. Nel caso del descrittore di file, il file non viene sostituito! I dati non vengono necessariamente scritti all'inizio del file e i dati originali del file potrebbero rimanere prima e/o dopo i dati appena scritti.

Ad esempio, se fs.writeFile() viene chiamato due volte di fila, prima per scrivere la stringa 'Hello', poi per scrivere la stringa ', World', il file conterrebbe 'Hello, World', e potrebbe contenere alcuni dei dati originali del file (a seconda delle dimensioni del file originale e della posizione del descrittore di file). Se invece di un descrittore fosse stato utilizzato un nome di file, il file conterrebbe sicuramente solo ', World'.

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora restituisce ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v12.9.0	Aggiunto in: v12.9.0

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

Scrive un array di ArrayBufferView nel file specificato da fd usando writev().

position è l'offset dall'inizio del file in cui questi dati dovrebbero essere scritti. Se typeof position !== 'number', i dati verranno scritti nella posizione corrente.

Il callback riceverà tre argomenti: err, bytesWritten e buffers. bytesWritten è il numero di byte scritti da buffers.

Se questo metodo è util.promisify()ato, restituisce una promise per un Object con proprietà bytesWritten e buffers.

Non è sicuro utilizzare fs.writev() più volte sullo stesso file senza attendere il callback. Per questo scenario, utilizza fs.createWriteStream().

Su Linux, le scritture posizionali non funzionano quando il file è aperto in modalità di accodamento. Il kernel ignora l'argomento position e accoda sempre i dati alla fine del file.

API Sincrone

Le API sincrone eseguono tutte le operazioni in modo sincrono, bloccando il loop degli eventi fino a quando l'operazione non viene completata o fallisce.

fs.accessSync(path[, mode])

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG utilizzando il protocollo file:.
v0.11.15	Aggiunto in: v0.11.15

• path <stringa> | <Buffer> | <URL>
• mode <integer> Predefinito: fs.constants.F_OK

Verifica in modo sincrono le autorizzazioni di un utente per il file o la directory specificati da path. L'argomento mode è un intero facoltativo che specifica i controlli di accessibilità da eseguire. mode dovrebbe essere il valore fs.constants.F_OK o una maschera composta dall'OR bit a bit di uno qualsiasi tra fs.constants.R_OK, fs.constants.W_OK e fs.constants.X_OK (ad es. fs.constants.W_OK | fs.constants.R_OK). Controlla Costanti di accesso ai file per i possibili valori di mode.

Se uno qualsiasi dei controlli di accessibilità fallisce, verrà generato un Errore. Altrimenti, il metodo restituirà undefined.

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

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('può leggere/scrivere')
} catch (err) {
  console.error('nessun accesso!')
}

fs.appendFileSync(path, data[, options])

[Cronologia]

Versione	Modifiche
v21.1.0, v20.10.0	L'opzione flush ora è supportata.
v7.0.0	L'oggetto options passato non verrà mai modificato.
v5.0.0	Il parametro file ora può essere un descrittore di file.
v0.6.7	Aggiunto in: v0.6.7

• path <stringa> | <Buffer> | <URL> | <numero> nome file o descrittore di file
• data <stringa> | <Buffer>
• options <Oggetto> | <stringa>
  • encoding <stringa> | <null> Predefinito: 'utf8'
  • mode <integer> Predefinito: 0o666
  • flag <stringa> Consulta supporto dei flag del file system. Predefinito: 'a'.
  • flush <boolean> Se true, il descrittore di file sottostante viene scaricato prima della chiusura. Predefinito: false.

Aggiunge in modo sincrono i dati a un file, creandolo se non esiste ancora. data può essere una stringa o un <Buffer>.

L'opzione mode influisce solo sul file appena creato. Consulta fs.open() per maggiori dettagli.

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'dati da aggiungere')
  console.log('I "dati da aggiungere" sono stati aggiunti al file!')
} catch (err) {
  /* Gestisci l'errore */
}

Se options è una stringa, specifica la codifica:

import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'dati da aggiungere', 'utf8')

Il path può essere specificato come descrittore di file numerico che è stato aperto per l'aggiunta (utilizzando fs.open() o fs.openSync()). Il descrittore di file non verrà chiuso automaticamente.

import { openSync, closeSync, appendFileSync } from 'node:fs'

let fd

try {
  fd = openSync('message.txt', 'a')
  appendFileSync(fd, 'dati da aggiungere', 'utf8')
} catch (err) {
  /* Gestisci l'errore */
} finally {
  if (fd !== undefined) closeSync(fd)
}

fs.chmodSync(path, mode)

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG utilizzando il protocollo file:.
v0.6.7	Aggiunto in: v0.6.7

• path <stringa> | <Buffer> | <URL>
• mode <stringa> | <numero intero>

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.chmod().

Consultare la documentazione POSIX chmod(2) per maggiori dettagli.

fs.chownSync(path, uid, gid)

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG utilizzando il protocollo file:.
v0.1.97	Aggiunto in: v0.1.97

• path <stringa> | <Buffer> | <URL>
• uid <numero intero>
• gid <numero intero>

Cambia in modo sincrono il proprietario e il gruppo di un file. Restituisce undefined. Questa è la versione sincrona di fs.chown().

Consultare la documentazione POSIX chown(2) per maggiori dettagli.

fs.closeSync(fd)

Aggiunto in: v0.1.21

• fd <numero intero>

Chiude il descrittore di file. Restituisce undefined.

Chiamare fs.closeSync() su qualsiasi descrittore di file (fd) attualmente in uso tramite qualsiasi altra operazione fs potrebbe portare a un comportamento indefinito.

Consultare la documentazione POSIX close(2) per maggiori dettagli.

fs.copyFileSync(src, dest[, mode])

[Cronologia]

Versione	Cambiamenti
v14.0.0	Modificato l'argomento flags in mode e imposta una convalida del tipo più rigorosa.
v8.5.0	Aggiunto in: v8.5.0

• src <string> | <Buffer> | <URL> nome del file di origine da copiare
• dest <string> | <Buffer> | <URL> nome del file di destinazione dell'operazione di copia
• mode <integer> modificatori per l'operazione di copia. Predefinito: 0.

Copia in modo sincrono src in dest. Per impostazione predefinita, dest viene sovrascritto se esiste già. Restituisce undefined. Node.js non fornisce alcuna garanzia sull'atomicità dell'operazione di copia. Se si verifica un errore dopo che il file di destinazione è stato aperto per la scrittura, Node.js tenterà di rimuovere la destinazione.

mode è un intero opzionale che specifica il comportamento dell'operazione di copia. È possibile creare una maschera composta dall'OR bit a bit di due o più valori (ad esempio, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: l'operazione di copia fallirà se dest esiste già.
• fs.constants.COPYFILE_FICLONE: l'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma non supporta copy-on-write, viene utilizzato un meccanismo di copia di fallback.
• fs.constants.COPYFILE_FICLONE_FORCE: l'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma non supporta copy-on-write, l'operazione fallirà.

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

// destination.txt verrà creato o sovrascritto per impostazione predefinita.
copyFileSync('source.txt', 'destination.txt')
console.log('source.txt è stato copiato in destination.txt')

// Utilizzando COPYFILE_EXCL, l'operazione fallirà se destination.txt esiste.
copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL)

fs.cpSync(src, dest[, options])

[Cronologia]

Versione	Modifiche
v22.3.0	Questa API non è più sperimentale.
v20.1.0, v18.17.0	Accetta un'opzione mode aggiuntiva per specificare il comportamento di copia come l'argomento mode di fs.copyFile().
v17.6.0, v16.15.0	Accetta un'opzione verbatimSymlinks aggiuntiva per specificare se eseguire la risoluzione del percorso per i link simbolici.
v16.7.0	Aggiunto in: v16.7.0

• src <string> | <URL> percorso di origine da copiare.

• dest <string> | <URL> percorso di destinazione in cui copiare.

• options <Object>

  • dereference <boolean> dereferenzia i collegamenti simbolici. Predefinito: false.

  • errorOnExist <boolean> quando force è false e la destinazione esiste, genera un errore. Predefinito: false.

  • filter <Function> Funzione per filtrare i file/directory copiati. Restituisce true per copiare l'elemento, false per ignorarlo. Quando si ignora una directory, anche tutto il suo contenuto verrà saltato. Predefinito: undefined

  • src <string> percorso di origine da copiare.

  • dest <string> percorso di destinazione in cui copiare.

  • Restituisce: <boolean> Qualsiasi valore non-Promise che possa essere convertito in boolean.

  • force <boolean> sovrascrive il file o la directory esistente. L'operazione di copia ignorerà gli errori se si imposta questo valore su false e la destinazione esiste. Utilizzare l'opzione errorOnExist per modificare questo comportamento. Predefinito: true.

  • mode <integer> modificatori per l'operazione di copia. Predefinito: 0. Vedere il flag mode di fs.copyFileSync().

  • preserveTimestamps <boolean> Quando true vengono conservati i timestamp da src. Predefinito: false.

  • recursive <boolean> copia le directory in modo ricorsivo Predefinito: false

  • verbatimSymlinks <boolean> Quando true, la risoluzione del percorso per i collegamenti simbolici verrà saltata. Predefinito: false

Copia in modo sincrono l'intera struttura di directory da src a dest, incluse le sottodirectory e i file.

Quando si copia una directory in un'altra directory, i glob non sono supportati e il comportamento è simile a cp dir1/ dir2/.

fs.existsSync(path)

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

• path <string> | <Buffer> | <URL>
• Restituisce: <boolean>

Restituisce true se il percorso esiste, false altrimenti.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.exists().

fs.exists() è deprecato, ma fs.existsSync() non lo è. Il parametro callback di fs.exists() accetta parametri che non sono coerenti con altre callback di Node.js. fs.existsSync() non usa una callback.

import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('Il percorso esiste.')

fs.fchmodSync(fd, mode)

Aggiunto in: v0.4.7

• fd <integer>
• mode <string> | <integer>

Imposta le autorizzazioni sul file. Restituisce undefined.

Vedere la documentazione POSIX fchmod(2) per maggiori dettagli.

fs.fchownSync(fd, uid, gid)

Aggiunto in: v0.4.7

• fd <integer>
• uid <integer> L'ID utente del nuovo proprietario del file.
• gid <integer> L'ID gruppo del nuovo gruppo del file.

Imposta il proprietario del file. Restituisce undefined.

Vedere la documentazione POSIX fchown(2) per maggiori dettagli.

fs.fdatasyncSync(fd)

Aggiunto in: v0.1.96

• fd <integer>

Forza tutte le operazioni di I/O attualmente in coda associate al file allo stato di completamento I/O sincronizzato del sistema operativo. Fare riferimento alla documentazione POSIX fdatasync(2) per i dettagli. Restituisce undefined.

fs.fstatSync(fd[, options])

[Cronologia]

Versione	Modifiche
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti devono essere bigint.
v0.1.95	Aggiunto in: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.

• Restituisce: <fs.Stats>

Recupera <fs.Stats> per il descrittore di file.

Per maggiori dettagli, consulta la documentazione POSIX fstat(2).

fs.fsyncSync(fd)

Aggiunto in: v0.1.96

• fd <integer>

Richiede che tutti i dati per il descrittore di file aperto vengano scaricati sul dispositivo di archiviazione. L'implementazione specifica dipende dal sistema operativo e dal dispositivo. Fare riferimento alla documentazione POSIX fsync(2) per maggiori dettagli. Restituisce undefined.

fs.ftruncateSync(fd[, len])

Aggiunto in: v0.8.6

• fd <integer>
• len <integer> Predefinito: 0

Tronca il descrittore di file. Restituisce undefined.

Per informazioni dettagliate, consulta la documentazione della versione asincrona di questa API: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[Cronologia]

Versione	Cambiamenti
v4.1.0	Stringhe numeriche, NaN e Infinity sono ora consentiti come specificatori di tempo.
v0.4.2	Aggiunto in: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Versione sincrona di fs.futimes(). Restituisce undefined.

fs.globSync(pattern[, options])

[Cronologia]

Versione	Cambiamenti
v22.2.0	Aggiunto il supporto per withFileTypes come opzione.
v22.0.0	Aggiunto in: v22.0.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> directory di lavoro corrente. Predefinito: process.cwd()
  • exclude <Function> Funzione per filtrare file/directory. Restituisce true per escludere l'elemento, false per includerlo. Predefinito: undefined.
  • withFileTypes <boolean> true se la ricerca globale deve restituire i percorsi come Dirent, false altrimenti. Predefinito: false.
• Restituisce: <string[]> percorsi dei file che corrispondono al pattern.

ESM

import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))

CJS

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

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

Deprecato dal: v0.4.7

• path <stringa> | <Buffer> | <URL>
• mode <integer>

Modifica le autorizzazioni su un collegamento simbolico. Restituisce undefined.

Questo metodo è implementato solo su macOS.

Vedi la documentazione POSIX lchmod(2) per maggiori dettagli.

fs.lchownSync(path, uid, gid)

[Cronologia]

Versione	Modifiche
v10.6.0	Questa API non è più deprecata.
v0.4.7	Deprecazione solo documentazione.

• path <stringa> | <Buffer> | <URL>
• uid <integer> L'ID utente del nuovo proprietario del file.
• gid <integer> L'ID gruppo del nuovo gruppo del file.

Imposta il proprietario per il percorso. Restituisce undefined.

Vedi la documentazione POSIX lchown(2) per maggiori dettagli.

fs.lutimesSync(path, atime, mtime)

Aggiunto in: v14.5.0, v12.19.0

• path <stringa> | <Buffer> | <URL>
• atime <numero> | <stringa> | <Date>
• mtime <numero> | <stringa> | <Date>

Modifica i timestamp del file system del collegamento simbolico a cui fa riferimento path. Restituisce undefined oppure genera un'eccezione quando i parametri non sono corretti o l'operazione non riesce. Questa è la versione sincrona di fs.lutimes().

fs.linkSync(existingPath, newPath)

[Cronologia]

Versione	Modifiche
v7.6.0	I parametri existingPath e newPath possono essere oggetti URL WHATWG che utilizzano il protocollo file:. Il supporto è attualmente ancora sperimentale.
v0.1.31	Aggiunto in: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Crea un nuovo collegamento da existingPath a newPath. Per maggiori dettagli, consulta la documentazione POSIX link(2). Restituisce undefined.

fs.lstatSync(path[, options])

[Cronologia]

Versione	Modifiche
v15.3.0, v14.17.0	Accetta un'opzione throwIfNoEntry per specificare se debba essere generata un'eccezione nel caso in cui la voce non esista.
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti debbano essere bigint.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v0.1.30	Aggiunto in: v0.1.30

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

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.Stats> restituito debbano essere bigint. Predefinito: false.
  • throwIfNoEntry <boolean> Indica se debba essere generata un'eccezione nel caso in cui non esista alcuna voce del file system, piuttosto che restituire undefined. Predefinito: true.

• Restituisce: <fs.Stats>

Recupera <fs.Stats> per il collegamento simbolico a cui fa riferimento path.

Per maggiori dettagli, consulta la documentazione POSIX lstat(2).

fs.mkdirSync(path[, options])

[Cronologia]

Versione	Modifiche
v13.11.0, v12.17.0	In modalità recursive, viene ora restituito il primo percorso creato.
v10.12.0	Il secondo argomento ora può essere un oggetto options con le proprietà recursive e mode.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

• path <stringa> | <Buffer> | <URL>

• options <Oggetto> | <numero intero>

  • recursive <booleano> Predefinito: false
  • mode <stringa> | <numero intero> Non supportato su Windows. Predefinito: 0o777.

• Restituisce: <stringa> | <undefined>

Crea una directory in modo sincrono. Restituisce undefined o, se recursive è true, il primo percorso della directory creata. Questa è la versione sincrona di fs.mkdir().

Vedere la documentazione POSIX mkdir(2) per maggiori dettagli.

fs.mkdtempSync(prefix[, options])

[Cronologia]

Versione	Modifiche
v20.6.0, v18.19.0	Il parametro prefix ora accetta buffer e URL.
v16.5.0, v14.18.0	Il parametro prefix ora accetta una stringa vuota.
v5.10.0	Aggiunto in: v5.10.0

• prefix <stringa> | <Buffer> | <URL>

• options <stringa> | <Oggetto>

  • encoding <stringa> Predefinito: 'utf8'

• Restituisce: <stringa>

Restituisce il percorso della directory creata.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.mkdtemp().

L'argomento opzionale options può essere una stringa che specifica una codifica o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare.

fs.opendirSync(path[, options])

[Cronologia]

Versione	Modifiche
v20.1.0, v18.17.0	Aggiunta l'opzione recursive.
v13.1.0, v12.16.0	Introdotta l'opzione bufferSize.
v12.12.0	Aggiunto in: v12.12.0

• path <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • encoding <stringa> | <null> Predefinito: 'utf8'
  • bufferSize <numero> Numero di voci di directory che vengono memorizzate internamente quando si legge dalla directory. Valori più elevati comportano prestazioni migliori ma un maggiore utilizzo di memoria. Predefinito: 32
  • recursive <booleano> Predefinito: false

• Restituisce: <fs.Dir>

Apre in modo sincrono una directory. Vedere opendir(3).

Crea un <fs.Dir>, che contiene tutte le funzioni per la lettura e la pulizia della directory.

L'opzione encoding imposta la codifica per il path durante l'apertura della directory e le successive operazioni di lettura.

fs.openSync(path[, flags[, mode]])

[Cronologia]

Versione	Modifiche
v11.1.0	L'argomento flags ora è opzionale e il valore predefinito è 'r'.
v9.9.0	I flag as e as+ sono ora supportati.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL usando il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

• path <stringa> | <Buffer> | <URL>
• flags <stringa> | <numero> Predefinito: 'r'. Vedere supporto dei flag del file system.
• mode <stringa> | <intero> Predefinito: 0o666
• Restituisce: <numero>

Restituisce un numero intero che rappresenta il descrittore del file.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.open().

fs.readdirSync(path[, options])

[Cronologia]

Versione	Modifiche
v20.1.0, v18.17.0	Aggiunta l'opzione recursive.
v10.10.0	Aggiunta la nuova opzione withFileTypes.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL che utilizza il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'
  • withFileTypes <boolean> Predefinito: false
  • recursive <boolean> Se true, legge in modo ricorsivo il contenuto di una directory. In modalità ricorsiva, elenca tutti i file, i sottofile e le directory. Predefinito: false.

• Restituisce: <string[]> | <Buffer[]> | <fs.Dirent[]>

Legge il contenuto della directory.

Consulta la documentazione POSIX readdir(3) per maggiori dettagli.

L'argomento opzionale options può essere una stringa che specifica una codifica, oppure un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per i nomi file restituiti. Se encoding è impostata su 'buffer', i nomi file restituiti saranno passati come oggetti <Buffer>.

Se options.withFileTypes è impostato su true, il risultato conterrà oggetti <fs.Dirent>.

fs.readFileSync(path[, options])

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che usa il protocollo file:.
v5.0.0	Il parametro path ora può essere un descrittore di file.
v0.1.8	Aggiunto in: v0.1.8

• path <string> | <Buffer> | <URL> | <integer> nome del file o descrittore del file

• options <Object> | <string>

  • encoding <string> | <null> Predefinito: null
  • flag <string> Vedi supporto per i flag del file system. Predefinito: 'r'.

• Restituisce: <string> | <Buffer>

Restituisce il contenuto di path.

Per informazioni dettagliate, consulta la documentazione della versione asincrona di questa API: fs.readFile().

Se viene specificata l'opzione encoding, questa funzione restituisce una stringa. Altrimenti restituisce un buffer.

Simile a fs.readFile(), quando il percorso è una directory, il comportamento di fs.readFileSync() è specifico della piattaforma.

import { readFileSync } from 'node:fs'

// macOS, Linux e Windows
readFileSync('<directory>')
// => [Error: EISDIR: operazione non consentita su una directory, leggi <directory>]

//  FreeBSD
readFileSync('<directory>') // => <dati>

fs.readlinkSync(path[, options])

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG usando il protocollo file:.
v0.1.31	Aggiunto in: v0.1.31

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'

• Restituisce: <string> | <Buffer>

Restituisce il valore stringa del link simbolico.

Vedere la documentazione POSIX readlink(2) per maggiori dettagli.

L'argomento opzionale options può essere una stringa che specifica una codifica, o un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso del link restituito. Se encoding è impostato su 'buffer', il percorso del link restituito verrà passato come oggetto <Buffer>.

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

[Cronologia]

Versione	Modifiche
v10.10.0	Il parametro buffer ora può essere qualsiasi TypedArray o DataView.
v6.0.0	Il parametro length ora può essere 0.
v0.1.21	Aggiunto in: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer> | <bigint> | <null> Predefinito: null
• Restituisce: <number>

Restituisce il numero di bytesRead.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.read().

fs.readSync(fd, buffer[, options])

[Cronologia]

Versione	Modifiche
v13.13.0, v12.17.0	L'oggetto Options può essere passato per rendere offset, length e position opzionali.
v13.13.0, v12.17.0	Aggiunto in: v13.13.0, v12.17.0

• fd <integer>

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

• options <Object>

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

• Restituisce: <number>

Restituisce il numero di bytesRead.

Simile alla funzione fs.readSync di cui sopra, questa versione accetta un oggetto options opzionale. Se non viene specificato alcun oggetto options, verrà impostato il valore predefinito con i valori sopra indicati.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.read().

fs.readvSync(fd, buffers[, position])

Aggiunto in: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Predefinito: null
• Restituisce: <number> Il numero di byte letti.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.readv().

fs.realpathSync(path[, options])

[Cronologia]

Versione	Modifiche
v8.0.0	Aggiunto il supporto per la risoluzione di Pipe/Socket.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v6.4.0	La chiamata a realpathSync ora funziona di nuovo per vari casi limite su Windows.
v6.0.0	Il parametro cache è stato rimosso.
v0.1.31	Aggiunto in: v0.1.31

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'

• Restituisce: <string> | <Buffer>

Restituisce il percorso risolto.

Per informazioni dettagliate, consulta la documentazione della versione asincrona di questa API: fs.realpath().

fs.realpathSync.native(path[, options])

Aggiunto in: v9.2.0

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

• options <string> | <Object>

  • encoding <string> Predefinito: 'utf8'

• Restituisce: <string> | <Buffer>

realpath(3) sincrono.

Sono supportati solo i percorsi che possono essere convertiti in stringhe UTF8.

L'argomento opzionale options può essere una stringa che specifica una codifica oppure un oggetto con una proprietà encoding che specifica la codifica dei caratteri da utilizzare per il percorso restituito. Se encoding è impostato su 'buffer', il percorso restituito sarà passato come oggetto <Buffer>.

Su Linux, quando Node.js è collegato a musl libc, il file system procfs deve essere montato su /proc affinché questa funzione funzioni. Glibc non ha questa restrizione.

fs.renameSync(oldPath, newPath)

[Cronologia]

Versione	Modifiche
v7.6.0	I parametri oldPath e newPath possono essere oggetti URL WHATWG che utilizzano il protocollo file:. Il supporto è attualmente ancora sperimentale.
v0.1.21	Aggiunto in: v0.1.21

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Rinomina il file da oldPath a newPath. Restituisce undefined.

Vedere la documentazione POSIX rename(2) per maggiori dettagli.

fs.rmdirSync(path[, options])

[Cronologia]

Versione	Modifiche
v16.0.0	L'utilizzo di fs.rmdirSync(path, { recursive: true }) su un path che è un file non è più consentito e si traduce in un errore ENOENT su Windows e un errore ENOTDIR su POSIX.
v16.0.0	L'utilizzo di fs.rmdirSync(path, { recursive: true }) su un path che non esiste non è più consentito e si traduce in un errore ENOENT.
v16.0.0	L'opzione recursive è obsoleta, il suo utilizzo attiva un avviso di deprecazione.
v14.14.0	L'opzione recursive è obsoleta, utilizzare invece fs.rmSync.
v13.3.0, v12.16.0	L'opzione maxBusyTries è stata rinominata in maxRetries e il suo valore predefinito è 0. L'opzione emfileWait è stata rimossa e gli errori EMFILE utilizzano la stessa logica di ripetizione degli altri errori. L'opzione retryDelay è ora supportata. Gli errori ENFILE vengono ora ritentati.
v12.10.0	Le opzioni recursive, maxBusyTries e emfileWait sono ora supportate.
v7.6.0	I parametri path possono essere un oggetto URL WHATWG che utilizza il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Se si verifica un errore EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js ritenta l'operazione con un'attesa di backoff lineare di retryDelay millisecondi più lunga ad ogni tentativo. Questa opzione rappresenta il numero di tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 0.
  • recursive <boolean> Se true, esegue una rimozione ricorsiva della directory. In modalità ricorsiva, le operazioni vengono ritentate in caso di errore. Predefinito: false. Obsoleto.
  • retryDelay <integer> La quantità di tempo in millisecondi da attendere tra i tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 100.

rmdir(2) sincrono. Restituisce undefined.

L'utilizzo di fs.rmdirSync() su un file (non una directory) si traduce in un errore ENOENT su Windows e un errore ENOTDIR su POSIX.

Per ottenere un comportamento simile al comando Unix rm -rf, utilizzare fs.rmSync() con le opzioni { recursive: true, force: true }.

fs.rmSync(path[, options])

[Cronologia]

Versione	Modifiche
v17.3.0, v16.14.0	Il parametro path può essere un oggetto WHATWG URL usando il protocollo file:.
v14.14.0	Aggiunto in: v14.14.0

• path <stringa> | <Buffer> | <URL>
• options <Oggetto>
  • force <booleano> Quando true, le eccezioni verranno ignorate se path non esiste. Predefinito: false.
  • maxRetries <numero intero> Se si verifica un errore EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js riproverà l'operazione con un'attesa lineare di backoff di retryDelay millisecondi in più ad ogni tentativo. Questa opzione rappresenta il numero di tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 0.
  • recursive <booleano> Se true, esegue una rimozione ricorsiva della directory. In modalità ricorsiva, le operazioni vengono ritentate in caso di errore. Predefinito: false.
  • retryDelay <numero intero> La quantità di tempo in millisecondi da attendere tra i tentativi. Questa opzione viene ignorata se l'opzione recursive non è true. Predefinito: 100.

Rimuove in modo sincrono file e directory (modellato sull'utility standard POSIX rm). Restituisce undefined.

fs.statSync(path[, options])

[Cronologia]

Versione	Modifiche
v15.3.0, v14.17.0	Accetta un'opzione throwIfNoEntry per specificare se un'eccezione deve essere generata se la voce non esiste.
v10.5.0	Accetta un oggetto options aggiuntivo per specificare se i valori numerici restituiti devono essere bigint.
v7.6.0	Il parametro path può essere un oggetto WHATWG URL usando il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

• path <stringa> | <Buffer> | <URL>

• options <Oggetto>

  • bigint <booleano> Se i valori numerici nell'oggetto <fs.Stats> restituito devono essere bigint. Predefinito: false.
  • throwIfNoEntry <booleano> Se verrà generata un'eccezione se non esiste una voce del file system, anziché restituire undefined. Predefinito: true.

• Restituisce: <fs.Stats>

Recupera <fs.Stats> per il percorso.

fs.statfsSync(path[, options])

Aggiunto in: v19.6.0, v18.15.0

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

• options <Object>

  • bigint <boolean> Indica se i valori numerici nell'oggetto <fs.StatFs> restituito devono essere di tipo bigint. Predefinito: false.

• Restituisce: <fs.StatFs>

statfs(2) sincrono. Restituisce informazioni sul file system montato che contiene path.

In caso di errore, err.code sarà uno tra gli Errori comuni di sistema.

fs.symlinkSync(target, path[, type])

[Cronologia]

Versione	Modifiche
v12.0.0	Se l'argomento type viene lasciato non definito, Node rileva automaticamente il tipo di target e seleziona automaticamente dir o file.
v7.6.0	I parametri target e path possono essere oggetti URL WHATWG che utilizzano il protocollo file:. Il supporto è attualmente ancora sperimentale.
v0.1.31	Aggiunto in: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Predefinito: null

Restituisce undefined.

Per informazioni dettagliate, consultare la documentazione della versione asincrona di questa API: fs.symlink().

fs.truncateSync(path[, len])

Aggiunto in: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> Predefinito: 0

Tronca il file. Restituisce undefined. Un descrittore di file può anche essere passato come primo argomento. In questo caso, viene chiamato fs.ftruncateSync().

Passare un descrittore di file è deprecato e potrebbe causare la generazione di un errore in futuro.

fs.unlinkSync(path)

[Cronologia]

Versione	Modifiche
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v0.1.21	Aggiunto in: v0.1.21

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

unlink(2) sincrono. Restituisce undefined.

fs.utimesSync(path, atime, mtime)

[Cronologia]

Versione	Modifiche
v8.0.0	NaN, Infinity e -Infinity non sono più specificatori di tempo validi.
v7.6.0	Il parametro path può essere un oggetto URL WHATWG che utilizza il protocollo file:.
v4.1.0	Stringhe numeriche, NaN e Infinity sono ora specificatori di tempo consentiti.
v0.4.2	Aggiunto in: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Restituisce undefined.

Per informazioni dettagliate, consultare la documentazione della versione asincrona di questa API: fs.utimes().

fs.writeFileSync(file, data[, options])

[Cronologia]

Versione	Modifiche
v21.0.0, v20.10.0	L'opzione flush è ora supportata.
v19.0.0	Passare al parametro data un oggetto con una funzione toString propria non è più supportato.
v17.8.0	Passare al parametro data un oggetto con una funzione toString propria è deprecato.
v14.12.0	Il parametro data trasformerà in stringa un oggetto con una funzione toString esplicita.
v14.0.0	Il parametro data non forzerà più l'input non supportato a stringhe.
v10.10.0	Il parametro data ora può essere un qualsiasi TypedArray o una DataView.
v7.4.0	Il parametro data ora può essere un Uint8Array.
v5.0.0	Il parametro file ora può essere un descrittore di file.
v0.1.29	Aggiunto in: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> nome file o descrittore di file
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> Predefinito: 'utf8'
  • mode <integer> Predefinito: 0o666
  • flag <string> Vedere supporto dei flag del file system. Predefinito: 'w'.
  • flush <boolean> Se tutti i dati sono stati scritti correttamente nel file, e flush è true, fs.fsyncSync() viene usato per scaricare i dati.

Restituisce undefined.

L'opzione mode influisce solo sul file appena creato. Vedere fs.open() per maggiori dettagli.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.writeFile().

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

[Cronologia]

Versione	Modifiche
v14.0.0	Il parametro buffer non forzerà più input non supportati a stringhe.
v10.10.0	Il parametro buffer ora può essere qualsiasi TypedArray o DataView.
v7.4.0	Il parametro buffer ora può essere un Uint8Array.
v7.2.0	I parametri offset e length ora sono opzionali.
v0.1.21	Aggiunto in: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Predefinito: 0
• length <integer> Predefinito: buffer.byteLength - offset
• position <integer> | <null> Predefinito: null
• Restituisce: <number> Il numero di byte scritti.

Per informazioni dettagliate, consultare la documentazione della versione asincrona di questa API: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

Aggiunto in: v18.3.0, v16.17.0

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • offset <integer> Predefinito: 0
  • length <integer> Predefinito: buffer.byteLength - offset
  • position <integer> Predefinito: null
• Restituisce: <number> Il numero di byte scritti.

Per informazioni dettagliate, consultare la documentazione della versione asincrona di questa API: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

[Cronologia]

Versione	Modifiche
v14.0.0	Il parametro string non forzerà più l'input non supportato a stringhe.
v7.2.0	Il parametro position ora è opzionale.
v0.11.5	Aggiunto in: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> Predefinito: null
• encoding <string> Predefinito: 'utf8'
• Restituisce: <number> Il numero di byte scritti.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.write(fd, string...).

fs.writevSync(fd, buffers[, position])

Aggiunto in: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Predefinito: null
• Restituisce: <number> Il numero di byte scritti.

Per informazioni dettagliate, vedere la documentazione della versione asincrona di questa API: fs.writev().

Oggetti Comuni

Gli oggetti comuni sono condivisi da tutte le varianti dell'API del file system (promise, callback e sincrona).

Classe: fs.Dir

Aggiunto in: v12.12.0

Una classe che rappresenta un flusso di directory.

Creata da fs.opendir(), fs.opendirSync(), o 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)
}

Quando si utilizza l'iteratore async, l'oggetto <fs.Dir> verrà chiuso automaticamente dopo l'uscita dell'iteratore.

dir.close()

Aggiunto in: v12.12.0

• Restituisce: <Promise>

Chiude in modo asincrono l'handle della risorsa sottostante della directory. Le letture successive provocheranno errori.

Viene restituita una promise che verrà soddisfatta dopo che la risorsa è stata chiusa.

dir.close(callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v12.12.0	Aggiunto in: v12.12.0

• callback <Function>
  • err <Error>

Chiude in modo asincrono l'handle della risorsa sottostante della directory. Le letture successive provocheranno errori.

La callback verrà chiamata dopo che l'handle della risorsa è stato chiuso.

dir.closeSync()

Aggiunto in: v12.12.0

Chiude in modo sincrono l'handle della risorsa sottostante della directory. Le letture successive provocheranno errori.

dir.path

Aggiunto in: v12.12.0

• <string>

Il percorso di sola lettura di questa directory come è stato fornito a fs.opendir(), fs.opendirSync() o fsPromises.opendir().

dir.read()

Aggiunto in: v12.12.0

• Restituisce: <Promise> Risolve con un <fs.Dirent> | <null>

Legge in modo asincrono la prossima voce della directory tramite readdir(3) come un <fs.Dirent>.

Viene restituita una promise che verrà risolta con un <fs.Dirent>, o null se non ci sono più voci della directory da leggere.

Le voci della directory restituite da questa funzione non sono in un ordine particolare, così come fornite dai meccanismi della directory sottostanti del sistema operativo. Le voci aggiunte o rimosse durante l'iterazione sulla directory potrebbero non essere incluse nei risultati dell'iterazione.

dir.read(callback)

Aggiunto in: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

Legge in modo asincrono la prossima voce della directory tramite readdir(3) come un <fs.Dirent>.

Dopo che la lettura è stata completata, la callback verrà chiamata con un <fs.Dirent>, o null se non ci sono più voci della directory da leggere.

Le voci della directory restituite da questa funzione non sono in un ordine particolare, così come fornite dai meccanismi della directory sottostanti del sistema operativo. Le voci aggiunte o rimosse durante l'iterazione sulla directory potrebbero non essere incluse nei risultati dell'iterazione.

dir.readSync()

Aggiunto in: v12.12.0

• Restituisce: <fs.Dirent> | <null>

Legge in modo sincrono la prossima voce della directory come un <fs.Dirent>. Consulta la documentazione POSIX readdir(3) per maggiori dettagli.

Se non ci sono più voci della directory da leggere, verrà restituito null.

Le voci della directory restituite da questa funzione non sono in un ordine particolare, così come fornite dai meccanismi della directory sottostanti del sistema operativo. Le voci aggiunte o rimosse durante l'iterazione sulla directory potrebbero non essere incluse nei risultati dell'iterazione.

dir[Symbol.asyncIterator]()

Aggiunto in: v12.12.0

• Restituisce: <AsyncIterator> Un AsyncIterator di <fs.Dirent>

Itera in modo asincrono sulla directory fino a quando tutte le voci non sono state lette. Fare riferimento alla documentazione POSIX readdir(3) per maggiori dettagli.

Le voci restituite dall'iteratore asincrono sono sempre un <fs.Dirent>. Il caso null di dir.read() viene gestito internamente.

Vedere <fs.Dir> per un esempio.

Le voci di directory restituite da questo iteratore non sono in un ordine particolare come fornito dai meccanismi di directory sottostanti del sistema operativo. Le voci aggiunte o rimosse durante l'iterazione sulla directory potrebbero non essere incluse nei risultati dell'iterazione.

Classe: fs.Dirent

Aggiunto in: v10.10.0

Una rappresentazione di una voce di directory, che può essere un file o una sottodirectory all'interno della directory, come restituito dalla lettura da un <fs.Dir>. La voce di directory è una combinazione del nome del file e delle coppie di tipo di file.

Inoltre, quando fs.readdir() o fs.readdirSync() viene chiamato con l'opzione withFileTypes impostata su true, l'array risultante viene riempito con oggetti <fs.Dirent>, anziché stringhe o <Buffer>.

dirent.isBlockDevice()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive un dispositivo a blocchi.

dirent.isCharacterDevice()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive un dispositivo a caratteri.

dirent.isDirectory()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive una directory del file system.

dirent.isFIFO()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive una pipe first-in-first-out (FIFO).

dirent.isFile()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive un file regolare.

dirent.isSocket()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive un socket.

dirent.isSymbolicLink()

Aggiunto in: v10.10.0

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Dirent> descrive un collegamento simbolico.

dirent.name

Aggiunto in: v10.10.0

• <string> | <Buffer>

Il nome del file a cui fa riferimento questo oggetto <fs.Dirent>. Il tipo di questo valore è determinato dall'elemento options.encoding passato a fs.readdir() o fs.readdirSync().

dirent.parentPath

Aggiunto in: v21.4.0, v20.12.0, v18.20.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• <string>

Il percorso della directory padre del file a cui fa riferimento questo oggetto <fs.Dirent>.

dirent.path

[Cronologia]

Versione	Cambiamenti
v23.2.0	La proprietà non è più di sola lettura.
v23.0.0	L'accesso a questa proprietà emette un avviso. Ora è di sola lettura.
v21.5.0, v20.12.0, v18.20.0	Deprecato da: v21.5.0, v20.12.0, v18.20.0
v20.1.0, v18.17.0	Aggiunto in: v20.1.0, v18.17.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: utilizzare invece dirent.parentPath.

• <string>

Alias per dirent.parentPath.

Classe: fs.FSWatcher

Aggiunto in: v0.5.8

• Estende <EventEmitter>

Una chiamata di successo al metodo fs.watch() restituirà un nuovo oggetto <fs.FSWatcher>.

Tutti gli oggetti <fs.FSWatcher> emettono un evento 'change' ogni volta che un file specifico osservato viene modificato.

Evento: 'change'

Aggiunto in: v0.5.8

• eventType <string> Il tipo di evento di modifica che si è verificato
• filename <string> | <Buffer> Il nome del file che è cambiato (se rilevante/disponibile)

Emesso quando qualcosa cambia in una directory o file osservato. Maggiori dettagli in fs.watch().

L'argomento filename potrebbe non essere fornito a seconda del supporto del sistema operativo. Se filename viene fornito, verrà fornito come <Buffer> se fs.watch() viene chiamato con la sua opzione encoding impostata su 'buffer', altrimenti filename sarà una stringa UTF-8.

import { watch } from 'node:fs'
// Esempio se gestito tramite listener fs.watch()
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename)
    // Stampa: <Buffer ...>
  }
})

Evento: 'close'

Aggiunto in: v10.0.0

Emesso quando il watcher smette di monitorare le modifiche. L'oggetto <fs.FSWatcher> chiuso non è più utilizzabile nell'event handler.

Evento: 'error'

Aggiunto in: v0.5.8

• error <Error>

Emesso quando si verifica un errore durante il monitoraggio del file. L'oggetto <fs.FSWatcher> in errore non è più utilizzabile nell'event handler.

watcher.close()

Aggiunto in: v0.5.8

Interrompe il monitoraggio delle modifiche sull'oggetto <fs.FSWatcher> specificato. Una volta arrestato, l'oggetto <fs.FSWatcher> non è più utilizzabile.

watcher.ref()

Aggiunto in: v14.3.0, v12.20.0

• Restituisce: <fs.FSWatcher>

Quando chiamato, richiede che il ciclo di eventi di Node.js non termini finché l'oggetto <fs.FSWatcher> è attivo. La chiamata a watcher.ref() più volte non ha effetto.

Per impostazione predefinita, tutti gli oggetti <fs.FSWatcher> sono "ref'ed", rendendo normalmente non necessario chiamare watcher.ref() a meno che watcher.unref() non sia stato chiamato in precedenza.

watcher.unref()

Aggiunto in: v14.3.0, v12.20.0

• Restituisce: <fs.FSWatcher>

Quando chiamato, l'oggetto <fs.FSWatcher> attivo non richiederà che il ciclo di eventi di Node.js rimanga attivo. Se non ci sono altre attività che mantengono in esecuzione il ciclo di eventi, il processo potrebbe terminare prima che venga richiamata la callback dell'oggetto <fs.FSWatcher>. La chiamata a watcher.unref() più volte non ha effetto.

Classe: fs.StatWatcher

Aggiunto in: v14.3.0, v12.20.0

• Estende <EventEmitter>

Una chiamata riuscita al metodo fs.watchFile() restituirà un nuovo oggetto <fs.StatWatcher>.

watcher.ref()

Aggiunto in: v14.3.0, v12.20.0

• Restituisce: <fs.StatWatcher>

Quando chiamato, richiede che il ciclo di eventi di Node.js non termini finché l'oggetto <fs.StatWatcher> è attivo. La chiamata a watcher.ref() più volte non ha effetto.

Per impostazione predefinita, tutti gli oggetti <fs.StatWatcher> sono "ref'ed", rendendo normalmente non necessario chiamare watcher.ref() a meno che watcher.unref() non sia stato chiamato in precedenza.

watcher.unref()

Aggiunto in: v14.3.0, v12.20.0

• Restituisce: <fs.StatWatcher>

Quando viene chiamato, l'oggetto <fs.StatWatcher> attivo non richiederà che il ciclo di eventi di Node.js rimanga attivo. Se non ci sono altre attività che mantengono in esecuzione il ciclo di eventi, il processo potrebbe terminare prima che venga richiamata la callback dell'oggetto <fs.StatWatcher>. La chiamata di watcher.unref() più volte non avrà alcun effetto.

Classe: fs.ReadStream

Aggiunto in: v0.1.93

• Estende: <stream.Readable>

Le istanze di <fs.ReadStream> vengono create e restituite utilizzando la funzione fs.createReadStream().

Evento: 'close'

Aggiunto in: v0.1.93

Emesso quando il descrittore di file sottostante di <fs.ReadStream> è stato chiuso.

Evento: 'open'

Aggiunto in: v0.1.93

• fd <integer> Descrittore di file intero utilizzato da <fs.ReadStream>.

Emesso quando il descrittore di file di <fs.ReadStream> è stato aperto.

Evento: 'ready'

Aggiunto in: v9.11.0

Emesso quando <fs.ReadStream> è pronto per essere utilizzato.

Si attiva immediatamente dopo 'open'.

readStream.bytesRead

Aggiunto in: v6.4.0

• <number>

Il numero di byte che sono stati letti finora.

readStream.path

Aggiunto in: v0.1.93

• <string> | <Buffer>

Il percorso del file da cui il flusso sta leggendo come specificato nel primo argomento di fs.createReadStream(). Se path viene passato come stringa, allora readStream.path sarà una stringa. Se path viene passato come <Buffer>, allora readStream.path sarà un <Buffer>. Se viene specificato fd, allora readStream.path sarà undefined.

readStream.pending

Aggiunto in: v11.2.0, v10.16.0

• <boolean>

Questa proprietà è true se il file sottostante non è stato ancora aperto, ovvero prima che venga emesso l'evento 'ready'.

Classe: fs.Stats

[Cronologia]

Versione	Modifiche
v22.0.0, v20.13.0	Il costruttore pubblico è deprecato.
v8.1.0	Aggiunti i tempi come numeri.
v0.1.21	Aggiunto in: v0.1.21

Un oggetto <fs.Stats> fornisce informazioni su un file.

Gli oggetti restituiti da fs.stat(), fs.lstat(), fs.fstat() e le loro controparti sincrone sono di questo tipo. Se bigint nelle options passate a questi metodi è true, i valori numerici saranno bigint invece di number e l'oggetto conterrà proprietà aggiuntive con precisione in nanosecondi con suffisso Ns. Gli oggetti Stat non devono essere creati direttamente utilizzando la parola chiave new.

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 }

Versione bigint:

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

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive un dispositivo a blocchi.

stats.isCharacterDevice()

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive un dispositivo a caratteri.

stats.isDirectory()

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive una directory del file system.

Se l'oggetto <fs.Stats> è stato ottenuto chiamando fs.lstat() su un collegamento simbolico che si risolve in una directory, questo metodo restituirà false. Questo perché fs.lstat() restituisce informazioni su un collegamento simbolico stesso e non sul percorso a cui si risolve.

stats.isFIFO()

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive una pipe first-in-first-out (FIFO).

stats.isFile()

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive un file regolare.

stats.isSocket()

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive un socket.

stats.isSymbolicLink()

Aggiunto in: v0.1.10

• Restituisce: <boolean>

Restituisce true se l'oggetto <fs.Stats> descrive un collegamento simbolico.

Questo metodo è valido solo quando si utilizza fs.lstat().

stats.dev

• <number> | <bigint>

L'identificatore numerico del dispositivo contenente il file.

stats.ino

• <number> | <bigint>

Il numero "Inode" specifico del file system per il file.

stats.mode

• <number> | <bigint>

Un campo di bit che descrive il tipo e la modalità del file.

stats.nlink

• <number> | <bigint>

Il numero di hard-link esistenti per il file.

stats.uid

• <number> | <bigint>

L'identificatore numerico dell'utente proprietario del file (POSIX).

stats.gid

• <number> | <bigint>

L'identificatore numerico del gruppo proprietario del file (POSIX).

stats.rdev

• <number> | <bigint>

Un identificatore numerico del dispositivo se il file rappresenta un dispositivo.

stats.size

• <number> | <bigint>

La dimensione del file in byte.

Se il file system sottostante non supporta l'ottenimento della dimensione del file, questo sarà 0.

stats.blksize

• <number> | <bigint>

La dimensione del blocco del file system per le operazioni di i/o.

stats.blocks

• <number> | <bigint>

Il numero di blocchi allocati per questo file.

stats.atimeMs

Aggiunto in: v8.1.0

• <number> | <bigint>

Il timestamp che indica l'ultima volta che si è acceduto a questo file espresso in millisecondi dall'epoca POSIX.

stats.mtimeMs

Aggiunto in: v8.1.0

• <number> | <bigint>

Il timestamp che indica l'ultima volta che questo file è stato modificato espresso in millisecondi dall'epoca POSIX.

stats.ctimeMs

Aggiunto in: v8.1.0

• <number> | <bigint>

Il timestamp che indica l'ultima volta che lo stato del file è stato modificato espresso in millisecondi dall'epoca POSIX.

stats.birthtimeMs

Aggiunto in: v8.1.0

• <number> | <bigint>

Il timestamp che indica l'ora di creazione di questo file espressa in millisecondi dall'epoca POSIX.

stats.atimeNs

Aggiunto in: v12.10.0

• <bigint>

Presente solo quando bigint: true viene passato al metodo che genera l'oggetto. Il timestamp che indica l'ultima volta che si è acceduto a questo file espresso in nanosecondi dall'epoca POSIX.

stats.mtimeNs

Aggiunto in: v12.10.0

• <bigint>

Presente solo quando bigint: true viene passato nel metodo che genera l'oggetto. Il timestamp che indica l'ultima volta che questo file è stato modificato espresso in nanosecondi dall'Epoca POSIX.

stats.ctimeNs

Aggiunto in: v12.10.0

• <bigint>

Presente solo quando bigint: true viene passato nel metodo che genera l'oggetto. Il timestamp che indica l'ultima volta che lo stato del file è stato modificato espresso in nanosecondi dall'Epoca POSIX.

stats.birthtimeNs

Aggiunto in: v12.10.0

• <bigint>

Presente solo quando bigint: true viene passato nel metodo che genera l'oggetto. Il timestamp che indica il tempo di creazione di questo file espresso in nanosecondi dall'Epoca POSIX.

stats.atime

Aggiunto in: v0.11.13

• <Date>

Il timestamp che indica l'ultima volta che questo file è stato acceduto.

stats.mtime

Aggiunto in: v0.11.13

• <Date>

Il timestamp che indica l'ultima volta che questo file è stato modificato.

stats.ctime

Aggiunto in: v0.11.13

• <Date>

Il timestamp che indica l'ultima volta che lo stato del file è stato modificato.

stats.birthtime

Aggiunto in: v0.11.13

• <Date>

Il timestamp che indica il tempo di creazione di questo file.

Valori temporali di Stat

Le proprietà atimeMs, mtimeMs, ctimeMs, birthtimeMs sono valori numerici che contengono i tempi corrispondenti in millisecondi. La loro precisione è specifica della piattaforma. Quando bigint: true viene passato nel metodo che genera l'oggetto, le proprietà saranno bigint, altrimenti saranno numeri.

Le proprietà atimeNs, mtimeNs, ctimeNs, birthtimeNs sono bigint che contengono i tempi corrispondenti in nanosecondi. Sono presenti solo quando bigint: true viene passato nel metodo che genera l'oggetto. La loro precisione è specifica della piattaforma.

atime, mtime, ctime e birthtime sono rappresentazioni alternative come oggetto Date dei vari tempi. I valori Date e numerici non sono collegati. Assegnare un nuovo valore numerico o mutare il valore Date non si rifletterà nella corrispondente rappresentazione alternativa.

I tempi nell'oggetto stat hanno la seguente semantica:

• atime "Tempo di accesso": Tempo in cui i dati del file sono stati acceduti l'ultima volta. Modificato dalle chiamate di sistema mknod(2), utimes(2) e read(2).
• mtime "Tempo di modifica": Tempo in cui i dati del file sono stati modificati l'ultima volta. Modificato dalle chiamate di sistema mknod(2), utimes(2) e write(2).
• ctime "Tempo di modifica": Tempo in cui lo stato del file è stato modificato l'ultima volta (modifica dei dati dell'inode). Modificato dalle chiamate di sistema chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) e write(2).
• birthtime "Tempo di creazione": Tempo di creazione del file. Impostato una sola volta quando il file viene creato. Sui file system in cui birthtime non è disponibile, questo campo può invece contenere ctime o 1970-01-01T00:00Z (ovvero, il timestamp Unix epoch 0). In questo caso questo valore potrebbe essere maggiore di atime o mtime. Su Darwin e altre varianti FreeBSD, impostato anche se atime è impostato esplicitamente su un valore precedente all'attuale birthtime utilizzando la chiamata di sistema utimes(2).

Prima di Node.js 0.12, ctime conteneva birthtime sui sistemi Windows. A partire dalla 0.12, ctime non è "tempo di creazione" e sui sistemi Unix non lo è mai stato.

Classe: fs.StatFs

Aggiunto in: v19.6.0, v18.15.0

Fornisce informazioni su un file system montato.

Gli oggetti restituiti da fs.statfs() e dalla sua controparte sincrona sono di questo tipo. Se bigint nelle options passate a questi metodi è true, i valori numerici saranno bigint anziché number.

StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

Versione bigint:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Blocchi liberi disponibili per gli utenti non privilegiati.

statfs.bfree

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Blocchi liberi nel file system.

statfs.blocks

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Totale blocchi dati nel file system.

statfs.bsize

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Dimensione ottimale del blocco di trasferimento.

statfs.ffree

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Nodi file liberi nel file system.

statfs.files

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Numero totale di nodi file nel file system.

statfs.type

Aggiunto in: v19.6.0, v18.15.0

• <number> | <bigint>

Tipo di file system.

Classe: fs.WriteStream

Aggiunto in: v0.1.93

• Estende <stream.Writable>

Le istanze di <fs.WriteStream> vengono create e restituite utilizzando la funzione fs.createWriteStream().

Evento: 'close'

Aggiunto in: v0.1.93

Emesso quando il descrittore del file sottostante di <fs.WriteStream> è stato chiuso.

Evento: 'open'

Aggiunto in: v0.1.93

• fd <integer> Descrittore del file intero utilizzato da <fs.WriteStream>.

Emesso quando il file di <fs.WriteStream> è aperto.

Evento: 'ready'

Aggiunto in: v9.11.0

Emesso quando <fs.WriteStream> è pronto per essere utilizzato.

Viene attivato immediatamente dopo 'open'.

writeStream.bytesWritten

Aggiunto in: v0.4.7

Il numero di byte scritti finora. Non include i dati ancora in coda per la scrittura.

writeStream.close([callback])

Aggiunto in: v0.9.4

• callback <Function>
  • err <Error>

Chiude writeStream. Accetta facoltativamente una callback che verrà eseguita una volta che writeStream è chiuso.

writeStream.path

Aggiunto in: v0.1.93

Il percorso del file su cui lo stream sta scrivendo, come specificato nel primo argomento di fs.createWriteStream(). Se path viene passato come stringa, allora writeStream.path sarà una stringa. Se path viene passato come <Buffer>, allora writeStream.path sarà un <Buffer>.

writeStream.pending

Aggiunto in: v11.2.0

• <boolean>

Questa proprietà è true se il file sottostante non è stato ancora aperto, cioè prima che venga emesso l'evento 'ready'.

fs.constants

• <Object>

Restituisce un oggetto contenente costanti comunemente usate per le operazioni del file system.

Costanti FS

Le seguenti costanti vengono esportate da fs.constants e fsPromises.constants.

Non tutte le costanti saranno disponibili su ogni sistema operativo; questo è particolarmente importante per Windows, dove molte delle definizioni specifiche POSIX non sono disponibili. Per applicazioni portabili si raccomanda di verificarne la presenza prima dell'uso.

Per usare più di una costante, usare l'operatore OR bit a bit |.

Esempio:

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) => {
  // ...
})

Costanti di accesso ai file

Le seguenti costanti sono destinate all'uso come parametro mode passato a fsPromises.access(), fs.access() e fs.accessSync().

Costante	Descrizione
F_OK	Flag che indica che il file è visibile al processo chiamante. Questo è utile per determinare se un file esiste, ma non dice nulla sui permessi rwx. Valore predefinito se non viene specificata alcuna modalità.
R_OK	Flag che indica che il file può essere letto dal processo chiamante.
W_OK	Flag che indica che il file può essere scritto dal processo chiamante.
X_OK	Flag che indica che il file può essere eseguito dal processo chiamante. Questo non ha effetto su Windows (si comporterà come fs.constants.F_OK).

Le definizioni sono disponibili anche su Windows.

Costanti per la copia di file

Le seguenti costanti sono destinate all'uso con fs.copyFile().

Costante	Descrizione
COPYFILE_EXCL	Se presente, l'operazione di copia fallirà con un errore se il percorso di destinazione esiste già.
COPYFILE_FICLONE	Se presente, l'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma sottostante non supporta il copy-on-write, viene utilizzato un meccanismo di copia di fallback.
COPYFILE_FICLONE_FORCE	Se presente, l'operazione di copia tenterà di creare un reflink copy-on-write. Se la piattaforma sottostante non supporta il copy-on-write, l'operazione fallirà con un errore.

Le definizioni sono disponibili anche su Windows.

Costanti per l'apertura di file

Le seguenti costanti sono destinate all'uso con fs.open().

Costante	Descrizione
O_RDONLY	Flag che indica di aprire un file in sola lettura.
O_WRONLY	Flag che indica di aprire un file in sola scrittura.
O_RDWR	Flag che indica di aprire un file in lettura e scrittura.
O_CREAT	Flag che indica di creare il file se non esiste già.
O_EXCL	Flag che indica che l'apertura di un file dovrebbe fallire se il flag O_CREAT è impostato e il file esiste già.
O_NOCTTY	Flag che indica che se il percorso identifica un dispositivo terminale, l'apertura del percorso non farà sì che quel terminale diventi il terminale di controllo per il processo (se il processo non ne ha già uno).
O_TRUNC	Flag che indica che se il file esiste ed è un file regolare, e il file viene aperto correttamente per l'accesso in scrittura, la sua lunghezza deve essere troncata a zero.
O_APPEND	Flag che indica che i dati verranno aggiunti alla fine del file.
O_DIRECTORY	Flag che indica che l'apertura dovrebbe fallire se il percorso non è una directory.
O_NOATIME	Flag che indica che gli accessi in lettura al file system non comporteranno più un aggiornamento delle informazioni atime associate al file. Questo flag è disponibile solo sui sistemi operativi Linux.
O_NOFOLLOW	Flag che indica che l'apertura dovrebbe fallire se il percorso è un collegamento simbolico.
O_SYNC	Flag che indica che il file viene aperto per I/O sincronizzato con operazioni di scrittura in attesa dell'integrità del file.
O_DSYNC	Flag che indica che il file viene aperto per I/O sincronizzato con operazioni di scrittura in attesa dell'integrità dei dati.
O_SYMLINK	Flag che indica di aprire il collegamento simbolico stesso anziché la risorsa a cui punta.
O_DIRECT	Quando impostato, verrà fatto un tentativo per ridurre al minimo gli effetti di caching dell'I/O del file.
O_NONBLOCK	Flag che indica di aprire il file in modalità non bloccante quando possibile.
UV_FS_O_FILEMAP	Quando impostato, viene utilizzato un mapping di file in memoria per accedere al file. Questo flag è disponibile solo sui sistemi operativi Windows. Sugli altri sistemi operativi, questo flag viene ignorato.

Su Windows, sono disponibili solo O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY e UV_FS_O_FILEMAP.

Costanti del tipo di file

Le seguenti costanti sono destinate all'uso con la proprietà mode dell'oggetto <fs.Stats> per determinare il tipo di file.

Costante	Descrizione
S_IFMT	Maschera di bit utilizzata per estrarre il codice del tipo di file.
S_IFREG	Costante del tipo di file per un file normale.
S_IFDIR	Costante del tipo di file per una directory.
S_IFCHR	Costante del tipo di file per un file di dispositivo orientato ai caratteri.
S_IFBLK	Costante del tipo di file per un file di dispositivo orientato ai blocchi.
S_IFIFO	Costante del tipo di file per un FIFO/pipe.
S_IFLNK	Costante del tipo di file per un collegamento simbolico.
S_IFSOCK	Costante del tipo di file per un socket.

Su Windows, sono disponibili solo S_IFCHR, S_IFDIR, S_IFLNK, S_IFMT e S_IFREG.

Costanti della modalità file

Le seguenti costanti sono destinate all'uso con la proprietà mode dell'oggetto <fs.Stats> per determinare i permessi di accesso per un file.

Costante	Descrizione
S_IRWXU	Modalità file che indica leggibile, scrivibile ed eseguibile dal proprietario.
S_IRUSR	Modalità file che indica leggibile dal proprietario.
S_IWUSR	Modalità file che indica scrivibile dal proprietario.
S_IXUSR	Modalità file che indica eseguibile dal proprietario.
S_IRWXG	Modalità file che indica leggibile, scrivibile ed eseguibile dal gruppo.
S_IRGRP	Modalità file che indica leggibile dal gruppo.
S_IWGRP	Modalità file che indica scrivibile dal gruppo.
S_IXGRP	Modalità file che indica eseguibile dal gruppo.
S_IRWXO	Modalità file che indica leggibile, scrivibile ed eseguibile da altri.
S_IROTH	Modalità file che indica leggibile da altri.
S_IWOTH	Modalità file che indica scrivibile da altri.
S_IXOTH	Modalità file che indica eseguibile da altri.

Su Windows, sono disponibili solo S_IRUSR e S_IWUSR.

Note

Ordinamento delle operazioni basate su callback e promesse

Poiché vengono eseguite in modo asincrono dal thread pool sottostante, non esiste un ordinamento garantito quando si utilizzano i metodi basati su callback o promesse.

Ad esempio, quanto segue è soggetto a errori perché l'operazione fs.stat() potrebbe completarsi prima dell'operazione fs.rename():

const fs = require('node:fs')

fs.rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  console.log('rinominato completato')
})
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err
  console.log(`statistiche: ${JSON.stringify(stats)}`)
})

È importante ordinare correttamente le operazioni attendendo i risultati di una prima di invocare l'altra:

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(`statistiche: ${JSON.stringify(stats)}`)
} catch (error) {
  console.error('si è verificato un errore:', 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(`statistiche: ${JSON.stringify(stats)}`)
  } catch (error) {
    console.error('si è verificato un errore:', error.message)
  }
})('/tmp/hello', '/tmp/world')

Oppure, quando si utilizzano le API callback, spostare la chiamata fs.stat() nel callback dell'operazione fs.rename():

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(`statistiche: ${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(`statistiche: ${JSON.stringify(stats)}`)
  })
})

Percorsi dei file

La maggior parte delle operazioni fs accettano percorsi di file che possono essere specificati sotto forma di stringa, un oggetto <Buffer> o un oggetto <URL> utilizzando il protocollo file:.

Percorsi di stringhe

I percorsi di stringhe vengono interpretati come sequenze di caratteri UTF-8 che identificano il nome del file assoluto o relativo. I percorsi relativi verranno risolti in relazione alla directory di lavoro corrente come determinato chiamando process.cwd().

Esempio di utilizzo di un percorso assoluto su POSIX:

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

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // Fai qualcosa con il file
} finally {
  await fd?.close()
}

Esempio di utilizzo di un percorso relativo su POSIX (relativo a process.cwd()):

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

let fd
try {
  fd = await open('file.txt', 'r')
  // Fai qualcosa con il file
} finally {
  await fd?.close()
}

Percorsi di URL di file

Aggiunto in: v7.6.0

Per la maggior parte delle funzioni del modulo node:fs, l'argomento path o filename può essere passato come oggetto <URL> utilizzando il protocollo file:.

import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

Gli URL file: sono sempre percorsi assoluti.

Considerazioni specifiche per la piattaforma

Su Windows, gli <URL> file: con un nome host vengono convertiti in percorsi UNC, mentre gli <URL> file: con lettere di unità vengono convertiti in percorsi assoluti locali. Gli <URL> file: senza nome host e senza lettera di unità genereranno un errore:

import { readFileSync } from 'node:fs'
// Su Windows:

// - Gli URL di file WHATWG con nome host si convertono in percorsi UNC
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - Gli URL di file WHATWG con lettere di unità si convertono in percorsi assoluti
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - Gli URL di file WHATWG senza nome host devono avere una lettera di unità
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]: Il percorso URL del file deve essere assoluto

Gli <URL> file: con lettere di unità devono usare : come separatore subito dopo la lettera di unità. L'uso di un altro separatore genererà un errore.

Su tutte le altre piattaforme, gli <URL> file: con un nome host non sono supportati e genereranno un errore:

import { readFileSync } from 'node:fs'
// Su altre piattaforme:

// - Gli URL di file WHATWG con nome host non sono supportati
// file://hostname/p/a/t/h/file => genera un errore!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: deve essere assoluto

// - Gli URL di file WHATWG si convertono in percorsi assoluti
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

Un <URL> file: che ha caratteri barra codificati genererà un errore su tutte le piattaforme:

import { readFileSync } from 'node:fs'

// Su 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]: Il percorso URL del file non deve includere caratteri \ o / codificati */

// Su 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]: Il percorso URL del file non deve includere caratteri / codificati */

Su Windows, gli <URL> file: che hanno una barra rovesciata codificata genereranno un errore:

import { readFileSync } from 'node:fs'

// Su Windows
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: Il percorso URL del file non deve includere caratteri \ o / codificati */

Percorsi buffer

I percorsi specificati utilizzando un <Buffer> sono utili principalmente su alcuni sistemi operativi POSIX che trattano i percorsi dei file come sequenze di byte opache. Su tali sistemi, è possibile che un singolo percorso di file contenga sottosequenze che utilizzano più codifiche di caratteri. Come con i percorsi stringa, i percorsi <Buffer> possono essere relativi o assoluti:

Esempio di utilizzo di un percorso assoluto su 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')
  // Fai qualcosa con il file
} finally {
  await fd?.close()
}

Directory di lavoro per unità su Windows

Su Windows, Node.js segue il concetto di directory di lavoro per unità. Questo comportamento può essere osservato quando si utilizza un percorso di unità senza barra rovesciata. Ad esempio fs.readdirSync('C:\\') può potenzialmente restituire un risultato diverso da fs.readdirSync('C:'). Per ulteriori informazioni, consultare questa pagina MSDN.

Descrittori di file

Sui sistemi POSIX, per ogni processo, il kernel mantiene una tabella di file e risorse attualmente aperti. A ogni file aperto viene assegnato un semplice identificatore numerico chiamato descrittore di file. A livello di sistema, tutte le operazioni del file system utilizzano questi descrittori di file per identificare e tenere traccia di ogni file specifico. I sistemi Windows utilizzano un meccanismo diverso ma concettualmente simile per tenere traccia delle risorse. Per semplificare le cose per gli utenti, Node.js astrae le differenze tra i sistemi operativi e assegna a tutti i file aperti un descrittore di file numerico.

I metodi basati su callback fs.open() e sincrono fs.openSync() aprono un file e allocano un nuovo descrittore di file. Una volta allocato, il descrittore di file può essere utilizzato per leggere dati da, scrivere dati in o richiedere informazioni sul file.

I sistemi operativi limitano il numero di descrittori di file che possono essere aperti in un dato momento, quindi è fondamentale chiudere il descrittore quando le operazioni sono state completate. In caso contrario, si verificherà una perdita di memoria che alla fine causerà l'arresto anomalo di un'applicazione.

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
      }

      // usa stat

      closeFd(fd)
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

Le API basate su promise utilizzano un oggetto <FileHandle> al posto del descrittore di file numerico. Questi oggetti sono gestiti meglio dal sistema per garantire che le risorse non vengano perse. Tuttavia, è comunque necessario che vengano chiusi al termine delle operazioni:

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

let file
try {
  file = await open('/open/some/file.txt', 'r')
  const stat = await file.stat()
  // usa stat
} finally {
  await file.close()
}

Utilizzo del pool di thread

Tutte le API di callback e basate su promesse del file system (con l'eccezione di fs.FSWatcher()) utilizzano il pool di thread di libuv. Questo può avere implicazioni inattese e negative sulle prestazioni per alcune applicazioni. Fare riferimento alla documentazione di UV_THREADPOOL_SIZE per ulteriori informazioni.

Flag del file system

I seguenti flag sono disponibili ovunque l'opzione flag accetti una stringa.

• 'a': Apre il file per l'aggiunta. Il file viene creato se non esiste.
• 'ax': Come 'a', ma restituisce un errore se il percorso esiste.
• 'a+': Apre il file per la lettura e l'aggiunta. Il file viene creato se non esiste.
• 'ax+': Come 'a+', ma restituisce un errore se il percorso esiste.
• 'as': Apre il file per l'aggiunta in modalità sincrona. Il file viene creato se non esiste.
• 'as+': Apre il file per la lettura e l'aggiunta in modalità sincrona. Il file viene creato se non esiste.
• 'r': Apre il file per la lettura. Si verifica un'eccezione se il file non esiste.
• 'rs': Apre il file per la lettura in modalità sincrona. Si verifica un'eccezione se il file non esiste.
• 'r+': Apre il file per la lettura e la scrittura. Si verifica un'eccezione se il file non esiste.
• 'rs+': Apre il file per la lettura e la scrittura in modalità sincrona. Istruisce il sistema operativo a bypassare la cache locale del file system. Ciò è principalmente utile per aprire file su montaggi NFS poiché consente di saltare la cache locale potenzialmente obsoleta. Ha un impatto molto reale sulle prestazioni I/O, quindi l'utilizzo di questo flag non è raccomandato a meno che non sia necessario. Ciò non trasforma fs.open() o fsPromises.open() in una chiamata bloccante sincrona. Se si desidera un'operazione sincrona, è necessario utilizzare qualcosa come fs.openSync().
• 'w': Apre il file per la scrittura. Il file viene creato (se non esiste) o troncato (se esiste).
• 'wx': Come 'w', ma restituisce un errore se il percorso esiste.
• 'w+': Apre il file per la lettura e la scrittura. Il file viene creato (se non esiste) o troncato (se esiste).
• 'wx+': Come 'w+', ma restituisce un errore se il percorso esiste.

flag può anche essere un numero come documentato da open(2); costanti comunemente usate sono disponibili da fs.constants. Su Windows, i flag vengono tradotti nei loro equivalenti dove applicabile, ad esempio O_WRONLY in FILE_GENERIC_WRITE o O_EXCL|O_CREAT in CREATE_NEW, come accettato da CreateFileW.

Il flag esclusivo 'x' (flag O_EXCL in open(2)) fa sì che l'operazione restituisca un errore se il percorso esiste già. Su POSIX, se il percorso è un collegamento simbolico, l'utilizzo di O_EXCL restituisce un errore anche se il collegamento è a un percorso che non esiste. Il flag esclusivo potrebbe non funzionare con i file system di rete.

Su Linux, le scritture posizionali non funzionano quando il file viene aperto in modalità di aggiunta. Il kernel ignora l'argomento della posizione e aggiunge sempre i dati alla fine del file.

La modifica di un file anziché la sua sostituzione potrebbe richiedere che l'opzione flag sia impostata su 'r+' anziché sul valore predefinito 'w'.

Il comportamento di alcuni flag è specifico della piattaforma. Pertanto, l'apertura di una directory su macOS e Linux con il flag 'a+', come nell'esempio seguente, restituirà un errore. Al contrario, su Windows e FreeBSD, verrà restituito un descrittore di file o un FileHandle.

// macOS e Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: operazione illegale su una directory, open <directory>]
})

// Windows e FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
})

Su Windows, l'apertura di un file nascosto esistente utilizzando il flag 'w' (tramite fs.open(), fs.writeFile() o fsPromises.open()) non riuscirà con EPERM. I file nascosti esistenti possono essere aperti per la scrittura con il flag 'r+'.

È possibile utilizzare una chiamata a fs.ftruncate() o filehandle.truncate() per reimpostare il contenuto del file.