Система файлов

Исходный код: lib/fs.js

Модуль fs позволяет взаимодействовать с файловой системой, моделируя стандартные функции POSIX.

Для использования этого модуля:

const fs = require('fs');

Все операции с файловой системой имеют синхронные, основанные на обратных вызовах и на основе обещаний формы.

Синхронный пример

Синхронная форма блокирует цикл событий Node.js и дальнейшее выполнение JavaScript до завершения операции. Исключение выбрасывается немедленно и может быть обработано с помощью try…catch, или может быть допущено до обработки вверх по стеку.

const fs = require('fs');

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

Пример с обратным вызовом

Форма обратного вызова принимает функцию обратного вызова завершения в качестве последнего аргумента и вызывает операцию асинхронно. Аргументы, передаваемые в обратный вызов завершения, зависят от метода, но первый аргумент всегда зарезервирован для исключения. Если операция завершилась успешно, то первый аргумент - null или undefined.

const fs = require('fs');

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

Пример с обещанием

Операции на основе обещаний возвращают Promise, который разрешается, когда асинхронная операция завершается.

const fs = require('fs').promises;

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

Порядок операций с обратными вызовами и обещаниями

Нет гарантированного порядка при использовании методов обратного вызова или на основе обещаний. Например, следующее подвержено ошибкам, потому что операция fs.stat() может завершиться до операции fs.rename().

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err;
  console.log(`stats: ${JSON.stringify(stats)}`);
});

Чтобы правильно упорядочить операции, переместите вызов fs.stat() в обратный вызов операции fs.rename().

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  fs.stat('/tmp/world', (err, stats) => {
    if (err) throw err;
    console.log(`stats: ${JSON.stringify(stats)}`);
  });
});

Или используйте API на основе обещаний:

const fs = require('fs').promises;

(async function(from, to) {
  try {
    await fs.rename(from, to);
    const stats = await fs.stat(to);
    console.log(`stats: ${JSON.stringify(stats)}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello', '/tmp/world');

Пути к файлам

Большинство fs операций принимают пути к файлам, которые могут быть указаны в виде строки, Buffer или объекта URL с использованием протокола file:.

Пути в виде строк интерпретируются как последовательности символов UTF-8, идентифицирующие абсолютный или относительный путь к файлу. Относительные пути будут разрешаться относительно текущей рабочей директории, как определяется вызовом process.cwd().

Пример использования абсолютного пути в POSIX:

const fs = require('fs');

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

Пример использования относительного пути в POSIX (относительно process.cwd()):

fs.open('file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

Пути, указанные с помощью Buffer, полезны в основном на определенных операционных системах POSIX, которые рассматривают пути к файлам как непрозрачные последовательности байтов. В таких системах возможно, что один путь к файлу содержит подпоследовательности, использующие несколько кодировок символов. Как и в случае с путями в виде строк, пути в виде Buffer могут быть относительными или абсолютными:

Пример использования абсолютного пути в POSIX:

fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

В Windows Node.js следует концепции рабочей директории на диск. Это поведение можно наблюдать при использовании пути к диску без обратного слэша. Например, fs.readdirSync('C:\\') потенциально может возвращать другой результат, чем fs.readdirSync('C:') . Для получения дополнительной информации см. эту страницу MSDN.

Поддержка объектов URL

Для большинства функций модуля fs, аргумент path или filename может быть передан как объект WHATWG URL. Поддерживаются только объекты URL, использующие протокол file:.

const fs = require('fs');
const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

file: URL — это всегда абсолютные пути.

Использование объектов WHATWG URL может привести к поведению, зависящему от платформы.

В Windows URL с именем хоста преобразуются в UNC-пути, а URL с буквами дисков преобразуются в локальные абсолютные пути. file: URL без имени хоста и буквы диска приведут к ошибке:

// On Windows :

// - WHATWG file URLs with hostname convert to UNC path
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - WHATWG file URLs with drive letters convert to absolute path
// file:///C:/tmp/hello => C:\tmp\hello
fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - WHATWG file URLs without hostname must have a drive letters
fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));
fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

file: URL с буквами дисков должны использовать : в качестве разделителя сразу после буквы диска. Использование другого разделителя приведет к ошибке.

На всех остальных платформах URL с именем хоста не поддерживаются и приведут к ошибке:

// On other platforms:

// - WHATWG file URLs with hostname are unsupported
// file://hostname/p/a/t/h/file => throw!
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG file URLs convert to absolute path
// file:///tmp/hello => /tmp/hello
fs.readFileSync(new URL('file:///tmp/hello'));

URL с закодированными символами слэша приведут к ошибке на всех платформах:

// On Windows
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

// On POSIX
fs.readFileSync(new URL('file:///p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
/ characters */

В Windows URL с закодированными обратными слешами приведут к ошибке:

// On Windows
fs.readFileSync(new URL('file:///C:/path/%5C'));
fs.readFileSync(new URL('file:///C:/path/%5c'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

Дескрипторы файлов

В системах POSIX для каждого процесса ядро поддерживает таблицу открытых файлов и ресурсов. Каждый открытый файл получает простой числовой идентификатор, называемый дескриптором файла. На уровне системы все операции с файловой системой используют эти дескрипторы для идентификации и отслеживания каждого конкретного файла. Системы Windows используют другой, но концептуально аналогичный механизм для отслеживания ресурсов. Для упрощения работы пользователей Node.js абстрагирует конкретные различия между операционными системами и назначает всем открытым файлам числовой дескриптор файла.

Метод fs.open() используется для выделения нового дескриптора файла. После выделения дескриптор файла может быть использован для чтения данных из файла, записи данных в файл или запроса информации о файле.

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.fstat(fd, (err, stat) => {
    if (err) throw err;
    // use stat

    // always close the file descriptor!
    fs.close(fd, (err) => {
      if (err) throw err;
    });
  });
});

Большинство операционных систем ограничивают количество открытых дескрипторов файлов в любой момент, поэтому крайне важно закрывать дескриптор после завершения операций. Невыполнение этого приведет к утечке памяти, которая в конечном итоге приведет к зависанию приложения.

Использование потоковой очереди

Все API файловой системы, кроме fs.FSWatcher(), и те, которые явно синхронные, используют пул потоков libuv, что может иметь неожиданные и негативные последствия для производительности некоторых приложений. См. документацию UV_THREADPOOL_SIZE для получения дополнительной информации.

Класс: fs.Dir

Класс, представляющий поток каталога.

Создается с помощью fs.opendir(), fs.opendirSync() или fsPromises.opendir().

const fs = require('fs');

async function print(path) {
  const dir = await fs.promises.opendir(path);
  for await (const dirent of dir) {
    console.log(dirent.name);
  }
}
print('./').catch(console.error);

dir.close()

• Возвращает: <Promise>

Асинхронно закрывает базовый дескриптор ресурса каталога. Следующие чтения приведут к ошибкам.

Возвращается обещание, которое разрешится после закрытия ресурса.

dir.close(callback)

• callback <Функция>
  • err <Ошибка>

Асинхронно закрывает базовый дескриптор ресурса каталога. Следующие чтения приведут к ошибкам.

Обратный вызов будет вызван после закрытия дескриптора ресурса.

dir.closeSync()

Синхронно закрывает базовый дескриптор ресурса каталога. Следующие чтения приведут к ошибкам.

dir.path

• <строка>

Только для чтения путь к этому каталогу, предоставленный в fs.opendir(), fs.opendirSync() или fsPromises.opendir().

dir.read()

• Возвращает: <Promise> содержащее <fs.Dirent> | <null>

Асинхронно читает следующую запись каталога с помощью readdir(3) как fs.Dirent.

После завершения чтения возвращается обещание, которое разрешится с fs.Dirent или <null>, если больше нет записей каталога для чтения.

Записи каталога, возвращаемые этой функцией, не упорядочены, так как это предоставлено базовыми механизмами каталога операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут или не могут быть включены в результаты итерации.

dir.read(callback)

• callback <Функция>
  • err <Ошибка>
  • dirent <fs.Dirent> | <null>

Асинхронно читает следующую запись каталога с помощью readdir(3) как fs.Dirent.

После завершения чтения обратный вызов будет вызван с fs.Dirent или <null>, если больше нет записей каталога для чтения.

Записи каталога, возвращаемые этой функцией, не упорядочены, так как это предоставлено базовыми механизмами каталога операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут или не могут быть включены в результаты итерации.

dir.readSync()

• Возвращает: <fs.Dirent> | <null>

Синхронно прочитайте следующую запись каталога с помощью readdir(3) в виде fs.Dirent.

Если больше записей каталога для чтения нет, будет возвращено null.

Записи каталога, возвращаемые этой функцией, не упорядочены, как предоставляет подлежащая механизмам каталогов операционная система. Записи, добавленные или удалённые во время итерации по каталогу, могут или не могут быть включены в результаты итерации.

dir[Symbol.asyncIterator]()

• Возвращает: <AsyncIterator> объекта <fs.Dirent>

Асинхронно итерируется по каталогу с помощью readdir(3) до тех пор, пока все записи не будут прочитаны.

Записи, возвращаемые асинхронным итератором, всегда являются объектом fs.Dirent. Случай null из dir.read() обрабатывается внутри.

См. пример в fs.Dir.

Записи каталога, возвращаемые этим итератором, не упорядочены, как предоставляет подлежащая механизмам каталогов операционная система. Записи, добавленные или удалённые во время итерации по каталогу, могут или не могут быть включены в результаты итерации.

Класс: fs.Dirent

Представление записи каталога, которая может быть файлом или подкаталогом внутри каталога, как возвращается при чтении из fs.Dir. Запись каталога — это сочетание пар имя файла и тип файла.

Кроме того, когда fs.readdir() или fs.readdirSync() вызываются с параметром withFileTypes установленным в значение true, результирующий массив заполняется объектами fs.Dirent, а не строками или Buffers.

dirent.isBlockDevice()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает блок-устройство.

dirent.isCharacterDevice()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает символьное устройство.

dirent.isDirectory()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает директорию файловой системы.

dirent.isFIFO()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает очередь FIFO (первым вошел — первым вышел).

dirent.isFile()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает обычный файл.

dirent.isSocket()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает сокет.

dirent.isSymbolicLink()

• Возвращает: <boolean>

Возвращает true если объект fs.Dirent описывает символическую ссылку.

dirent.name

• <string> | <Buffer>

Имя файла, на который ссылается этот объект fs.Dirent. Тип этого значения определяется значением options.encoding переданным в fs.readdir() или fs.readdirSync().

Класс: fs.FSWatcher

• Расширяет <EventEmitter>

Успешное вызов метода fs.watch() вернёт новый объект fs.FSWatcher.

Все объекты fs.FSWatcher излучают событие 'change' всякий раз, когда изменяется конкретный наблюдаемый файл.

Событие: 'change'

• eventType <string> Тип события изменения, которое произошло
• filename <string> | <Buffer> Имя файла, который изменился (если это применимо/доступно)

Излучается, когда что-то меняется в наблюдаемой директории или файле. Более подробная информация в fs.watch().

Аргумент filename может не быть предоставлен в зависимости от поддержки операционной системы. Если filename предоставлен, он будет предоставлен как Buffer, если fs.watch() вызван с параметром encoding установленным в 'buffer', в противном случае filename будет строкой UTF-8.

// Example when handled through fs.watch() listener
fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename);
    // Prints: <Buffer ...>
  }
});

Событие: 'close'

Излучается, когда наблюдатель прекращает отслеживание изменений. Закрытый объект fs.FSWatcher больше не используется в обработчике событий.

Событие: 'error'

• error <Error>

Излучается, когда возникает ошибка во время наблюдения за файлом. Объект fs.FSWatcher с ошибкой больше не используется в обработчике событий.

watcher.close()

Прекращение наблюдения за изменениями в указанном fs.FSWatcher. После остановки объект fs.FSWatcher больше не может быть использован.

watcher.ref()

• Возвращает: <fs.FSWatcher>

По запросу цикл событий Node.js не завершается, пока активен FSWatcher. Вызов watcher.ref() несколько раз не имеет эффекта.

По умолчанию все объекты FSWatcher «ссылочные», поэтому обычно нет необходимости вызывать watcher.ref() , если ранее не был вызван watcher.unref().

watcher.unref()

• Возвращает: <fs.FSWatcher>

При вызове активный объект FSWatcher не потребует поддержания активного цикла событий Node.js. Если нет другой активности, удерживающей цикл событий, процесс может выйти, прежде чем будет вызван обратный вызов объекта FSWatcher. Вызов watcher.unref() несколько раз не имеет эффекта.

Класс: fs.StatWatcher

• Расширяет <EventEmitter>

Успешный вызов метода fs.watchFile() вернёт новый объект fs.StatWatcher.

watcher.ref()

• Возвращает: <fs.StatWatcher>

По запросу цикл событий Node.js не завершается, пока активен StatWatcher. Вызов watcher.ref() несколько раз не имеет эффекта.

По умолчанию все объекты StatWatcher «ссылочные», поэтому обычно нет необходимости вызывать watcher.ref() , если ранее не был вызван watcher.unref().

watcher.unref()

• Возвращает: <fs.StatWatcher>

При вызове активный объект StatWatcher не потребует поддержания активного цикла событий Node.js. Если нет другой активности, удерживающей цикл событий, процесс может выйти, прежде чем будет вызван обратный вызов объекта StatWatcher. Вызов watcher.unref() несколько раз не имеет эффекта.

Класс: fs.ReadStream

• Расширяет: <stream.Readable>

Экземпляры fs.ReadStream создаются и возвращаются с помощью функции fs.createReadStream().

Событие: 'close'

Излучается, когда дескриптор файла fs.ReadStream нижележащего файла был закрыт.

Событие: 'open'

• fd <integer> Целое число дескриптора файла, используемого потоком ReadStream.

Излучается, когда дескриптор файла потока fs.ReadStream был открыт.

Событие: 'ready'

Излучается, когда fs.ReadStream готов к использованию.

Излучается сразу после 'open'.

readStream.bytesRead

• <number>

Количество байтов, прочитанных до настоящего момента.

readStream.path

• <string> | <Buffer>

Путь к файлу, из которого считывается поток, указанный в первом аргументе fs.createReadStream(). Если path передаётся как строка, то readStream.path будет строкой. Если path передаётся как Buffer, то readStream.path будет Buffer.

readStream.pending

• <boolean>

Это свойство равно true если базовый файл ещё не открыт, т.е. до того, как будет выпущен 'ready'.

Класс: fs.Stats

Объект fs.Stats предоставляет информацию о файле.

Объекты, возвращаемые fs.stat(), fs.lstat() и fs.fstat(), а также их синхронные аналоги, имеют этот тип. Если bigint в options методах установлено в true, числовые значения будут bigint вместо number, и объект будет содержать дополнительные свойства с наносекундной точностью, оканчивающиеся на Ns.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

bigint версия:

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

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает блочное устройство.

stats.isCharacterDevice()

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает символьное устройство.

stats.isDirectory()

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает каталог файловой системы.

stats.isFIFO()

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает канал FIFO (First-In-First-Out).

stats.isFile()

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает обычный файл.

stats.isSocket()

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает сокет.

stats.isSymbolicLink()

• Возвращает: <boolean>

Возвращает true если объект fs.Stats описывает символическую ссылку.

Этот метод допустим только при использовании fs.lstat().

stats.dev

• <number> | <bigint>

Числовой идентификатор устройства, содержащего файл.

stats.ino

• <number> | <bigint>

Номер узла файла (inode), специфичный для файловой системы.

stats.mode

• <number> | <bigint>

Битовое поле, описывающее тип и режим файла.

stats.nlink

• <number> | <bigint>

Количество жёстких ссылок на файл.

stats.uid

• <number> | <bigint>

Числовой идентификатор пользователя (POSIX), владеющего файлом.

stats.gid

• <number> | <bigint>

Числовой идентификатор группы (POSIX), владеющей файлом.

stats.rdev

• <number> | <bigint>

Числовой идентификатор устройства, если файл представляет собой устройство.

stats.size

• <number> | <bigint>

Размер файла в байтах.

stats.blksize

• <number> | <bigint>

Размер блока файловой системы для операций ввода-вывода.

stats.blocks

• <number> | <bigint>

Количество блоков, выделенных для этого файла.

stats.atimeMs

• <number> | <bigint>

Отметка времени последнего доступа к файлу в миллисекундах с эпохи POSIX.

stats.mtimeMs

• <number> | <bigint>

Отметка времени последнего изменения файла в миллисекундах с эпохи POSIX.

stats.ctimeMs

• <number> | <bigint>

Отметка времени последнего изменения статуса файла в миллисекундах с эпохи POSIX.

stats.birthtimeMs

• <number> | <bigint>

Отметка времени создания файла в миллисекундах с эпохи POSIX.

stats.atimeNs

• <bigint>

Присутствует только когда bigint: true передаётся в метод, генерирующий объект. Отметка времени последнего доступа к файлу в наносекундах с эпохи POSIX.

stats.mtimeNs

• <bigint>

Присутствует только тогда, когда bigint: true передается в метод, генерирующий объект. Отметка времени, указывающая последний раз, когда этот файл был изменён, выражена в наносекундах с момента эпохи POSIX.

stats.ctimeNs

• <bigint>

Присутствует только тогда, когда bigint: true передается в метод, генерирующий объект. Отметка времени, указывающая последний раз, когда статус файла был изменён, выражена в наносекундах с момента эпохи POSIX.

stats.birthtimeNs

• <bigint>

Присутствует только тогда, когда bigint: true передается в метод, генерирующий объект. Отметка времени, указывающая время создания этого файла, выражена в наносекундах с момента эпохи POSIX.

stats.atime

• <Date>

Отметка времени, указывающая последний раз, когда этот файл был открыт.

stats.mtime

• <Date>

Отметка времени, указывающая последний раз, когда этот файл был изменён.

stats.ctime

• <Date>

Отметка времени, указывающая последний раз, когда статус файла был изменён.

stats.birthtime

• <Date>

Отметка времени, указывающая время создания этого файла.

Значения времени stat

Свойства atimeMs, mtimeMs, ctimeMs, birthtimeMs — числовые значения, содержащие соответствующие временные метки в миллисекундах. Точность зависит от платформы. Когда bigint: true передаётся в метод, генерирующий объект, эти свойства будут bigints, в противном случае — числа.

Свойства atimeNs, mtimeNs, ctimeNs, birthtimeNs — bigints, содержащие соответствующие временные метки в наносекундах. Они присутствуют только когда bigint: true передаётся в метод, генерирующий объект. Точность зависит от платформы.

atime, mtime, ctime, и birthtime являются Date объект альтернативные представления различных временных меток. Значения Date и числовые значения не связаны. Присвоение нового числового значения или изменение значения Date не будет отражено в соответствующем альтернативном представлении.

Временные метки в объекте stat имеют следующие семантики:

• atime «Время доступа»: Время последнего доступа к данным файла. Изменяется системными вызовами mknod(2), utimes(2) и read(2).
• mtime «Время изменения»: Время последнего изменения данных файла. Изменяется системными вызовами mknod(2), utimes(2) и write(2).
• ctime «Время изменения статуса»: Время последнего изменения статуса файла (изменение данных узла). Изменяется системными вызовами chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) и write(2).
• birthtime «Время создания»: Время создания файла. Устанавливается один раз при создании файла. На файловых системах, где время создания недоступно, это поле может содержать ctime или 1970-01-01T00:00Z (то есть временную метку эпохи Unix 0). В этом случае это значение может быть больше atime или mtime. На Darwin и других вариантах FreeBSD, также устанавливается, если atime явно задано значением раньше текущего birthtime с помощью системного вызова utimes(2).

До Node.js 0.12, ctime содержал birthtime на системах Windows. С версии 0.12, ctime не является «временем создания», и на Unix-системах таковым никогда не был.

Класс: fs.WriteStream

• Расширяет <stream.Writable>

Экземпляры fs.WriteStream создаются и возвращаются с помощью функции fs.createWriteStream().

Событие: 'close'

Выдается, когда базовый дескриптор файла потока WriteStream был закрыт.

Событие: 'open'

• fd <целое> Целочисленный дескриптор файла, используемый потоком WriteStream.

Выдается, когда файл потока WriteStream открыт.

Событие: 'ready'

Выдаётся, когда поток fs.WriteStream готов к использованию.

Вызывается сразу после 'open'.

writeStream.bytesWritten

Количество байтов, записанных до сих пор. Не включает данные, которые всё ещё находятся в очереди на запись.

writeStream.path

Путь к файлу, в который записывается поток, указанный в первом аргументе функции fs.createWriteStream(). Если path передан как строка, то writeStream.path будет строкой. Если path передан как Buffer, то writeStream.path будет Buffer.

writeStream.pending

• <булево>

Это свойство равно true, если базовый файл ещё не открыт, т.е. до выдачи события 'ready'.

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

• path <строка> | <Буфер> | <URL>
• mode <целое> По умолчанию: fs.constants.F_OK
• callback <Функция>
  • err <Ошибка>

Проверяет права пользователя для файла или каталога, указанного в path. Аргумент mode — необязательное целое число, определяющее проверки доступности. См. Константы доступа к файлам для возможных значений mode. Возможна создание маски, состоящей из побитового ИЛИ двух или более значений (например, fs.constants.W_OK | fs.constants.R_OK).

Последний аргумент, callback, — функция обратного вызова, которая вызывается с возможным аргументом ошибки. Если любая проверка доступности завершается неудачно, аргумент ошибки будет объектом Error. Следующие примеры проверяют существование package.json и его читаемость или возможность записи.

const file = 'package.json';

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

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

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

// Check if the file exists in the current directory, and if it is writable.
fs.access(file, fs.constants.F_OK | fs.constants.W_OK, (err) => {
  if (err) {
    console.error(
      `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`);
  } else {
    console.log(`${file} exists, and it is writable`);
  }
});

Не используйте fs.access() для проверки доступности файла перед вызовом fs.open(), fs.readFile() или fs.writeFile(). Это приводит к гонке, так как другие процессы могут изменить состояние файла между этими вызовами. Вместо этого пользовательский код должен напрямую открывать/читать/записывать файл и обрабатывать ошибку, если файл недоступен.

запись (НЕ РЕКОМЕНДУЕТСЯ)

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

  fs.open('myfile', 'wx', (err, fd) => {
    if (err) throw err;
    writeMyData(fd);
  });
});

запись (РЕКОМЕНДУЕТСЯ)

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

    throw err;
  }

  writeMyData(fd);
});

чтение (НЕ РЕКОМЕНДУЕТСЯ)

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

    throw err;
  }

  fs.open('myfile', 'r', (err, fd) => {
    if (err) throw err;
    readMyData(fd);
  });
});

чтение (РЕКОМЕНДУЕТСЯ)

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

    throw err;
  }

  readMyData(fd);
});

Приведённые выше примеры с пометкой «не рекомендуется» проверяют доступность, а затем используют файл; примеры с пометкой «рекомендуется» лучше, так как они напрямую используют файл и обрабатывают ошибки, если таковые имеются.

В общем случае проверяйте доступность файла только в том случае, если файл не будет использоваться напрямую, например, когда его доступность является сигналом для другого процесса.

В Windows политики управления доступом (ACL) к каталогу могут ограничивать доступ к файлу или каталогу. Однако функция fs.access() не проверяет ACL и, следовательно, может сообщить, что путь доступен, даже если политика ACL запрещает пользователю чтение или запись.

fs.accessSync(path[, mode])

• path <строка> | <Буфер> | <URL>
• mode <целое число> По умолчанию: fs.constants.F_OK

Синхронно проверяет права пользователя для файла или каталога, указанного параметром path. Аргумент mode — это необязательное целое число, определяющее выполняемые проверки доступности. См. Константы доступа к файлам для возможных значений mode. Можно создать маску, используя побитовое ИЛИ двух или более значений (например, fs.constants.W_OK | fs.constants.R_OK).

Если любая из проверок доступности завершится неудачно, будет выброшено исключение Error. В противном случае метод вернёт undefined.

try {
  fs.accessSync('etc/passwd', fs.constants.R_OK | fs.constants.W_OK);
  console.log('can read/write');
} catch (err) {
  console.error('no access!');
}

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

• path <строка> | <Буфер> | <URL> | <число> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'a'.
• callback <Функция>
  • err <Ошибка>

Асинхронно добавляет данные в файл, создавая его, если он ещё не существует. data может быть строкой или Buffer.

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

Если options является строкой, то она определяет кодировку:

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

Параметр path может быть числовым дескриптором файла, открытым для добавления (с помощью fs.open() или fs.openSync()). Дескриптор файла не будет закрыт автоматически.

fs.open('message.txt', 'a', (err, fd) => {
  if (err) throw err;
  fs.appendFile(fd, 'data to append', 'utf8', (err) => {
    fs.close(fd, (err) => {
      if (err) throw err;
    });
    if (err) throw err;
  });
});

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

• path <строка> | <Буфер> | <URL> | <число> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'a'.

Синхронно добавляет данные в файл, создавая его, если он ещё не существует. data может быть строкой или Buffer.

try {
  fs.appendFileSync('message.txt', 'data to append');
  console.log('The "data to append" was appended to file!');
} catch (err) {
  /* Handle the error */
}

Если options является строкой, то она определяет кодировку:

fs.appendFileSync('message.txt', 'data to append', 'utf8');

Параметр path может быть числовым дескриптором файла, открытым для добавления (с помощью fs.open() или fs.openSync()). Дескриптор файла не будет закрыт автоматически.

let fd;

try {
  fd = fs.openSync('message.txt', 'a');
  fs.appendFileSync(fd, 'data to append', 'utf8');
} catch (err) {
  /* Handle the error */
} finally {
  if (fd !== undefined)
    fs.closeSync(fd);
}

fs.chmod(path, mode, callback)

• path <строка> | <Буфер> | <URL>
• mode <строка> | <целое число>
• callback <Функция>
  • err <Ошибка>

Асинхронно изменяет права доступа к файлу. В обратный вызов не передаются никакие аргументы, кроме возможного исключения.

См. также: chmod(2).

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

Режимы файлов

Аргумент mode, используемый в методах fs.chmod() и fs.chmodSync(), является числовой маской, созданной с помощью логического ИЛИ следующих констант:

Более простой способ построения mode заключается в использовании последовательности из трёх восьмеричных цифр (например, 765). Левая цифра (7 в примере) определяет разрешения для владельца файла. Средняя цифра (6 в примере) определяет разрешения для группы. Правая цифра (5 в примере) определяет разрешения для других.

Например, восьмеричное значение 0o765 означает:

• Владелец может читать, записывать и выполнять файл.
• Группа может читать и записывать файл.
• Другие могут читать и выполнять файл.

При использовании чисел, где ожидаются режимы файлов, любое значение, большее 0o777, может привести к платформозависимому поведению, которое не гарантируется для согласованной работы. Поэтому константы, такие как S_ISVTX, S_ISGID или S_ISUID, не представлены в fs.constants.

Примечание: в Windows можно изменить только разрешение на запись, и различие между разрешениями группы, владельца или других не реализовано.

fs.chmodSync(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <строка> | <целое число>

Для получения подробной информации обратитесь к документации асинхронной версии этого API: fs.chmod().

См. также: chmod(2).

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

• path <строка> | <Буфер> | <URL>
• uid <целое число>
• gid <целое число>
• callback <Функция>
  • err <Ошибка>

Асинхронно изменяет владельца и группу файла. В обратный вызов завершения передаются только возможные исключения.

См. также: chown(2).

fs.chownSync(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое число>
• gid <целое число>

Синхронно изменяет владельца и группу файла. Возвращает undefined. Это синхронная версия fs.chown().

См. также: chown(2).

fs.close(fd, callback)

• fd <целое число>
• callback <Функция>
  • err <Ошибка>

Асинхронное закрытие close(2). В обратный вызов завершения передаются только возможные исключения.

Вызов fs.close() для любого файлового дескриптора (fd), который в данный момент используется в другой fs операции, может привести к неопределённому поведению.

fs.closeSync(fd)

• fd <целое число>

Синхронное закрытие close(2). Возвращает undefined.

Вызов fs.closeSync() для любого файлового дескриптора (fd), который в данный момент используется в другой fs операции, может привести к неопределённому поведению.

fs.constants

• <Объект>

Возвращает объект, содержащий часто используемые константы для операций с файловой системой. Определённые константы описаны в константы FS.

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

• src <строка> | <Буфер> | <URL> имя исходного файла для копирования
• dest <строка> | <Буфер> | <URL> имя файла назначения для копирования
• flags <число> модификаторы для операции копирования. По умолчанию: 0.
• callback <Функция>

Асинхронно копирует src в dest. По умолчанию, dest перезаписывается, если он уже существует. В функцию обратного вызова не передаются аргументы, кроме возможного исключения. Node.js не гарантирует атомарность операции копирования. Если ошибка возникает после того, как целевой файл был открыт для записи, Node.js попытается удалить целевой файл.

flags — это необязательное целое число, которое указывает поведение операции копирования. Можно создать маску, используя побитовое ИЛИ двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: Операция копирования завершится ошибкой, если dest уже существует.
• fs.constants.COPYFILE_FICLONE: Операция копирования попытается создать ссылку копирования с совместным использованием памяти. Если платформа не поддерживает копирование с совместным использованием памяти, будет использоваться резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать ссылку копирования с совместным использованием памяти. Если платформа не поддерживает копирование с совместным использованием памяти, операция завершится ошибкой.

const fs = require('fs');

// destination.txt will be created or overwritten by default.
fs.copyFile('source.txt', 'destination.txt', (err) => {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
});

Если третий аргумент является числом, то он задаёт flags:

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

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

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

• src <строка> | <Буфер> | <URL> имя исходного файла для копирования
• dest <строка> | <Буфер> | <URL> имя целевого файла для копирования
• flags <число> модификаторы для операции копирования. По умолчанию: 0.

Синхронно копирует src в dest. По умолчанию, dest перезаписывается, если он уже существует. Возвращает undefined. Node.js не гарантирует атомарность операции копирования. Если ошибка возникает после того, как целевой файл был открыт для записи, Node.js попытается удалить целевой файл.

flags — это необязательное целое число, которое указывает поведение операции копирования. Можно создать маску, используя побитовое ИЛИ двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: Операция копирования завершится ошибкой, если dest уже существует.
• fs.constants.COPYFILE_FICLONE: Операция копирования попытается создать ссылку копирования с совместным использованием памяти. Если платформа не поддерживает копирование с совместным использованием памяти, будет использоваться резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать ссылку копирования с совместным использованием памяти. Если платформа не поддерживает копирование с совместным использованием памяти, операция завершится ошибкой.

const fs = require('fs');

// destination.txt will be created or overwritten by default.
fs.copyFileSync('source.txt', 'destination.txt');
console.log('source.txt was copied to destination.txt');

Если третий аргумент является числом, то он задаёт flags:

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL);

fs.createReadStream(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <объект>
  • flags <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
  • encoding <строка> По умолчанию: null
  • fd <целое число> По умолчанию: null
  • mode <целое число> По умолчанию: 0o666
  • autoClose <логическое значение> По умолчанию: true
  • emitClose <логическое значение> По умолчанию: false
  • start <целое число>
  • end <целое число> По умолчанию: Infinity
  • highWaterMark <целое число> По умолчанию: 64 * 1024
  • fs <объект> | <null> По умолчанию: null
• Возвращает: <fs.Поток чтения> См. Поток чтения.

В отличие от значения по умолчанию 16 Кб для потока чтения, поток, возвращаемый этим методом, имеет значение по умолчанию 64 Кб.

options может включать значения start и end, чтобы прочитать определённый диапазон байтов из файла, а не весь файл. Оба start и end являются включительно и начинаются со счёта с 0, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Если fd указано, и start пропущено или undefined, fs.createReadStream() считывает последовательно из текущей позиции файла. encoding может быть любым из тех, что принимаются Buffer.

Если fd указано, ReadStream проигнорирует аргумент path и будет использовать указанный дескриптор файла. Это означает, что событие 'open' не будет генерироваться. fd должен быть блокирующим; неблокирующие fd должны быть переданы в net.Socket.

Если fd указывает на устройство символьного ввода-вывода, которое поддерживает только блокирующие операции чтения (например, клавиатуру или звуковую карту), операции чтения не завершатся, пока данные не станут доступны. Это может помешать завершению процесса и естественному закрытию потока.

По умолчанию поток не будет генерировать событие 'close' после того, как он был уничтожен. Это противоположно поведению по умолчанию для других потоков Readable. Установите опцию emitClose в true, чтобы изменить это поведение.

Указав опцию fs, можно переопределить соответствующие реализации fs для open, read, и close. При указании опции fs, требуются переопределения для open, read, и close.

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

Если autoClose ложно, тогда дескриптор файла не будет закрыт, даже если произошла ошибка. Приложение несет ответственность за его закрытие и обеспечение отсутствия утечки дескриптора файла. Если autoClose установлено в истинное значение (поведение по умолчанию), при 'error' или 'end' дескриптор файла будет автоматически закрыт.

mode устанавливает режим файла (разрешения и биты «вклеивания»), но только если файл был создан.

Пример чтения последних 10 байтов файла, который имеет длину 100 байтов:

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

Если options является строкой, то она определяет кодировку.

fs.createWriteStream(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
  • encoding <string> По умолчанию: 'utf8'
  • fd <integer> По умолчанию: null
  • mode <integer> По умолчанию: 0o666
  • autoClose <boolean> По умолчанию: true
  • emitClose <boolean> По умолчанию: false
  • start <integer>
  • fs <Object> | <null> По умолчанию: null
• Возвращает: <fs.WriteStream> См. Поток-получатель.

options также может включать параметр start для записи данных в определённой позиции после начала файла, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Изменение файла вместо его замены может потребовать использования режима flags r+ вместо режима по умолчанию w. encoding может быть любым из поддерживаемых Buffer.

Если autoClose установлено в true (поведение по умолчанию) для 'error' или 'finish', дескриптор файла будет закрыт автоматически. Если autoClose равно false, дескриптор файла не будет закрыт, даже при ошибке. Приложение несет ответственность за его закрытие и предотвращение утечки дескрипторов файлов.

По умолчанию, поток не будет излучать событие 'close' после уничтожения. Это противоположно поведению по умолчанию для других потоков-получателей Writable. Установите параметр emitClose в true, чтобы изменить это поведение.

Использование параметра fs позволяет переопределить соответствующие реализации fs для open, write, writev и close. Переопределение write() без writev() может снизить производительность, так как некоторые оптимизации (_writev()) будут отключены. При использовании параметра fs, необходимы переопределения для open, close, и по крайней мере одного из write и writev.

Как и ReadStream, если указан fd, WriteStream проигнорирует аргумент path и будет использовать указанный дескриптор файла. Это означает, что событие 'open' не будет излучаться. fd должен быть блокирующим; неблокирующие fd должны передаваться в net.Socket.

Если options является строкой, то она указывает кодировку.

fs.exists(path, callback)

• path <string> | <Buffer> | <URL>
• callback <Функция>
  • exists <boolean>

Проверяет существование заданного пути в файловой системе. Затем вызывает аргумент callback со значением true или false:

fs.exists('/etc/passwd', (exists) => {
  console.log(exists ? 'it\'s there' : 'no passwd!');
});

Параметры для этого обратного вызова не согласованы с другими обратными вызовами Node.js. Обычно первым параметром обратного вызова Node.js является параметр err, за которым могут следовать другие параметры. Обратный вызов fs.exists() имеет только один булевый параметр. Это одна из причин, по которой рекомендуется fs.access() вместо fs.exists().

Использование fs.exists() для проверки существования файла перед вызовом fs.open(), fs.readFile() или fs.writeFile() не рекомендуется. Это создаёт гонку, так как другие процессы могут изменить состояние файла между этими двумя вызовами. Вместо этого, код приложения должен напрямую открыть/прочитать/записать файл и обработать ошибку, если файл не существует.

write (НЕ РЕКОМЕНДУЕТСЯ)

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

write (РЕКОМЕНДУЕТСЯ)

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

    throw err;
  }

  writeMyData(fd);
});

read (НЕ РЕКОМЕНДУЕТСЯ)

fs.exists('myfile', (exists) => {
  if (exists) {
    fs.open('myfile', 'r', (err, fd) => {
      if (err) throw err;
      readMyData(fd);
    });
  } else {
    console.error('myfile does not exist');
  }
});

read (РЕКОМЕНДУЕТСЯ)

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

    throw err;
  }

  readMyData(fd);
});

В примерах выше, отмеченных как «не рекомендуется», проверяется существование файла, а затем используется файл; примеры, отмеченные как «рекомендуется», лучше, поскольку они напрямую используют файл и обрабатывают ошибку, если она возникнет.

В целом, проверяйте существование файла только в том случае, если файл не будет использоваться напрямую, например, когда его существование является сигналом от другого процесса.

fs.existsSync(path)

• path <string> | <Buffer> | <URL>
• Возвращает: <boolean>

Возвращает true, если путь существует, false в противном случае.

Подробную информацию см. в документации асинхронной версии этого API: fs.exists().

fs.exists() устарело, но fs.existsSync() нет. Параметр callback для fs.exists() содержит параметры, не согласованные с другими обратными вызовами Node.js. fs.existsSync() не использует обратный вызов.

if (fs.existsSync('/etc/passwd')) {
  console.log('The path exists.');
}

fs.fchmod(fd, mode, callback)

• fd <integer>
• mode <string> | <integer>
• callback <Функция>
  • err <Ошибка>

Асинхронная fchmod(2). В обратный вызов при завершении передаются только возможные исключения.

fs.fchmodSync(fd, mode)

• fd <integer>
• mode <string> | <integer>

Синхронная fchmod(2). Возвращает undefined.

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

• fd <целое число>
• uid <целое число>
• gid <целое число>
• callback <Функция>
  • err <Ошибка>

Асинхронная fchown(2). В обратный вызов для завершения передаются только возможные исключения.

fs.fchownSync(fd, uid, gid)

• fd <целое число>
• uid <целое число>
• gid <целое число>

Синхронная fchown(2). Возвращает undefined.

fs.fdatasync(fd, callback)

• fd <целое число>
• callback <Функция>
  • err <Ошибка>

Асинхронная fdatasync(2). В обратный вызов для завершения передаются только возможные исключения.

fs.fdatasyncSync(fd)

• fd <целое число>

Синхронная fdatasync(2). Возвращает undefined.

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

• fd <целое число>
• options <Объект>
  • bigint <логическое значение> Является ли необходимостью использование типа bigint для числовых значений в возвращаемом объекте fs.Stats. По умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

Асинхронная fstat(2). Обратный вызов получает два аргумента (err, stats), где stats – объект fs.Stats. fstat() идентичен stat(), за исключением того, что файл, для которого необходимо получить информацию, указывается с помощью дескриптора файла fd.

fs.fstatSync(fd[, options])

• fd <целое число>
• options <Объект>
  • bigint <логическое значение> Является ли необходимостью использование типа bigint для числовых значений в возвращаемом объекте fs.Stats. По умолчанию: false.
• Возвращает: <fs.Stats>

Синхронная fstat(2).

fs.fsync(fd, callback)

• fd <целое число>
• callback <Функция>
  • err <Ошибка>

Асинхронная fsync(2). В обратный вызов для завершения передаются только возможные исключения.

fs.fsyncSync(fd)

• fd <целое число>

Синхронная fsync(2). Возвращает undefined.

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

• fd <целое число>
• len <целое число> По умолчанию: 0
• callback <Функция>
  • err <Ошибка>

Асинхронная ftruncate(2). В обратный вызов для завершения передаются только возможные исключения.

Если файл, на который ссылается дескриптор файла, был больше, чем len байт, в файле сохранятся только первые len байт.

Например, следующая программа сохраняет только первые четыре байта файла:

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

// get the file descriptor of the file to be truncated
const fd = fs.openSync('temp.txt', 'r+');

// Truncate the file to first four bytes
fs.ftruncate(fd, 4, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt', 'utf8'));
});
// Prints: Node

Если файл ранее был короче, чем len байт, он будет расширен, и расширенная часть будет заполнена нулевыми байтами ('\0'):

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

// get the file descriptor of the file to be truncated
const fd = fs.openSync('temp.txt', 'r+');

// Truncate the file to 10 bytes, whereas the actual size is 7 bytes
fs.ftruncate(fd, 10, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt'));
});
// Prints: <Buffer 4e 6f 64 65 2e 6a 73 00 00 00>
// ('Node.js\0\0\0' in UTF8)

Последние три байта – нулевые байты ('\0'), чтобы компенсировать перерезку.

fs.ftruncateSync(fd[, len])

• fd <целое>
• len <целое> По умолчанию: 0

Возвращает undefined.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.ftruncate().

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

• fd <целое>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• callback <Функция>
  • err <Ошибка>

Изменяет временные метки файла, на который ссылается предоставленный дескриптор файла. См. fs.utimes().

Эта функция не работает на версиях AIX до 7.1, она вернёт ошибку UV_ENOSYS.

fs.futimesSync(fd, atime, mtime)

• fd <целое>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>

Синхронная версия fs.futimes(). Возвращает undefined.

fs.lchmod(path, mode, callback)

• path <строка> | <Буфер> | <URL>
• mode <целое>
• callback <Функция>
  • err <Ошибка>

Асинхронный вызов lchmod(2). В качестве аргументов обратного вызова передаётся только возможная ошибка.

Доступно только на macOS.

fs.lchmodSync(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <целое>

Синхронный вызов lchmod(2). Возвращает undefined.

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

• path <строка> | <Буфер> | <URL>
• uid <целое>
• gid <целое>
• callback <Функция>
  • err <Ошибка>

Асинхронный вызов lchown(2). В качестве аргументов обратного вызова передаётся только возможная ошибка.

fs.lchownSync(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое>
• gid <целое>

Синхронный вызов lchown(2). Возвращает undefined.

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

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• callback <Функция>
  • err <Ошибка>

Изменяет временные метки доступа и изменения файла аналогично fs.utimes(), с той разницей, что если путь ссылается на символическую ссылку, она не разыменовывается: вместо этого изменяются временные метки самой символической ссылки.

В качестве аргументов обратного вызова, кроме возможного исключения, ничего не передается.

fs.lutimesSync(path, atime, mtime)

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>

Изменяет метки времени файла системы для символической ссылки, на которую ссылается path. Возвращает undefined, или выбрасывает исключение при некорректных параметрах или при неудачном выполнении операции. Это синхронная версия fs.lutimes().

fs.link(existingPath, newPath, callback)

• existingPath <строка> | <Буфер> | <URL>
• newPath <строка> | <Буфер> | <URL>
• callback <Функция>
  • err <Ошибка>

Асинхронная link(2). В качестве аргументов обратного вызова, кроме возможного исключения, ничего не передается.

fs.linkSync(existingPath, newPath)

• existingPath <строка> | <Буфер> | <URL>
• newPath <строка> | <Буфер> | <URL>

Синхронная link(2). Возвращает undefined.

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое> Нужно ли, чтобы числовые значения в возвращаемом объекте fs.Stats были типа bigint? По умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

Асинхронная lstat(2). Обратный вызов получает два аргумента (err, stats), где stats - объект fs.Stats. lstat() идентичен stat(), за исключением того, что если path является символической ссылкой, то состояние определяется для самой ссылки, а не для файла, на который она указывает.

fs.lstatSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое> Нужно ли, чтобы числовые значения в возвращаемом объекте fs.Stats были типа bigint? По умолчанию: false.
• Возвращает: <fs.Stats>

Синхронная lstat(2).

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

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> По умолчанию: false
  • mode <string> | <integer> Не поддерживается в Windows. По умолчанию: 0o777.
• callback <Function>
  • err <Error>

Асинхронно создаёт директорию.

Обратный вызов получает возможную исключительную ситуацию и, если recursive является true, первый созданный путь к директории, (err, [path]).

Необязательный аргумент options может быть целым числом, определяющим режим (разрешения и биты «sticky»), или объектом с свойством mode и свойством recursive, указывающими, должны ли создаваться родительские директории. Вызов fs.mkdir(), когда path — это существующая директория, приводит к ошибке только тогда, когда recursive равно false.

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

В Windows, использование fs.mkdir() для корневой директории даже с рекурсией приведёт к ошибке:

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

См. также: mkdir(2).

fs.mkdirSync(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> По умолчанию: false
  • mode <string> | <integer> Не поддерживается в Windows. По умолчанию: 0o777.
• Возвращает: <string> | <undefined>

Синхронно создаёт директорию. Возвращает undefined, или если recursive — true, первый созданный путь к директории. Это синхронная версия fs.mkdir().

См. также: mkdir(2).

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

• prefix <string>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• callback <Function>
  • err <Error>
  • directory <string>

Создаёт уникальную временную директорию.

Генерирует шесть случайных символов, которые добавляются к необходимому prefix, чтобы создать уникальную временную директорию. Избегайте символов X в prefix, из-за несовместимостей между платформами. Некоторые платформы, особенно BSD, могут возвращать больше шести случайных символов и заменять конечные символы X в prefix случайными символами.

Созданный путь к директории передаётся в качестве строки во второй параметр обратного вызова.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом с свойством encoding, определяющим кодировку символов.

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

Метод fs.mkdtemp() добавит шесть случайно выбранных символов непосредственно к строке prefix. Например, если нужно создать временную директорию *внутри* /tmp, то prefix должна заканчиваться специальным символом пути (require('path').sep).

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

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

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

fs.mkdtempSync(prefix[, options])

• prefix <string>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• Возвращает: <string>

Возвращает созданный путь к директории.

Для подробной информации см. документацию асинхронной версии этого API: fs.mkdtemp().

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом с свойством encoding.

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

• path <string> | <Buffer> | <URL>
• flags <string> | <number> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
• mode <string> | <integer> По умолчанию: 0o666 (чтение и запись)
• callback <Function>
  • err <Error>
  • fd <integer>

Асинхронное открытие файла. См. open(2).

mode устанавливает режим файла (разрешения и биты «только чтение»), но только если файл был создан. В Windows можно изменять только разрешение на запись; см. fs.chmod().

Обратный вызов получает два аргумента (err, fd).

Некоторые символы (< > : " / \ | ? *) зарезервированы в Windows, как документировано в Naming Files, Paths, and Namespaces. В NTFS, если имя файла содержит двоеточие, Node.js откроет поток файловой системы, как описано на странице MSDN по этой ссылке.

Функции, основанные на fs.open(), также демонстрируют это поведение: fs.writeFile(), fs.readFile(), и т.д.

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • bufferSize <число> Количество записей каталога, которые буферизуются внутри при чтении из каталога. Более высокие значения приводят к лучшей производительности, но большему потреблению памяти. По умолчанию: 32
• callback <Функция>
  • err <Ошибка>
  • dir <fs.Dir>

Асинхронно открыть каталог. См. opendir(3).

Создаёт fs.Dir, который содержит все последующие функции для чтения из каталога и его очистки.

Параметр encoding устанавливает кодировку для path при открытии каталога и последующих операциях чтения.

fs.opendirSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • bufferSize <число> Количество записей каталога, которые буферизуются внутри при чтении из каталога. Более высокие значения приводят к лучшей производительности, но большему потреблению памяти. По умолчанию: 32
• Возвращает: <fs.Dir>

Синхронно открыть каталог. См. opendir(3).

Создаёт fs.Dir, который содержит все последующие функции для чтения из каталога и его очистки.

Параметр encoding устанавливает кодировку для path при открытии каталога и последующих операциях чтения.

fs.openSync(path[, flags, mode])

• path <строка> | <Буфер> | <URL>
• flags <строка> | <число> По умолчанию: 'r'. См. поддержку флагов файловой системы flags.
• mode <строка> | <целое число> По умолчанию: 0o666
• Возвращает: <число>

Возвращает целое число, представляющее дескриптор файла.

Для подробной информации см. документацию асинхронной версии этого API: fs.open().

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

• fd <целое число>
• buffer <Буфер> | <Массив типов> | <DataView>
• offset <целое число>
• length <целое число>
• position <целое число>
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое число>
  • buffer <Буфер>

Считывает данные из файла, указанного fd.

buffer — это буфер, в который будут записаны считанные (из fd) данные.

offset — это смещение в буфере, с которого начнется запись.

length — это целое число, определяющее количество байтов для чтения.

position — это аргумент, определяющий, с какого места файла начать чтение. Если position является null, данные будут считываться с текущей позиции файла, и позиция файла будет обновлена. Если position является целым числом, позиция файла останется неизменной.

Обратный вызов получает три аргумента, (err, bytesRead, buffer).

Если этот метод вызывается как его версия util.promisify(), он возвращает Promise для Object, с свойствами bytesRead и buffer.

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

• fd <целое>
• options <Объект>
  • buffer <Буфер> | <Массив типов> | <Представление данных> По умолчанию: Buffer.alloc(16384)
  • offset <целое> По умолчанию: 0
  • length <целое> По умолчанию: buffer.length
  • position <целое> По умолчанию: null
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Буфер>

Аналогично вышеописанной fs.read функции, этот вариант принимает необязательный options объект. Если объект options не указан, используются значения по умолчанию, указанные выше.

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

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
• callback <Функция>
  • err <Ошибка>
  • files <массив строк> | <массив буферов> | <массив fs.Dirent>

Асинхронная readdir(3). Читает содержимое каталога. Обратный вызов получает два аргумента (err, files), где files — массив имён файлов в каталоге, исключая '.' и '..'.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом с свойством encoding, задающим кодировку символов для имён файлов, передаваемых в обратный вызов. Если encoding установлено в 'buffer', имена файлов будут возвращены как объекты Buffer.

Если options.withFileTypes установлено в true, массив files будет содержать объекты fs.Dirent.

fs.readdirSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
• Возвращает: <массив строк> | <массив буферов> | <массив fs.Dirent>

Синхронная readdir(3).

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом с свойством encoding, задающим кодировку символов для возвращаемых имён файлов. Если encoding установлено в 'buffer', имена файлов будут возвращены как объекты Buffer.

Если options.withFileTypes установлено в true, результат будет содержать объекты fs.Dirent.

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

• path <строка> | <Буфер> | <URL> | <целое> имя файла или дескриптор файла
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
• callback <Функция>
  • err <Ошибка>
  • data <строка> | <Буфер>

Асинхронно считывает всё содержимое файла.

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

Обратный вызов получает два аргумента (err, data), где data — содержимое файла.

Если кодировка не указана, возвращается буфер.

Если options — строка, она определяет кодировку:

fs.readFile('/etc/passwd', 'utf8', callback);

Когда путь указывает на директорию, поведение fs.readFile() и fs.readFileSync() зависит от платформы. В macOS, Linux и Windows будет возвращено сообщение об ошибке. В FreeBSD будет возвращено представление содержимого директории.

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

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

Функция fs.readFile() буферизует весь файл. Для минимизации затрат памяти, когда это возможно, предпочитайте потоковую передачу с помощью fs.createReadStream().

Дескрипторы файлов

1. Любой указанный дескриптор файла должен поддерживать чтение.
2. Если дескриптор файла указан в качестве path, он не будет закрыт автоматически.
3. Чтение начнется с текущей позиции. Например, если в файле уже есть данные 'Hello World, и с помощью дескриптора файла будут прочитаны шесть байтов, то вызов fs.readFile() с тем же дескриптором файла вернёт 'World', а не 'Hello World'.

fs.readFileSync(path[, options])

• path <строка> | <Буфер> | <URL> | <целое число> имя файла или дескриптор файла
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
• Возвращает: <строка> | <Буфер>

Возвращает содержимое path.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.readFile().

Если указан параметр encoding, функция возвращает строку. В противном случае возвращает буфер.

Аналогично fs.readFile(), при указании пути к директории поведение fs.readFileSync() зависит от платформы.

// macOS, Linux, and Windows
fs.readFileSync('<directory>');
// => [Error: EISDIR: illegal operation on a directory, read <directory>]

//  FreeBSD
fs.readFileSync('<directory>'); // => <data>

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

• path <строка> | <Буфер> | <URL>
• options <строка> | <объект>
  • encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • linkString <строка> | <Буфер>

Асинхронная функция readlink(2). Обратный вызов получает два аргумента (err, linkString).

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом с свойством encoding, задающим кодировку символов для пути к ссылке, передаваемого в обратный вызов. Если encoding установлено в значение 'buffer', путь к ссылке, возвращаемый в обратном вызове, будет передан как объект Buffer.

fs.readlinkSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <объект>
  • encoding <строка> По умолчанию: 'utf8'
• Возвращает: <строка> | <Буфер>

Синхронная функция readlink(2). Возвращает строковое значение символьной ссылки.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом с свойством encoding, задающим кодировку символов для возвращаемого пути к ссылке. Если encoding установлено в значение 'buffer', путь к ссылке, возвращаемый в обратном вызове, будет передан как объект Buffer.

fs.readSync(fd, buffer, offset, length, position)

• fd <целое число>
• buffer <Буфер> | <Массив типов> | <DataView>
• offset <целое число>
• length <целое число>
• position <целое число>
• Возвращает: <число>

Возвращает количество bytesRead.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.read().

fs.readSync(fd, buffer, [options])

• fd <целое>
• buffer <Буфер> | <TypedArray> | <DataView>
• options <Объект>
  • offset <целое> По умолчанию: 0
  • length <целое> По умолчанию: buffer.length
  • position <целое> По умолчанию: null
• Возвращает: <число>

Возвращает количество bytesRead.

Аналогично вышеупомянутой функции fs.readSync, этот вариант принимает необязательный объект options. Если объект options не указан, будут использоваться значения по умолчанию.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.read().

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

• fd <целое>
• buffers <ArrayBufferView[]>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesRead <целое>
  • buffers <ArrayBufferView[]>

Чтение из файла, указанного по fd, и запись в массив ArrayBufferView с помощью readv().

position — смещение от начала файла, с которого должно происходить чтение. Если typeof position !== 'number', чтение будет происходить с текущей позиции.

Обратный вызов получит три аргумента: err, bytesRead, и buffers. bytesRead — количество прочитанных байтов из файла.

Если этот метод вызван как его util.promisify()-версия, он возвращает промис для Promise с свойствами Object и bytesRead.

fs.readvSync(fd, buffers[, position])

• fd <целое>
• buffers <ArrayBufferView[]>
• position <целое>
• Возвращает: <число> Количество прочитанных байтов.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.readv().

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

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • resolvedPath <строка> | <Буфер>

Асинхронно вычисляет каноническое имя пути, разрешая ., .. и символические ссылки.

Каноническое имя пути не обязательно уникально. Жёсткие ссылки и монтирования с использованием bind могут отобразить сущность файловой системы через несколько имён путей.

Эта функция ведёт себя подобно realpath(3) с некоторыми исключениями:

1. Преобразование регистров не выполняется на регистронезависимых файловых системах.

2. Максимальное количество символических ссылок не зависит от платформы и, как правило, (намного) выше, чем поддерживается реализацией realpath(3).

Функция callback получает два аргумента (err, resolvedPath). Может использовать process.cwd для разрешения относительных путей.

Поддерживаются только пути, которые можно преобразовать в строки UTF8.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding, указывающим кодировку символов для пути, переданного в обратный вызов. Если encoding установлено в 'buffer', возвращаемый путь будет передан как объект Buffer.

Если path разрешается до сокета или трубы, функция вернёт имя, зависящее от системы.

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

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • resolvedPath <строка> | <Буфер>

Асинхронная версия realpath(3).

Функция callback получает два аргумента (err, resolvedPath).

Поддерживаются только пути, которые можно преобразовать в строки UTF8.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding, указывающим кодировку символов для пути, переданного в обратный вызов. Если encoding установлено в 'buffer', возвращаемый путь будет передан как объект Buffer.

В Linux, когда Node.js связан с musl libc, файловая система procfs должна быть смонтирована на /proc для работы этой функции. Glibc не имеет этого ограничения.

fs.realpathSync(path[, options])

• path <строка> | <Buffer> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• Возвращает: <строка> | <Buffer>

Возвращает разрешённый путь.

Для получения подробной информации см. документацию асинхронной версии данного API: fs.realpath().

fs.realpathSync.native(path[, options])

• path <строка> | <Buffer> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• Возвращает: <строка> | <Buffer>

Синхронная функция realpath(3).

Поддерживаются только пути, которые могут быть преобразованы в строки UTF8.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом с свойством encoding, определяющим кодировку символов для возвращаемого пути. Если encoding установлено в 'buffer', возвращаемый путь будет передан как объект Buffer.

В Linux, когда Node.js связан с musl libc, файловая система procfs должна быть смонтирована на /proc, чтобы эта функция работала. Glibc не имеет этого ограничения.

fs.rename(oldPath, newPath, callback)

• oldPath <строка> | <Buffer> | <URL>
• newPath <строка> | <Buffer> | <URL>
• callback <Функция>
  • err <Ошибка>

Асинхронно переименовывает файл по пути oldPath в указанный путь newPath. В случае, если файл по пути newPath уже существует, он будет перезаписан. Если по пути newPath находится директория, будет выброшено исключение. В качестве аргументов обратной функции вызывается только возможная ошибка.

См. также: rename(2).

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

fs.renameSync(oldPath, newPath)

• oldPath <строка> | <Buffer> | <URL>
• newPath <строка> | <Buffer> | <URL>

Синхронная функция rename(2). Возвращает undefined.

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

• path <строка> | <Buffer> | <URL>
• options <Объект>
  • maxRetries <целое> В случае возникновения ошибок EBUSY, EMFILE, ENFILE, ENOTEMPTY, или EPERM, Node.js будет повторять операцию с линейной задержкой, увеличивая время ожидания на retryDelay мс при каждой попытке. Данная опция определяет количество повторных попыток. Эта опция игнорируется, если опция recursive не равна true. По умолчанию: 0.
  • recursive <логическое> Если true, выполняется рекурсивное удаление директории. В рекурсивном режиме ошибки не сообщаются, если path не существует, и операции повторно выполняются при сбое. По умолчанию: false.
  • retryDelay <целое> Время ожидания между повторными попытками в миллисекундах. Эта опция игнорируется, если опция recursive не равна true. По умолчанию: 100.
• callback <Функция>
  • err <Ошибка>

Асинхронная функция rmdir(2). В качестве аргументов обратной функции вызывается только возможная ошибка.

Использование fs.rmdir() для файла (не директории) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

fs.rmdirSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • maxRetries <целое число> Если возникает ошибка EBUSY, EMFILE, ENFILE, ENOTEMPTY, или EPERM, Node.js повторит операцию с линейной задержкой ожидания retryDelay мс больше на каждой попытке. Эта опция представляет количество повторов. Эта опция игнорируется, если опция recursive не равна true. Значение по умолчанию: 0.
  • recursive <логическое значение> Если true, выполнить рекурсивное удаление каталога. В рекурсивном режиме ошибки не сообщаются, если path не существует, и операции повторяются при ошибках. Значение по умолчанию: false.
  • retryDelay <целое число> Время ожидания в миллисекундах между повторами. Эта опция игнорируется, если опция recursive не равна true. Значение по умолчанию: 100.

Синхронная rmdir(2). Возвращает undefined.

Использование fs.rmdirSync() для файла (не каталога) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

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

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое значение> Указывает, должны ли числовые значения в возвращаемом объекте fs.Stats быть типа bigint. Значение по умолчанию: false.
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

Асинхронная stat(2). Обратный вызов получает два аргумента (err, stats), где stats — объект fs.Stats.

В случае ошибки err.code будет одной из Общих системных ошибок.

Использование fs.stat() для проверки существования файла перед вызовом fs.open(), fs.readFile() или fs.writeFile() не рекомендуется. Вместо этого код должен напрямую открывать/читать/записывать файл и обрабатывать ошибку, если файл недоступен.

Для проверки существования файла без дальнейшей работы с ним рекомендуется использовать fs.access().

Например, при следующей структуре каталогов:

- txtDir
-- file.txt
- app.js

Следующая программа проверит статистику указанных путей:

const fs = require('fs');

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

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

Результат будет примерно таким:

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.statSync(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое значение> Указывает, должны ли числовые значения в возвращаемом объекте fs.Stats быть типа bigint. Значение по умолчанию: false.
• Возвращает: <fs.Stats>

Синхронная stat(2).

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

• target <строка> | <Буфер> | <URL>
• path <строка> | <Буфер> | <URL>
• type <строка>
• callback <Функция>
  • err <Ошибка>

Асинхронная symlink(2), которая создаёт ссылку под названием path , указывающую на target. В обратный вызов не передаются другие аргументы, кроме возможного исключения.

Аргумент type доступен только в Windows и игнорируется на других платформах. Он может быть установлен в 'dir', 'file', или 'junction'. Если аргумент type не задан, Node.js автоматически определит тип target и использует 'file' или 'dir'. Если target не существует, будет использоваться 'file'. Соединения Windows требуют абсолютного пути к целевому пути. При использовании 'junction', аргумент target автоматически нормализуется до абсолютного пути.

Относительные целевые пути относительны к родительскому каталогу ссылки.

fs.symlink('./mew', './example/mewtwo', callback);

В приведённом выше примере создаётся символическая ссылка mewtwo в example, которая указывает на mew в том же каталоге:

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

fs.symlinkSync(target, path[, type])

• target <строка> | <Буфер> | <URL>
• path <строка> | <Буфер> | <URL>
• type <строка>

Возвращает undefined.

Для получения подробной информации, см. документацию асинхронной версии этого API: fs.symlink().

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

• path <строка> | <Буфер> | <URL>
• len <целое число> По умолчанию: 0
• callback <Функция>
  • err <Ошибка>

Асинхронная truncate(2). В обратном вызове функции не передаются аргументы, кроме возможного исключения. В качестве первого аргумента также можно передать дескриптор файла. В этом случае вызывается fs.ftruncate().

Передача дескриптора файла устарела и может в будущем приводить к ошибке.

fs.truncateSync(path[, len])

• path <строка> | <Буфер> | <URL>
• len <целое число> По умолчанию: 0

Синхронная truncate(2). Возвращает undefined. В качестве первого аргумента также можно передать дескриптор файла. В этом случае вызывается fs.ftruncateSync().

Передача дескриптора файла устарела и может в будущем приводить к ошибке.

fs.unlink(path, callback)

• path <строка> | <Буфер> | <URL>
• callback <Функция>
  • err <Ошибка>

Асинхронно удаляет файл или символическую ссылку. В обратном вызове функции не передаются аргументы, кроме возможного исключения.

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

fs.unlink() не будет работать с каталогом, пустым или иным. Для удаления каталога используйте fs.rmdir().

См. также: unlink(2).

fs.unlinkSync(path)

• path <строка> | <Буфер> | <URL>

Синхронная unlink(2). Возвращает undefined.

fs.unwatchFile(filename[, listener])

• filename <строка> | <Буфер> | <URL>
• listener <Функция> Необязательно, ранее присоединённый обработчик с помощью fs.watchFile()

Остановить наблюдение за изменениями в filename. Если listener указан, удаляется только этот обработчик. В противном случае удаляются все обработчики, эффективно прекращая наблюдение за filename.

Вызов fs.unwatchFile() с именем файла, за которым не ведётся наблюдение, является пустой операцией, а не ошибкой.

Использование fs.watch() более эффективно, чем fs.watchFile() и fs.unwatchFile(). fs.watch() следует использовать вместо fs.watchFile() и fs.unwatchFile() при возможности.

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

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• callback <Функция>
  • err <Ошибка>

Изменить временные метки системы файлов объекта, на который ссылается path.

Аргументы atime и mtime следуют этим правилам:

• Значения могут быть либо числами, представляющими время Unix-эпохи в секундах, либо строками, либо числовыми строками, как '123456789.0'.
• Если значение не может быть преобразовано в число, или является NaN, Infinity или -Infinity, будет выброшено исключение Error.

fs.utimesSync(path, atime, mtime)

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>

Возвращает undefined.

Для подробной информации см. документацию асинхронной версии этого API: fs.utimes().

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

• filename <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • persistent <логическое значение> Указывает, следует ли продолжать выполнение процесса до тех пор, пока файлы отслеживаются. По умолчанию: true.
  • recursive <логическое значение> Указывает, должны ли отслеживаться все подкаталоги или только текущий каталог. Применяется, когда указан каталог и только на поддерживаемых платформах (см. Примечания). По умолчанию: false.
  • encoding <строка> Указывает кодировку символов, которая должна использоваться для имени файла, передаваемого слушателю. По умолчанию: 'utf8'.
• listener <Функция> | <неопределённо> По умолчанию: undefined.
  • eventType <строка>
  • filename <строка> | <Буфер>
• Возвращает: <fs.FSWatcher>

Отслеживание изменений в filename, где filename — это файл или каталог.

Второй аргумент является необязательным. Если options передан как строка, он указывает encoding. В противном случае options должен быть передан как объект.

Обработчик событий получает два аргумента (eventType, filename). eventType — это либо 'rename' или 'change', а filename — это имя файла, который вызвал событие.

На большинстве платформ событие 'rename' генерируется всякий раз, когда имя файла появляется или исчезает в каталоге.

Обработчик событий прикреплён к событию 'change' , генерируемому fs.FSWatcher, но это не то же самое, что значение 'change' объекта eventType.

Примечания

API fs.watch не является 100% согласованным на всех платформах и недоступен в некоторых ситуациях.

Рекурсивный вариант поддерживается только на macOS и Windows.

В Windows не будут генерироваться события, если отслеживаемый каталог перемещается или переименовывается. Ошибка EPERM сообщается, когда отслеживаемый каталог удаляется.

Доступность

Эта функция зависит от возможности операционной системы получать уведомления об изменениях в файловой системе.

• На системах Linux используется inotify(7).
• На системах BSD используется kqueue(2).
• На macOS используется kqueue(2) для файлов и FSEvents для каталогов.
• На системах SunOS (включая Solaris и SmartOS) используется event ports.
• На системах Windows используется ReadDirectoryChangesW.
• На системах AIX эта функция зависит от AHAFS, которая должна быть включена.
• На системах IBM i эта функция не поддерживается.

Если по какой-либо причине базовая функциональность недоступна, fs.watch() не сможет работать и может выбросить исключение. Например, отслеживание файлов или каталогов может быть ненадежным и в некоторых случаях невозможным на сетевых файловых системах (NFS, SMB и т. д.) или файловых системах хоста при использовании программного обеспечения виртуализации, такого как Vagrant или Docker.

Всё ещё можно использовать fs.watchFile(), который использует опросный метод, но этот метод медленнее и менее надёжен.

Иноды

В системах Linux и macOS fs.watch() определяет путь к иноду иноду и отслеживает его. Если отслеживаемый путь удаляется и создаётся заново, ему назначается новый инод. Слушатель событий получит уведомление об удалении, но продолжит отслеживание исходного инода. События для нового инода не будут генерироваться. Это ожидаемое поведение.

Файлы AIX сохраняют тот же инод на протяжении всего срока службы файла. Сохранение и закрытие отслеживаемого файла в AIX приведет к двум уведомлениям (одно для добавления нового содержимого и одно для усечения).

Аргумент имени файла

Предоставление аргумента filename в обработчике событий поддерживается только в Linux, macOS, Windows и AIX. Даже на поддерживаемых платформах filename не гарантируется всегда. Поэтому не предполагайте, что аргумент filename всегда предоставляется в обработчике событий, и предусмотрите механизм работы в случае, если он null.

fs.watch('somedir', (eventType, filename) => {
  console.log(`event type is: ${eventType}`);
  if (filename) {
    console.log(`filename provided: ${filename}`);
  } else {
    console.log('filename not provided');
  }
});

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

• filename <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое значение> По умолчанию: false
  • persistent <логическое значение> По умолчанию: true
  • interval <целое число> По умолчанию: 5007
• listener <Функция>
  • current <fs.Stats>
  • previous <fs.Stats>
• Возвращает: <fs.StatWatcher>

Отслеживание изменений в filename. Обработчик событий listener будет вызываться каждый раз, когда файл будет обращён.

Аргумент options может быть опущен. Если предоставлен, он должен быть объектом. Объект options может содержать булево значение, названное persistent, которое указывает, следует ли продолжать процесс, пока отслеживаются файлы. Объект options может указывать свойство interval, определяющее, как часто целевой объект должен опрашиваться в миллисекундах.

Функция listener получает два аргумента: текущий объект stat и предыдущий объект stat:

fs.watchFile('message.text', (curr, prev) => {
  console.log(`the current mtime is: ${curr.mtime}`);
  console.log(`the previous mtime was: ${prev.mtime}`);
});

Эти объекты stat являются экземплярами fs.Stat. Если опция bigint имеет значение true, числовые значения в этих объектах задаются как BigInt.

Для получения уведомления о том, что файл был изменен, а не только прочитан, необходимо сравнить curr.mtime и prev.mtime.

Когда операция fs.watchFile приводит к ошибке ENOENT, она вызовет слушателя один раз, со всеми полями, сброшенными до нуля (или, для дат, эпохи Unix). Если файл будет создан позднее, слушатель будет вызван снова, с последними объектами stat. Это изменение функциональности с версии v0.10.

Использование fs.watch() более эффективно, чем fs.watchFile и fs.unwatchFile. fs.watch следует использовать вместо fs.watchFile и fs.unwatchFile по возможности.

Когда файл, отслеживаемый fs.watchFile(), исчезает и снова появляется, содержимое previous во втором событии обратного вызова (повторное появление файла) будет таким же, как содержимое previous в первом событии обратного вызова (его исчезновение).

Это происходит, когда:

• файл удален, а затем восстановлен
• файл переименован, а затем переименован обратно в исходное имя

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

• fd <целое>
• buffer <Буфер> | <Массив_типов> | <DataView>
• offset <целое>
• length <целое>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffer <Буфер> | <Массив_типов> | <DataView>

Записать buffer в файл, указанный fd.

offset определяет часть буфера, подлежащую записи, а length — целое число, указывающее количество байтов для записи.

position относится к смещению с начала файла, куда должны быть записаны эти данные. Если typeof position !== 'number', данные будут записаны в текущей позиции. См. pwrite(2).

Обратный вызов получит три аргумента (err, bytesWritten, buffer), где bytesWritten указывает, сколько байтов было записано из buffer.

Если этот метод вызывается в виде его util.promisify()-версии, он возвращает Promise для Object, с bytesWritten и buffer свойствами.

Небезопасно использовать fs.write() несколько раз на одном и том же файле без ожидания обратного вызова. Для этой ситуации рекомендуется использовать fs.createWriteStream().

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

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

• fd <целое>
• string <строка>
• position <целое>
• encoding <строка> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • written <целое>
  • string <строка>

Записать string в файл, указанный fd. Если string не является строкой, значение будет преобразовано в строку.

position обозначает смещение с начала файла, куда должны быть записаны данные. Если typeof position !== 'number', данные будут записаны в текущей позиции. См. pwrite(2).

encoding — ожидаемая кодировка строки.

Обратный вызов получит аргументы (err, written, string), где written указывает, сколько байтов потребовалось для записи переданной строки. Количество записанных байтов не обязательно совпадает с количеством записанных символов строки. См. Buffer.byteLength.

Небезопасно использовать fs.write() несколько раз на одном и том же файле без ожидания обратного вызова. В этом случае рекомендуется использовать fs.createWriteStream().

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

В Windows, если дескриптор файла подключён к консоли (например, fd == 1 или stdout), строка, содержащая символы, не являющиеся ASCII, не будет отображаться должным образом по умолчанию, независимо от используемой кодировки. Можно настроить консоль на правильное отображение UTF-8, изменив активную кодовую страницу с помощью команды chcp 65001 . Подробнее см. в документации по команде chcp.

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

• file <string> | <Buffer> | <URL> | <integer> имя файла или дескриптор файла
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
• callback <Function>
  • err <Error>

Когда file является именем файла, асинхронно записывает данные в файл, заменяя файл, если он уже существует. data может быть строкой или буфером.

Когда file является дескриптором файла, поведение аналогично вызову fs.write() напрямую (что рекомендуется). См. примечания ниже об использовании дескриптора файла.

Опция encoding игнорируется, если data является буфером.

const data = new Uint8Array(Buffer.from('Hello Node.js'));
fs.writeFile('message.txt', data, (err) => {
  if (err) throw err;
  console.log('The file has been saved!');
});

Если options — строка, то она указывает кодировку:

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

Небезопасно использовать fs.writeFile() несколько раз для одного файла без ожидания обратного вызова. В этом случае рекомендуется fs.createWriteStream().

Использование fs.writeFile() с дескрипторами файлов

Когда file — дескриптор файла, поведение почти идентично прямому вызову fs.write():

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

Различие с прямым вызовом fs.write() заключается в том, что в некоторых необычных ситуациях fs.write() может записать только часть буфера и потребуется повторный вызов для записи оставшихся данных, в то время как fs.writeFile() будет повторять попытки до тех пор, пока данные не будут полностью записаны (или не произойдет ошибка).

Последствия этого часто приводят к путанице. В случае дескриптора файла файл не заменяется! Данные не обязательно записываются в начало файла, и исходные данные файла могут оставаться перед и/или после вновь записанных данных.

Например, если fs.writeFile() вызывается дважды подряд, сначала для записи строки 'Hello', а затем для записи строки ', World', файл будет содержать 'Hello, World', и может содержать часть исходных данных файла (в зависимости от размера исходного файла и позиции дескриптора файла). Если бы вместо дескриптора использовалось имя файла, файл гарантированно содержал бы только ', World'.

fs.writeFileSync(file, data[, options])

• file <string> | <Buffer> | <URL> | <integer> имя файла или дескриптор файла
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.

Возвращает undefined.

Для подробной информации см. документацию асинхронной версии этого API: fs.writeFile().

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

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer>
• Возвращает: <number> Количество записанных байтов.

Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

• fd <integer>
• string <string>
• position <integer>
• encoding <string>
• Возвращает: <number> Количество записанных байтов.

Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, string...).

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

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer>
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

Запишите массив ArrayBufferView в файл, указанный fd, используя writev().

position — это смещение от начала файла, куда должны быть записаны эти данные. Если typeof position !== 'number', данные будут записаны в текущей позиции.

Обратный вызов получит три аргумента: err, bytesWritten, и buffers. bytesWritten — это количество байтов, записанных из buffers.

Если этот метод util.promisify()рован, он возвращает Promise для Object, с bytesWritten и buffers свойствами.

Небезопасно использовать fs.writev() несколько раз на одном и том же файле без ожидания обратного вызова. В этом случае используйте fs.createWriteStream().

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

fs.writevSync(fd, buffers[, position])

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer>
• Возвращает: <number> Количество записанных байтов.

Для получения подробной информации, см. документацию асинхронной версии этого API: fs.writev().

fs API Обещаний

API Обещаний предоставляет альтернатный набор асинхронных методов работы с файлами, которые возвращают объекты обещаний, а не используют обратные вызовы. К API можно обратиться через require('fs').promises.

Класс: FileHandle

Объект FileHandle — это обёртка над числовым дескриптором файла. Экземпляры FileHandle отличаются от числовых дескрипторов файлов тем, что предоставляют объектно-ориентированный API для работы с файлами.

Если объект FileHandle не закрыт с помощью метода filehandle.close(), он может автоматически закрыть дескриптор файла и выведет предупреждение процесса, тем самым помогая предотвратить утечки памяти. Пожалуйста, не полагайтесь на это поведение, так как оно ненадежно, и файл может не закрыться. Вместо этого всегда явным образом закрывайте FileHandle.

Экземпляры объекта FileHandle создаются внутри методом fsPromises.open().

В отличие от API на основе обратных вызовов (fs.fstat(), fs.fchown(), fs.fchmod(), и т. д.), числовой дескриптор файла не используется в API на основе обещаний. Вместо этого API на основе обещаний использует класс FileHandle, чтобы избежать случайной утечки незакрытых дескрипторов файлов после того, как обещание Promise выполнено или отклонено.

filehandle.appendFile(data, options)

• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
• Возвращает: <Promise>

Псевдоним filehandle.writeFile().

При работе с дескрипторами файлов режим не может быть изменён с того, который был установлен с помощью fsPromises.open(). Поэтому это эквивалентно filehandle.writeFile().

filehandle.chmod(mode)

• mode <integer>
• Возвращает: <Promise>

Изменяет разрешения на файл. Обещание разрешается без аргументов при успехе.

filehandle.chown(uid, gid)

• uid <integer>
• gid <integer>
• Возвращает: <Promise>

Изменяет владельца файла, затем разрешает обещание без аргументов при успехе.

filehandle.close()

• Возвращает: <Promise> Обещание, которое будет выполнено, когда базовый дескриптор файла будет закрыт, или будет отклонено, если произойдёт ошибка при закрытии.

Закрывает дескриптор файла.

const fsPromises = require('fs').promises;
async function openAndClose() {
  let filehandle;
  try {
    filehandle = await fsPromises.open('thefile.txt', 'r');
  } finally {
    if (filehandle !== undefined)
      await filehandle.close();
  }
}

filehandle.datasync()

• Возвращает: <Promise>

Асинхронный fdatasync(2). Обещание разрешается без аргументов при успехе.

filehandle.fd

• <number> Числовой дескриптор файла, управляемый объектом FileHandle.

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

• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>
• Возвращает: <Promise>

Чтение данных из файла.

buffer — буфер, в который будут записаны данные.

offset — смещение в буфере, с которого нужно начать запись.

length — целое число, указывающее количество байтов для чтения.

position — аргумент, указывающий, с какого места в файле начать чтение. Если position равно null, данные будут считаны с текущей позиции файла, и позиция файла будет обновлена. Если position — целое число, позиция файла останется неизменной.

После успешного чтения обещание Promise выполняется с объектом, содержащим свойство bytesRead, которое указывает количество прочитанных байтов, и свойство buffer, которое является ссылкой на переданный аргумент buffer.

filehandle.read(options)

• options <Объект>
  • buffer <Буфер> | <Uint8Array> По умолчанию: Buffer.alloc(16384)
  • offset <целое> По умолчанию: 0
  • length <целое> По умолчанию: buffer.length
  • position <целое> По умолчанию: null
• Возвращает: <Promise>

filehandle.readFile(options)

• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
• Возвращает: <Promise>

Асинхронно считывает все содержимое файла.

Обещание Promise разрешается содержимым файла. Если кодировка не указана (используя options.encoding), данные возвращаются как объект Buffer. В противном случае данные будут строкой.

Если options — строка, то она задает кодировку.

Файловый FileHandle должен поддерживать чтение.

Если один или несколько вызовов filehandle.read() выполняются с файловым дескриптором, а затем выполняется вызов filehandle.readFile(), данные будут считываться с текущей позиции до конца файла. Это не всегда означает чтение с начала файла.

filehandle.readv(buffers[, position])

• buffers <ArrayBufferView[]>
• position <целое>
• Возвращает: <Promise>

Считывает данные из файла и записывает их в массив ArrayBufferView

Обещание Promise разрешается объектом, содержащим свойство bytesRead , определяющее количество прочитанных байтов, и свойство buffers , содержащее ссылку на массив buffers ввода.

position — смещение от начала файла, с которого следует читать данные. Если typeof position !== 'number', данные будут считываться с текущей позиции.

filehandle.stat([options])

• options <Объект>
  • bigint <логическое> Нужно ли числовые значения в возвращаемом объекте fs.Stats быть типа bigint. По умолчанию: false.
• Возвращает: <Promise>

Получает fs.Stats для файла.

filehandle.sync()

• Возвращает: <Promise>

Асинхронная функция fsync(2). Обещание Promise разрешается без аргументов при успехе.

filehandle.truncate(len)

• len <целое> По умолчанию: 0
• Возвращает: <Promise>

Усекает файл, затем разрешает обещание Promise без аргументов при успехе.

Если файл был больше, чем len байт, только первые len байт будут сохранены в файле.

Например, следующая программа сохраняет только первые четыре байта файла:

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(4);
  } finally {
    if (filehandle) {
      // Close the file if it is opened.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints: Node
}

doTruncate().catch(console.error);

Если файл был короче len байт, он расширяется, а расширенная часть заполняется нулевыми байтами ('\0'):

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(10);
  } finally {
    if (filehandle) {
      // Close the file if it is opened.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints Node.js\0\0\0
}

doTruncate().catch(console.error);

Последние три байта — нулевые байты ('\0'), чтобы компенсировать избыточное усечение.

filehandle.utimes(atime, mtime)

• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• Возвращает: <Promise>

Изменяет системные метки времени файла, на который ссылается FileHandle, и затем разрешает Promise без аргументов при успехе.

Эта функция не работает на версиях AIX до 7.1, она разрешит Promise с ошибкой с кодом UV_ENOSYS.

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

• buffer <Буфер> | <Uint8Array>
• offset <целое>
• length <целое>
• position <целое>
• Возвращает: <Promise>

Записывает buffer в файл.

Обещание Promise разрешается объектом, содержащим свойство bytesWritten , определяющее количество записанных байтов, и свойство buffer , содержащее ссылку на записанный buffer.

offset определяет часть буфера, которая должна быть записана, а length — целое число, определяющее количество байтов для записи.

position относится к смещению от начала файла, куда должны быть записаны эти данные. Если typeof position !== 'number', данные будут записаны в текущей позиции. См. pwrite(2).

Небезопасно использовать filehandle.write() несколько раз для одного файла без ожидания разрешения (или отклонения) Promise. Для этой ситуации используйте fs.createWriteStream().

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

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

• string <строка>
• position <целое>
• encoding <строка> По умолчанию: 'utf8'
• Возвращает: <Promise>

Записывает string в файл. Если string не является строкой, значение будет преобразовано в строку.

Обещание Promise разрешается объектом, содержащим свойство bytesWritten , определяющее количество записанных байтов, и свойство buffer , содержащее ссылку на записанную string.

position указывает смещение от начала файла, куда должны быть записаны эти данные. Если тип position не является number, данные будут записаны в текущей позиции. См. pwrite(2).

encoding — ожидаемая кодировка строки.

Небезопасно использовать filehandle.write() несколько раз на одном файле без ожидания, пока Promise будет разрешен (или отклонен). Для этого случая используйте fs.createWriteStream().

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

filehandle.writeFile(data, options)

• data <строка> | <Буфер> | <Uint8Array>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
• Возвращает: <Обещание>

Асинхронно записывает данные в файл, заменяя файл, если он уже существует. data может быть строкой или буфером. Promise будет разрешено без аргументов при успехе.

Опция encoding игнорируется, если data является буфером.

Если options является строкой, то она задаёт кодировку.

Файл FileHandle должен поддерживать запись.

Небезопасно использовать filehandle.writeFile() несколько раз на одном файле без ожидания, пока Promise будет разрешен (или отклонен).

Если один или несколько вызовов filehandle.write() были сделаны для файлового дескриптора, а затем вызов filehandle.writeFile() , данные будут записаны с текущей позиции до конца файла. Данные не всегда записываются с начала файла.

filehandle.writev(buffers[, position])

• buffers <ArrayBufferView[]>
• position <целое число>
• Возвращает: <Обещание>

Записывает массив ArrayBufferView в файл.

Promise разрешается с объектом, содержащим свойство bytesWritten для определения количества записанных байтов и свойство buffers, содержащее ссылку на входной buffers.

position — это смещение с начала файла, где должны быть записаны эти данные. Если typeof position !== 'number', данные будут записаны в текущей позиции.

Небезопасно вызывать writev() несколько раз для одного и того же файла без ожидания завершения предыдущей операции.

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

fsPromises.access(path[, mode])

• path <строка> | <Буфер> | <URL>
• mode <целое число> По умолчанию: fs.constants.F_OK
• Возвращает: <Обещание>

Проверяет разрешения пользователя для файла или каталога, указанного path. Аргумент mode — это необязательное целое число, которое указывает проверки доступности, которые нужно выполнить. Возможные значения mode см. в Константы доступа к файлам. Можно создать маску, используя побитовое ИЛИ двух или более значений (например, fs.constants.W_OK | fs.constants.R_OK).

Если проверка доступности успешна, Promise разрешается без значения. Если любая проверка доступности завершается ошибкой, Promise отклоняется с объектом Error. Следующий пример проверяет, может ли файл /etc/passwd читаться и записываться текущим процессом.

const fs = require('fs');
const fsPromises = fs.promises;

fsPromises.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK)
  .then(() => console.log('can access'))
  .catch(() => console.error('cannot access'));

Использование fsPromises.access() для проверки доступности файла перед вызовом fsPromises.open() не рекомендуется. Это создаёт гонку, так как другие процессы могут изменить состояние файла между этими двумя вызовами. Вместо этого код должен открывать/читать/записывать файл непосредственно и обрабатывать ошибку, если файл недоступен.

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

• path <строка> | <Буфер> | <URL> | <FileHandle> имя файла или FileHandle
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'a'.
• Возвращает: <Обещание>

Асинхронно добавляет данные в файл, создавая файл, если он ещё не существует. data может быть строкой или Buffer. Promise будет разрешено без аргументов при успехе.

Если options — это строка, то она задаёт кодировку.

path может быть указан как FileHandle , который был открыт для добавления (используя fsPromises.open()).

fsPromises.chmod(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <строка> | <целое число>
• Возвращает: <Обещание>

Изменяет разрешения файла, затем разрешает Promise без аргументов при успехе.

fsPromises.chown(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое число>
• gid <целое число>
• Возвращает: <Обещание>

Изменяет владение файлом, затем разрешает Promise без аргументов при успехе.

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

• src <строка> | <Буфер> | <URL> исходное имя файла для копирования
• dest <строка> | <Буфер> | <URL> имя файла назначения для операции копирования
• flags <число> модификаторы для операции копирования. По умолчанию: 0.
• Возвращает: <Обещание>

Асинхронно копирует src в dest. По умолчанию, dest перезаписывается, если он уже существует. Promise будет разрешён без аргументов при успешном выполнении.

Node.js не гарантирует атомарность операции копирования. Если ошибка произошла после того, как целевой файл был открыт для записи, Node.js попытается удалить целевой файл.

flags — необязательное целое число, которое определяет поведение операции копирования. Можно создать маску, используя побитовое ИЛИ двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: Операция копирования завершится ошибкой, если dest уже существует.
• fs.constants.COPYFILE_FICLONE: Операция копирования попытается создать ссылку копирования с записью при изменении. Если платформа не поддерживает копирование с записью при изменении, используется механизм копирования по умолчанию.
• fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать ссылку копирования с записью при изменении. Если платформа не поддерживает копирование с записью при изменении, операция завершится ошибкой.

const fsPromises = require('fs').promises;

// destination.txt will be created or overwritten by default.
fsPromises.copyFile('source.txt', 'destination.txt')
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

Если третий аргумент — число, то оно определяет flags.

const fs = require('fs');
const fsPromises = fs.promises;
const { COPYFILE_EXCL } = fs.constants;

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL)
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

fsPromises.lchmod(path, mode)

• path <строка> | <Буфер> | <URL>
• mode <целое число>
• Возвращает: <Promise>

Изменяет разрешения на символическую ссылку, а затем разрешает Promise без аргументов при успешном выполнении. Этот метод реализован только на macOS.

fsPromises.lchown(path, uid, gid)

• path <строка> | <Буфер> | <URL>
• uid <целое число>
• gid <целое число>
• Возвращает: <Promise>

Изменяет владельца символической ссылки, а затем разрешает Promise без аргументов при успешном выполнении.

fsPromises.lutimes(path, atime, mtime)

• path <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• Возвращает: <Promise>

Изменяет время доступа и изменения файла так же, как fsPromises.utimes(), с отличием, что если путь относится к символической ссылке, то ссылка не разыменовывается: вместо этого изменяются метки времени самой символической ссылки.

При успешном выполнении Promise разрешается без аргументов.

fsPromises.link(existingPath, newPath)

• existingPath <строка> | <Буфер> | <URL>
• newPath <строка> | <Буфер> | <URL>
• Возвращает: <Promise>

Асинхронная link(2). Promise разрешается без аргументов при успешном выполнении.

fsPromises.lstat(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • bigint <логическое значение> Следует ли возвращать числовые значения в объекте fs.Stats типа bigint. По умолчанию: false.
• Возвращает: <Promise>

Асинхронная lstat(2). Promise разрешается с объектом fs.Stats для данной символической ссылки path.

fsPromises.mkdir(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект> | <целое число>
  • recursive <логическое значение> По умолчанию: false
  • mode <строка> | <целое число> Не поддерживается в Windows. По умолчанию: 0o777.
• Возвращает: <Promise>

Асинхронно создаёт директорию, затем разрешает Promise либо без аргументов, либо с первым созданным путём к директории, если recursive имеет значение true.

Необязательный аргумент options может быть целым числом, определяющим режим (разрешения и биты «sticky»), или объектом с свойством mode и свойством recursive, указывающими, должны ли создаваться родительские директории. Вызов fsPromises.mkdir(), когда path — существующая директория, приводит к отклонению только тогда, когда recursive имеет значение false.

fsPromises.mkdtemp(prefix[, options])

• prefix <строка>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• Возвращает: <Promise>

Создаёт уникальную временную директорию и разрешает Promise с созданным путём к директории. Уникальное имя директории генерируется путём добавления шести случайных символов в конец предоставленной prefix. Избегайте завершающих символов X в prefix из-за несовместимости платформ. Некоторые платформы, в частности BSD, могут возвращать более шести случайных символов и заменять завершающие символы X в prefix случайными символами.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом со свойством encoding, определяющим кодировку символов для использования.

fsPromises.mkdtemp(path.join(os.tmpdir(), 'foo-'))
  .catch(console.error);

Метод fsPromises.mkdtemp() добавит шесть случайных символов непосредственно в строку prefix. Например, если требуется создать временную директорию внутри /tmp, то prefix должна завершаться платформно-специфическим разделителем пути (require('path').sep).

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

• path <строка> | <Буфер> | <URL>
• flags <строка> | <число> Смотрите поддержку флагов файловой системы flags. По умолчанию: 'r'.
• mode <строка> | <целое> По умолчанию: 0o666 (чтение и запись)
• Возвращает: <Promise>

Асинхронное открытие файла, возвращающее Promise, который, при разрешении, возвращает объект FileHandle. Смотрите open(2).

mode задаёт режим файла (разрешения и биты "sticky"), но только если файл был создан.

Некоторые символы (< > : " / \ | ? *) зарезервированы в Windows, как документировано в имени файла, пути и именах. В NTFS, если имя файла содержит двоеточие, Node.js откроет поток файловой системы, как описано на странице MSDN.

fsPromises.opendir(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • bufferSize <число> Количество записей каталога, которые буферизуются во время чтения из каталога. Более высокие значения ведут к лучшей производительности, но и большему использованию памяти. По умолчанию: 32
• Возвращает: <Promise> содержащий <fs.Dir>

Асинхронно открывает каталог. Смотрите opendir(3).

Создаёт fs.Dir, который содержит все дальнейшие функции для чтения из каталога и его очистки.

Параметр encoding задаёт кодировку для path при открытии каталога и последующих операциях чтения.

Пример использования асинхронной итерации:

const fs = require('fs');

async function print(path) {
  const dir = await fs.promises.opendir(path);
  for await (const dirent of dir) {
    console.log(dirent.name);
  }
}
print('./').catch(console.error);

fsPromises.readdir(path[, options])

• path <строка> | <Буфер> | <URL>
• options <Объект>
  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <логическое> По умолчанию: false
• Возвращает: <Promise>

Читает содержимое каталога и разрешает Promise массивом имён файлов в каталоге, исключая '.' и '..'.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом с свойством encoding, задающим кодировку символов для имён файлов. Если encoding установлено в 'buffer', возвращаемые имена файлов будут представлены как объекты Buffer.

Если options.withFileTypes установлено в true, возвращаемый массив будет содержать объекты fs.Dirent.

const fs = require('fs');

async function print(path) {
  const files = await fs.promises.readdir(path);
  for (const file of files) {
    console.log(file);
  }
}
print('./').catch(console.error);

fsPromises.readFile(path[, options])

• path <строка> | <Буфер> | <URL> | <Дескриптор файла> имя файла или FileHandle
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> Смотрите поддержку флагов файловой системы flags. По умолчанию: 'r'.
• Возвращает: <Promise>

Асинхронно читает всё содержимое файла.

Promise разрешается содержимым файла. Если кодировка не указана (используя options.encoding), данные возвращаются как объект Buffer. В противном случае данные будут строкой.

Если options является строкой, то она задаёт кодировку.

Если path является каталогом, поведение fsPromises.readFile() зависит от платформы. На macOS, Linux и Windows обещание будет отклонено с ошибкой. На FreeBSD будет возвращено представление содержимого каталога.

Любая указанная FileHandle должна поддерживать чтение.

fsPromises.readlink(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'
• Возвращает: <Promise>

Асинхронная readlink(2). Promise разрешается с linkString при успехе.

Необязательный аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding для кодировки символов для возвращаемого пути к ссылке. Если encoding установлено в 'buffer', возвращаемый путь к ссылке будет представлен как объект Buffer.

fsPromises.realpath(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> Значение по умолчанию: 'utf8'
• Возвращает: <Promise>

Определяет фактическое расположение path с использованием той же семантики, что и функция fs.realpath.native(), а затем разрешает Promise с разрешённым путём.

Поддерживаются только пути, которые можно преобразовать в строки UTF8.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом со свойством encoding, определяющим кодировку символов для использования в пути. Если свойство encoding установлено в значение 'buffer', возвращаемый путь будет передан как объект Buffer.

В Linux, когда Node.js связан с musl libc, для работы этой функции файловая система procfs должна быть смонтирована в /proc. Glibc не имеет такого ограничения.

fsPromises.rename(oldPath, newPath)

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Возвращает: <Promise>

Переименовывает oldPath в newPath и разрешает Promise без аргументов при успешном выполнении.

fsPromises.rmdir(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Если возникает ошибка EBUSY, EMFILE, ENFILE, ENOTEMPTY, или EPERM, Node.js повторно выполнит операцию с линейным экспоненциальным ожиданием в retryDelay мс дольше на каждой попытке. Эта опция представляет количество повторных попыток. Эта опция игнорируется, если опция recursive не равна true. Значение по умолчанию: 0.
  • recursive <boolean> Если true, выполнить рекурсивное удаление каталога. В рекурсивном режиме, ошибки не сообщаются, если path не существует, и операции повторяются при ошибке. Значение по умолчанию: false.
  • retryDelay <integer> Время ожидания между повторными попытками в миллисекундах. Эта опция игнорируется, если опция recursive не равна true. Значение по умолчанию: 100.
• Возвращает: <Promise>

Удаляет каталог, идентифицированный path, а затем разрешает Promise без аргументов при успешном выполнении.

Использование fsPromises.rmdir() на файле (не каталоге) приводит к тому, что Promise отклоняется с ошибкой ENOENT на Windows и ошибкой ENOTDIR на POSIX.

fsPromises.stat(path[, options])

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> Указать, должны ли числовые значения в возвращаемом объекте fs.Stats быть типа bigint. Значение по умолчанию: false.
• Возвращает: <Promise>

Значение Promise разрешается с объектом fs.Stats для данного path.

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

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> Значение по умолчанию: 'file'
• Возвращает: <Promise>

Создаёт символическую ссылку, а затем разрешает Promise без аргументов при успешном выполнении.

Аргумент type используется только на платформах Windows и может быть 'dir', 'file', или 'junction'. Для создания junction points на Windows требуется абсолютный путь к целевому файлу. При использовании 'junction', аргумент target будет автоматически приведен к абсолютному пути.

fsPromises.truncate(path[, len])

• path <string> | <Buffer> | <URL>
• len <integer> Значение по умолчанию: 0
• Возвращает: <Promise>

Усекает path, а затем разрешает Promise без аргументов при успешном выполнении. Аргумент path должен быть строкой или Buffer.

fsPromises.unlink(path)

• path <string> | <Buffer> | <URL>
• Возвращает: <Promise>

Асинхронная функция unlink(2). Значение Promise разрешается без аргументов при успешном выполнении.

fsPromises.utimes(path, atime, mtime)

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Возвращает: <Promise>

Измените временные метки файла, на который ссылается path, затем разрешит Promise без аргументов при успехе.

Аргументы atime и mtime следуют этим правилам:

• Значения могут быть либо числами, представляющими временную метку эпохи Unix, Date, либо числовой строкой, например, '123456789.0'.
• Если значение не может быть преобразовано в число или является NaN, Infinity или -Infinity, будет выброшено исключение Error.

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

• file <string> | <Buffer> | <URL> | <FileHandle> имя файла или FileHandle
• data <string> | <Buffer> | <Uint8Array>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
• Возвращает: <Promise>

Асинхронно записывает данные в файл, перезаписывая файл, если он уже существует. data может быть строкой или буфером. Promise будет разрешён без аргументов при успехе.

Опция encoding игнорируется, если data является буфером.

Если options является строкой, она указывает кодировку.

Любой указанный FileHandle должен поддерживать запись.

Небезопасно использовать fsPromises.writeFile() несколько раз на одном файле без ожидания, пока Promise будет разрешён (или отклонён).

Константы FS

Следующие константы экспортируются fs.constants.

Не все константы будут доступны на всех операционных системах.

Чтобы использовать более одной константы, используйте побитовое ИЛИ | оператор.

Пример:

const fs = require('fs');

const {
  O_RDWR,
  O_CREAT,
  O_EXCL
} = fs.constants;

fs.open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
  // ...
});

Константы доступа к файлам

Следующие константы предназначены для использования с fs.access().

Константы копирования файлов

Следующие константы предназначены для использования с fs.copyFile().

Константы открытия файлов

Следующие константы предназначены для использования с fs.open().

Константы типа файлов

Следующие константы предназначены для использования со свойством mode объекта fs.Stats для определения типа файла.

Константы режимов файлов

Следующие константы предназначены для использования со свойством mode объекта fs.Stats для определения прав доступа к файлу.