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

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

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

const fs = require('fs');

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

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

const fs = require('fs');

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

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

const fs = require('fs');

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

При использовании асинхронных методов нет гарантированного порядка. Поэтому следующее подвержено ошибкам, так как операция 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)}`);
  });
});

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

Хотя это не рекомендуется, большинство функций fs допускают опускание аргумента обратного вызова, в этом случае используется по умолчанию обратный вызов, который повторно выбрасывает ошибки. Для получения трассировки до исходного места вызова установите переменную среды NODE_DEBUG:

Опускание функции обратного вызова в асинхронных функциях fs устарело и в будущем может привести к выбросу ошибки.

$ cat script.js
function bad() {
  require('fs').readFile('/');
}
bad();

$ env NODE_DEBUG=fs node script.js
fs.js:88
        throw backtrace;
        ^
Error: EISDIR: illegal operation on a directory, read
    <stack trace.>

Пути к файлам

Большинство операций 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, file: URL с хост-именем преобразуются в UNC-пути, в то время как file: 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 с буквами дисков должны использовать : в качестве разделителя сразу после буквы диска. Использование другого разделителя приведёт к выбросу.

На всех остальных платформах file: 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'));

file: 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 file: 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.Dirent

При вызове 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 (first-in-first-out).

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

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

Все объекты fs.FSWatcher являются EventEmitter, которые будут испускать событие '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 <Ошибка>

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

watcher.close()

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

Класс: fs.ReadStream

Успешное выполнение fs.createReadStream() вернёт новый объект fs.ReadStream.

Все объекты fs.ReadStream являются Потоками-читателями.

Событие: 'close'

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

Событие: 'open'

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

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

Событие: 'ready'

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

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

readStream.bytesRead

• <число>

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

readStream.path

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

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

readStream.pending

• <логическое значение>

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

Класс: fs.Stats

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

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

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:

Stats {
  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,
  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()

• Возвращает: <логическое значение>

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

stats.isCharacterDevice()

• Возвращает: <логическое значение>

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

stats.isDirectory()

• Возвращает: <логическое значение>

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

stats.isFIFO()

• Возвращает: <логическое значение>

Возвращает true, если объект fs.Stats описывает пайп «первым вошел, первым вышел» (FIFO).

stats.isFile()

• Возвращает: <логическое значение>

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

stats.isSocket()

• Возвращает: <логическое значение>

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

stats.isSymbolicLink()

• Возвращает: <логическое значение>

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

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

stats.dev

• <число> | <bigint>

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

stats.ino

• <число> | <bigint>

Специфичный для файловой системы номер «узла» файла.

stats.mode

• <число> | <bigint>

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

stats.nlink

• <число> | <bigint>

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

stats.uid

• <число> | <bigint>

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

stats.gid

• <число> | <bigint>

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

stats.rdev

• <число> | <bigint>

Числовой идентификатор устройства, если файл считается «специальным».

stats.size

• <число> | <bigint>

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

stats.blksize

• <число> | <bigint>

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

stats.blocks

• <число> | <bigint>

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

stats.atimeMs

• <число> | <bigint>

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

stats.mtimeMs

• <число> | <bigint>

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

stats.ctimeMs

• <число> | <bigint>

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

stats.birthtimeMs

• <число> | <bigint>

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

stats.atime

• <Date>

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

stats.mtime

• <Date>

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

stats.ctime

• <Date>

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

stats.birthtime

• <Date>

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

Значения времени объекта stat

Свойства atimeMs, mtimeMs, ctimeMs, birthtimeMs являются числами, содержащими соответствующие значения времени в миллисекундах. Их точность зависит от платформы. 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

WriteStream является потоком для записи.

Событие: '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)[src]

• 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])[src]

• 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)[src]

• 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])[src]

• 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)[src]

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

• callback <Функция>

  • err <Ошибка>

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

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

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

Аргумент 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)[src]

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

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

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

fs.chown(path, uid, gid, callback)[src]

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

• callback <Функция>

  • err <Ошибка>

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

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

fs.chownSync(path, uid, gid)[src]

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

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

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

fs.close(fd, callback)[src]

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

• callback <Функция>

  • err <Ошибка>

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

fs.closeSync(fd)[src]

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

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

fs.constants

• <Объект>

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

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

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

Асинхронно копирует 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 — операция копирования попытается создать копию с разделяемой записью (copy-on-write reflink). Если платформа не поддерживает copy-on-write, используется резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE — операция копирования попытается создать копию с разделяемой записью (copy-on-write reflink). Если платформа не поддерживает copy-on-write, операция завершится ошибкой.

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]

• src <string> | <Buffer> | <URL> имя исходного файла для копирования
• dest <string> | <Buffer> | <URL> имя целевого файла для копирования
• flags <number> модификаторы для операции копирования. По умолчанию: 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 — операция копирования попытается создать копию с разделяемой записью (copy-on-write reflink). Если платформа не поддерживает copy-on-write, используется резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE — операция копирования попытается создать копию с разделяемой записью (copy-on-write reflink). Если платформа не поддерживает copy-on-write, операция завершится ошибкой.

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

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

• options <string> | <Object>

  • flags <string> См. поддержку флагов файловой системы flags. По умолчанию: 'r'.
  • encoding <string> По умолчанию: null
  • fd <integer> По умолчанию: null
  • mode <integer> По умолчанию: 0o666
  • autoClose <boolean> По умолчанию: true
  • start <integer>
  • end <integer> По умолчанию: Infinity
  • highWaterMark <integer> По умолчанию: 64 * 1024
• Возвращает: <fs.ReadStream> См. Потоки чтения (Readable Streams).

В отличие от стандартного значения 16 КБ для потока чтения, по умолчанию у потока, возвращаемого данным методом, размер буфера highWaterMark составляет 64 КБ.

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

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

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

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 равно false, дескриптор файла не будет закрыт даже при ошибке. Приложение должно закрыть его и убедиться, что нет утечки дескриптора файла. Если autoClose установлено в true (по умолчанию), при 'error' или 'end' дескриптор файла будет автоматически закрыт.

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

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

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

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

fs.createWriteStream(path[, options])[src]

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

• options <строка> | <Объект>

  • flags <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
  • encoding <строка> По умолчанию: 'utf8'
  • fd <целое число> По умолчанию: null
  • mode <целое число> По умолчанию: 0o666
  • autoClose <логическое значение> По умолчанию: true
  • start <целое число>
• Возвращает: <fs.WriteStream> См. Поток Writable.

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

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

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

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

fs.exists(path, callback)[src]

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

• callback <Функция>

  • exists <логическое значение>

Проверяет существование заданного пути, проверив его в файловой системе. Затем вызывает аргумент 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() не рекомендуется. Это вводит гонку, так как другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен напрямую открыть/читать/записать файл и обработать ошибку, если файл не существует.

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

fs.exists('myfile', (exists) => {
  if (exists) {
    console.error('myfile already exists');
  } else {
    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.exists('myfile', (exists) => {
  if (exists) {
    fs.open('myfile', 'r', (err, fd) => {
      if (err) throw err;
      readMyData(fd);
    });
  } else {
    console.error('myfile does not exist');
  }
});

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

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

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

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

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

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

fs.fchmod(fd, mode, callback)[src]

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

• callback <Функция>

  • err <Ошибка>

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

fs.fchmodSync(fd, mode)[src]

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

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

fs.fchown(fd, uid, gid, callback)[src]

• fd <целое>
• uid <целое>
• gid <целое>

• callback <Функция>

  • err <Ошибка>

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

fs.fchownSync(fd, uid, gid)[src]

• fd <целое>
• uid <целое>
• gid <целое>

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

fs.fdatasync(fd, callback)[src]

• fd <целое>

• callback <Функция>

  • err <Ошибка>

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

fs.fdatasyncSync(fd)[src]

• fd <целое>

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

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

• fd <целое>

• options <Объект>

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

• callback <Функция>

  • err <Ошибка>
  • stats <fs.Stats>

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

fs.fstatSync(fd[, options])[src]

• fd <целое>

• options <Объект>

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

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

fs.fsync(fd, callback)[src]

• fd <целое>

• callback <Функция>

  • err <Ошибка>

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

fs.fsyncSync(fd)[src]

• fd <целое>

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

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

• 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])[src]

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

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

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

fs.futimes(fd, atime, mtime, callback)[src]

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

• callback <Функция>

  • err <Ошибка>

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

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

fs.futimesSync(fd, atime, mtime)[src]

• 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)[src]

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

• callback <Функция>

  • err <Ошибка>

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

fs.lchownSync(path, uid, gid)[src]

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

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

fs.link(existingPath, newPath, callback)[src]

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

• callback <Функция>

  • err <Ошибка>

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

fs.linkSync(existingPath, newPath)[src]

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

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

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

• path <строка> | <Buffer> | <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])[src]

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

• options <Объект>

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

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

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

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

• options <Объект> | <целое число>

  • recursive <логическое> По умолчанию: false
  • mode <целое число> Не поддерживается в Windows. По умолчанию: 0o777.

• callback <Функция>

  • err <Ошибка>

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

Необязательный аргумент options может быть целым числом, определяющим режим (разрешения и биты "sticky"), или объектом со свойством mode и свойством recursive, указывающим, нужно ли создавать родительские папки.

// 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])[src]

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

• options <Объект> | <целое число>

  • recursive <логическое значение> По умолчанию: false
  • mode <целое число> Не поддерживается в Windows. По умолчанию: 0o777.

Синхронно создаёт директорию. Возвращает undefined. Это синхронная версия fs.mkdir().

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

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

• prefix <строка>

• options <строка> | <Объект>

  • encoding <строка> По умолчанию: 'utf8'

• callback <Функция>

  • err <Ошибка>
  • folder <строка>

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

Генерирует шесть случайных символов, которые добавляются к необходимому prefix для создания уникальной временной директории.

Путь к созданной папке передаётся в качестве строки второму параметру коллбэка.

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

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

Метод fs.mkdtemp() будет добавлять шесть случайных символов непосредственно к строке prefix. Например, если задана директория /tmp и нужно создать временную директорию *внутри* /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, folder) => {
  if (err) throw err;
  console.log(folder);
  // 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, folder) => {
  if (err) throw err;
  console.log(folder);
  // Will print something similar to `/tmp/abc123`.
  // A new temporary directory is created within
  // the /tmp directory.
});

fs.mkdtempSync(prefix[, options])[src]

• prefix <строка>

• options <строка> | <Объект>

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

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

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

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

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

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

• callback <Функция>

  • err <Ошибка>
  • fd <число>

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

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

Коллбэк получает два аргумента (err, fd).

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

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

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

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

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

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

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

• fd <целое>
• buffer <Буфер> | <Массив типов данных> | <DataView>
• offset <целое>
• length <целое>
• position <целое>

• callback <Функция>

  • err <Ошибка>
  • bytesRead <целое>
  • buffer <Буфер>

Чтение данных из файла, указанного fd.

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

offset — смещение в буфере для начала записи.

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

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

Обработчик получает три аргумента: (err, bytesRead, buffer).

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

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

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

• options <строка> | <Объект>

  • encoding <строка> По умолчанию: 'utf8'
  • withFileTypes <булево> По умолчанию: false

• callback <Функция>

  • err <Ошибка>
  • files <массив строк> | <массив буферов> | <массив fs.Dirent>

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

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

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

fs.readdirSync(path[, options])[src]

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

• options <строка> | <Объект>

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

Синхронное чтение содержимого каталога.

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

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

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

• 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])[src]

• 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)[src]

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

• options <строка> | <Объект>

  • encoding <строка> По умолчанию: 'utf8'

• callback <Функция>

  • err <Ошибка>
  • linkString <строка> | <Буфер>

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

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

fs.readlinkSync(path[, options])[src]

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

• options <строка> | <Объект>

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

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

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

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

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

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

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

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

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

• options <строка> | <Объект>

  • encoding <строка> По умолчанию: 'utf8'

• callback <Функция>

  • err <Ошибка>
  • resolvedPath <строка> | <Буфер>

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

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

Эта функция ведет себя как 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])[src]

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

• options <string> | <Object>

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

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

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

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

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

• options <string> | <Object>

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

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

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

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

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

fs.rename(oldPath, newPath, callback)[src]

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

• callback <Function>

  • err <Error>

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

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

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

fs.renameSync(oldPath, newPath)[src]

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

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

fs.rmdir(path, callback)[src]

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

• callback <Function>

  • err <Error>

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

Применение fs.rmdir() к файлу (а не каталогу) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

fs.rmdirSync(path)[src]

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

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

Применение fs.rmdirSync() к файлу (а не каталогу) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

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

• path <строка> | <Buffer> | <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().

fs.statSync(path[, options])[src]

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

• options <Объект>

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

Синхронная функция stat(2).

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

• target <строка> | <Buffer> | <URL>
• path <строка> | <Buffer> | <URL>
• type <строка> По умолчанию: 'file'

• callback <Функция>

  • err <Ошибка>

Асинхронная функция symlink(2). Никаких аргументов, кроме возможной ошибки, не передаётся обратному вызову. Аргумент type может быть 'dir', 'file' или 'junction' и доступен только на Windows (игнорируется на других платформах). Для создания джойнтов Windows требуется абсолютный путь к целевому файлу. При использовании 'junction' аргумент target будет автоматически нормализован до абсолютного пути.

Пример:

fs.symlink('./foo', './new-port', callback);

Создаёт символическую ссылку "new-port" на "foo".

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

• target <строка> | <Buffer> | <URL>
• path <строка> | <Buffer> | <URL>
• type <строка> По умолчанию: 'file'

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

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

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

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

• callback <Функция>

  • err <Ошибка>

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

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

fs.truncateSync(path[, len])[src]

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

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

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

fs.unlink(path, callback)[src]

• 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)[src]

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

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

fs.unwatchFile(filename[, listener])[src]

• 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)[src]

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

• callback <Функция>

  • err <Ошибка>

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

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

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

fs.utimesSync(path, atime, mtime)[src]

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

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

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

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

• 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.

Доступность

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

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

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

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

Иноды

В системах 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)[src]

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

• options <Объект>

  • bigint <логическое> По умолчанию: false
  • persistent <логическое> По умолчанию: true
  • interval <целое число> По умолчанию: 5007

• listener <Функция>

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

Отслеживание изменений в 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). В Windows поля blksize и blocks будут undefined вместо нуля. Если файл будет создан позже, слушатель будет вызван снова с последними объектами stat. Это изменение функциональности с версии 0.10.

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

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

Это происходит в следующих случаях:

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

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

• 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)[src]

• 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)[src]

• 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>

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

Параметр 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().

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

1. Любой указанный дескриптор файла должен поддерживать запись.
2. Если дескриптор файла указан как file, он не будет закрыт автоматически.
3. Запись начнется с начала файла. Например, если в файле уже были 'Hello World', а новые записанные данные – 'Aloha', то содержимое файла будет 'Aloha World', а не просто 'Aloha'.

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

• 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]]])[src]

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

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

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

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

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

fs Promises API

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

Класс: FileHandle

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

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

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

filehandle.appendFile(data, options)

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

• options <Объект> | <строка>

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

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

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

Файл должен быть открыт для добавления.

filehandle.chmod(mode)

• mode <целое число>
• Возвращает: <Обещание>

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

filehandle.chown(uid, gid)

• uid <целое число>
• gid <целое число>
• Возвращает: <Обещание>

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

filehandle.close()

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

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

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

• Возвращает: <Обещание>

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

filehandle.fd

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

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

• buffer <Буфер> | <Uint8 массив>
• offset <целое число>
• length <целое число>
• position <целое число>
• Возвращает: <Обещание>

Считывает данные из файла.

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

offset — смещение в буфере для начала записи.

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

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

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

filehandle.readFile(options)

• options <Объект> | <строка>

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

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

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

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

Если path — это директория, поведение fsPromises.readFile() зависит от платформы. В macOS, Linux и Windows обещание будет отклонено с ошибкой. В FreeBSD вернётся представление содержимого директории.

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

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

filehandle.stat([options])

• options <Объект>

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

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

filehandle.sync()

• Возвращает: <Обещание>

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

filehandle.truncate(len)

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

Укорачивает файл, после чего обещание 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'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку файловой системы flags. По умолчанию: 'w'.
• Возвращает: <Promise>

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

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

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

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

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

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

fsPromises.access(path[, mode])

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

Проверяет разрешения пользователя для файла или каталога, указанного 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
• data <строка> | <Буфер>

• options <Объект> | <строка>

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

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

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

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

fsPromises.chmod(path, mode)

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

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

fsPromises.chown(path, uid, gid)

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

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

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

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

Асинхронно копирует 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 — операция копирования попытается создать копию с использованием reflink. Если платформа не поддерживает copy-on-write, будет использован резервный механизм копирования.
• fs.constants.COPYFILE_FICLONE_FORCE — операция копирования попытается создать копию с использованием reflink. Если платформа не поддерживает copy-on-write, операция завершится ошибкой.

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.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 без аргументов при успехе.

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

fsPromises.mkdtemp(prefix[, options])

• prefix <строка>

• options <строка> | <Объект>

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

Создаёт уникальную временную директорию и разрешает Promise с путём созданной папки. Уникальное имя директории генерируется путём добавления шести случайных символов в конец предоставленной prefix.

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

fsPromises.mkdtemp(path.join(os.tmpdir(), 'foo-'))
  .catch(console.error);

Метод fsPromises.mkdtemp() будет добавлять шесть случайных символов непосредственно к строке prefix. Например, при заданной директории /tmp, если необходимо создать временную директорию *внутри* /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, как документировано в Naming Files, Paths, and Namespaces. В NTFS, если имя файла содержит двоеточие, Node.js откроет поток файловой системы, как описано в этой странице MSDN.

fsPromises.readdir(path[, options])

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

• options <строка> | <Объект>

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

Считывает содержимое директории и разрешает Promise с массивом имён файлов в директории, исключая '.' и '..'.

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

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

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 <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> По умолчанию: '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)

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

Удаляет директорию, идентифицированную по path, затем разрешает Promise без аргументов в случае успеха.

Использование fsPromises.rmdir() на файле (а не на каталоге) приводит к тому, что Promise отклоняется с ошибкой ENOENT на Windows и ошибкой ENOTDIR на POSIX.

fsPromises.stat(path[, options])

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

• options <Object>

  • bigint <boolean> Нужно ли использовать тип bigint для числовых значений в возвращаемом объекте fs.Stats. По умолчанию: 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'. Для создания джойнт-пунктов (Windows junction points) путь назначения должен быть абсолютным. При использовании '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 <строка> | <Буфер> | <URL>
• atime <число> | <строка> | <Дата>
• mtime <число> | <строка> | <Дата>
• Возвращает: <Promise>

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

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

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

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

• file <строка> | <Буфер> | <URL> | <Файловый дескриптор> имя файла или FileHandle
• data <строка> | <Буфер> | <Uint8Array>

• options <Объект> | <строка>

  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <строка> См. поддержку флагов файловой системы flags. По умолчанию: 'w'.
• Возвращает: <Promise>

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

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

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

Любой указанный FileHandle должен поддерживать запись.

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

Константы FS

Следующие константы экспортируются fs.constants.

Не каждая константа будет доступна на каждой операционной системе.

Константы доступа к файлам

Следующие константы предназначены для использования с fs.access().

Константы копирования файлов

Следующие константы предназначены для использования с fs.copyFile().

Константы открытия файлов

Следующие константы предназначены для использования с fs.open().

Константы типов файлов

Следующие константы предназначены для использования со свойством mode объекта fs.Stats для определения типа файла.

Константы режимов файла

Следующие константы предназначены для использования со свойством mode объекта fs.Stats для определения разрешений доступа к файлу.

Флаги файловой системы

Следующие флаги доступны там, где опция flag принимает строку:

• 'a' - Открыть файл для добавления. Файл создается, если он не существует.

• 'ax' - Аналогично 'a', но завершается ошибкой, если путь существует.

• 'a+' - Открыть файл для чтения и добавления. Файл создается, если он не существует.

• 'ax+' - Аналогично 'a+', но завершается ошибкой, если путь существует.

• 'as' - Открыть файл для добавления в синхронном режиме. Файл создается, если он не существует.

• 'as+' - Открыть файл для чтения и добавления в синхронном режиме. Файл создается, если он не существует.

• 'r' - Открыть файл для чтения. Возникает исключение, если файл не существует.

• 'r+' - Открыть файл для чтения и записи. Возникает исключение, если файл не существует.

• 'rs+' - Открыть файл для чтения и записи в синхронном режиме. Инструктирует операционную систему обойти локальный кэш файловой системы.

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

  Это не превращает fs.open() или fsPromises.open() в синхронный блокирующий вызов. Если желательно синхронное выполнение, следует использовать что-то вроде fs.openSync().

• 'w' - Открыть файл для записи. Файл создается (если он не существует) или обрезается (если он существует).

• 'wx' - Аналогично 'w', но завершается ошибкой, если путь существует.

• 'w+' - Открыть файл для чтения и записи. Файл создается (если он не существует) или обрезается (если он существует).

• 'wx+' - Аналогично 'w+', но завершается ошибкой, если путь существует.

flag также может быть числом, как указано в open(2); общепринятые константы доступны в fs.constants. В Windows флаги переводятся в эквивалентные, если применимо, например, O_WRONLY в FILE_GENERIC_WRITE или O_EXCL|O_CREAT в CREATE_NEW, как принимается CreateFileW.

Исключительный флаг 'x' (флаг O_EXCL в open(2)) гарантирует, что путь создается заново. В системах POSIX путь считается существующим, даже если он является символической ссылкой на несуществующий файл. Исключительный флаг может работать или не работать с сетевыми файловыми системами.

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

Изменение файла вместо его замещения может потребовать режим флагов 'r+' вместо стандартного режима 'w'.

Поведение некоторых флагов зависит от платформы. Поэтому при открытии каталога на macOS и Linux с флагом 'a+' (см. пример ниже) будет возвращена ошибка. В отличие от этого, в Windows и FreeBSD будет возвращен дескриптор файла или FileHandle.

// macOS and Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
});

// Windows and FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
});

В Windows открытие существующего скрытого файла с флагом 'w' (через fs.open(), fs.writeFile() или fsPromises.open()) завершится ошибкой EPERM. Существующие скрытые файлы можно открыть для записи с флагом 'r+'.

Для сброса содержимого файла можно использовать вызов fs.ftruncate() или filehandle.truncate().