Файловая система

Ввод-вывод файлов обеспечивается простыми оболочками вокруг стандартных функций POSIX. Для использования этого модуля сделайте require('fs'). Все методы имеют асинхронные и синхронные формы.

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

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

Вот пример асинхронной версии:

const fs = require('fs');

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

Вот синхронная версия:

const fs = require('fs');

fs.unlinkSync('/tmp/hello');
console.log('successfully deleted /tmp/hello');

При использовании асинхронных методов нет гарантированного порядка. Поэтому следующее подвержено ошибкам:

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

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

Можно использовать относительный путь к имени файла. Однако помните, что этот путь будет относительным к process.cwd().

Хотя это не рекомендуется, большинство функций 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.>

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

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

Использование пула потоков

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

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

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

const fs = require('fs');
const { URL } = require('url');
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 */

API буфера

Функции fs поддерживают передачу и получение путей как строк, так и буферов. Последнее предназначено для работы с файловыми системами, которые позволяют использовать имена файлов, не являющиеся UTF-8. Для большинства типичных случаев работа с путями в виде буферов будет излишней, так как API строк автоматически преобразует в UTF-8 и из него.

Примечание: В некоторых файловых системах (например, NTFS и HFS+) имена файлов всегда кодируются как UTF-8. В таких файловых системах передача не UTF-8 кодированных буферов функциям fs не будет работать как ожидается.

Класс: fs.FSWatcher

Объекты, возвращаемые из fs.watch(), относятся к этому типу.

Обратный вызов listener предоставленный fs.watch() получает события change возвращенного объекта FSWatcher.

Сам объект излучает эти события:

Событие: 'change'

• eventType <строка> Тип изменения fs
• filename <строка> | <Буфер> Измененный файл (если применимо/доступно)

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

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

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

Событие: 'error'

• error <Ошибка>

Издается при возникновении ошибки.

watcher.close()

Остановить отслеживание изменений в указанном fs.FSWatcher.

Класс: fs.ReadStream

ReadStream является потоком Readable Stream.

Событие: 'close'

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

Событие: 'open'

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

Издается, когда файл ReadStream открыт.

readStream.bytesRead

Количество прочитанных байтов.

readStream.path

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

Класс: fs.Stats

Объекты, возвращаемые из fs.stat(), fs.lstat() и fs.fstat() и их синхронных аналогов, относятся к этому типу.

• stats.isFile()
• stats.isDirectory()
• stats.isBlockDevice()
• stats.isCharacterDevice()
• stats.isSymbolicLink() (действительно только с fs.lstat())
• stats.isFIFO()
• stats.isSocket()

Для обычного файла util.inspect(stats) вернёт строку, очень похожую на эту:

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 }

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

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

Временные метки в объекте 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 v0.12, ctime содержало birthtime на системах Windows. Обратите внимание, что начиная с версии v0.12, ctime не является «временем создания», и на Unix-системах никогда им и не было.

Класс: fs.WriteStream

WriteStream является Потоком Writable Stream.

Событие: 'close'

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

Событие: 'open'

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

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

writeStream.bytesWritten

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

writeStream.path

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

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

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

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

• fs.constants.F_OK - Файл path виден вызывающему процессу. Это полезно для определения наличия файла, но ничего не говорит о rwx правах доступа. По умолчанию, если mode не указан.
• fs.constants.R_OK - Файл path может быть прочитан вызывающим процессом.
• fs.constants.W_OK - Файл path может быть записан вызывающим процессом.
• fs.constants.X_OK - Файл path может быть выполнен вызывающим процессом. Это не имеет эффекта на Windows (будет вести себя как fs.constants.F_OK).

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

fs.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK, (err) => {
  console.log(err ? 'no access!' : 'can read/write');
});

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

Например:

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

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

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

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

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

    throw err;
  }

  writeMyData(fd);
});

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

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

    throw err;
  }

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

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

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

    throw err;
  }

  readMyData(fd);
});

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

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

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

fs.accessSync(path[, mode])

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

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

• fs.constants.F_OK - Файл path виден вызывающему процессу. Это полезно для определения наличия файла, но ничего не говорит о rwx правах доступа. По умолчанию, если mode не указан.
• fs.constants.R_OK - Файл path может быть прочитан вызывающим процессом.
• fs.constants.W_OK - Файл path может быть записан вызывающим процессом.
• fs.constants.X_OK - Файл path может быть выполнен вызывающим процессом. Это не имеет эффекта на Windows (будет вести себя как fs.constants.F_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(file, data[, options], callback)

• file <string> | <Buffer> | <URL> | <number> имя файла или дескриптор файла
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <integer> По умолчанию: 0o666
  • flag <string> По умолчанию: '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);

file может быть указан как числовой дескриптор файла, открытого для добавления (используя 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(file, data[, options])

• file <string> | <Buffer> | <URL> | <number> имя файла или дескриптор файла
• data <string> | <Buffer>
• options <Объект> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <string> По умолчанию: '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');

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

let fd;

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

fs.chmod(path, mode, callback)

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

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

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

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

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

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

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

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

fs.chmodSync(path, mode)

• path <string> | <Buffer> | <URL>
• mode <целое число>

Синхронно изменяет разрешения файла. Возвращает undefined. Это синхронная версия fs.chmod().

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

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

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

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

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

fs.chownSync(path, uid, gid)

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

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

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

fs.close(fd, callback)

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

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

fs.closeSync(fd)

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

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

fs.constants

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

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

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

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

flags — необязательное целое число, которое задаёт поведение операции копирования. Поддерживается только флаг fs.constants.COPYFILE_EXCL, который заставляет операцию копирования завершиться неудачей, если dest уже существует.

Пример:

const fs = require('fs');

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

Если третий аргумент является числом, то он задаёт flags, как показано в следующем примере.

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

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

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

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

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

flags — необязательное целое число, которое задаёт поведение операции копирования. Поддерживается только флаг fs.constants.COPYFILE_EXCL, который заставляет операцию копирования завершиться неудачей, если dest уже существует.

Пример:

const fs = require('fs');

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

Если третий аргумент является числом, то он задаёт flags, как показано в следующем примере.

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

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

fs.createReadStream(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • flags <строка>
  • encoding <строка>
  • fd <целое число>
  • mode <целое число>
  • autoClose <логическое значение>
  • start <целое число>
  • end <целое число>
  • highWaterMark <целое число>

Возвращает новый объект ReadStream. (См. Поток чтения).

Обратите внимание, что в отличие от значения по умолчанию для highWaterMark в потоке чтения (16 КБ), поток, возвращаемый этим методом, имеет значение по умолчанию 64 КБ для того же параметра.

options — это объект или строка со следующими значениями по умолчанию:

const defaults = {
  flags: 'r',
  encoding: null,
  fd: null,
  mode: 0o666,
  autoClose: true,
  highWaterMark: 64 * 1024
};

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

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

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

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

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

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

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

fs.createWriteStream(path[, options])

• path <строка> | <Буфер> | <URL>
• options <строка> | <Объект>
  • flags <строка>
  • encoding <строка>
  • fd <целое число>
  • mode <целое число>
  • autoClose <логическое значение>
  • start <целое число>

Возвращает новый объект WriteStream. (См. Поток записи).

options — это объект или строка со следующими значениями по умолчанию:

const defaults = {
  flags: 'w',
  encoding: 'utf8',
  fd: null,
  mode: 0o666,
  autoClose: true
};

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

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

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

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

fs.exists(path, callback)

• path <строка> | <Буфер> | <URL>
• callback <Функция>
  • exists <логическое значение>

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

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)

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

Синхронная версия fs.exists(). Возвращает true если путь существует, false в противном случае.

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

fs.fchmod(fd, mode, callback)

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

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

fs.fchmodSync(fd, mode)

• fd <integer>
• mode <integer>

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

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

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

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

fs.fchownSync(fd, uid, gid)

• fd <integer>
• uid <integer>
• gid <integer>

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

fs.fdatasync(fd, callback)

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

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

fs.fdatasyncSync(fd)

• fd <integer>

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

fs.fstat(fd, callback)

• fd <integer>
• callback <Функция>
  • err <Ошибка>
  • stats <fs.Stats>

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

fs.fstatSync(fd)

• fd <integer>

Синхронная fstat(2). Возвращает экземпляр fs.Stats.

fs.fsync(fd, callback)

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

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

fs.fsyncSync(fd)

• fd <integer>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.ftruncateSync(fd[, len])

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

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

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

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

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

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

fs.futimesSync(fd, atime, mtime)

• fd <целое>
• atime <целое>
• mtime <целое>

Синхронный аналог fs.futimes(). Возвращает undefined.

fs.lchmod(path, mode, callback)

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

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

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

fs.lchmodSync(path, mode)

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

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

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

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

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

fs.lchownSync(path, uid, gid)

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

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

fs.link(existingPath, newPath, callback)

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

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

fs.linkSync(existingPath, newPath)

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

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

fs.lstat(path, callback)

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

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

fs.lstatSync(path)

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

Синхронная функция lstat(2). Возвращает экземпляр fs.Stats.

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

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

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

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

fs.mkdirSync(path[, mode])

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

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

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

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

• 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, то строка 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`.
  // Note that 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])

• prefix <строка>
• options <строка> | <Объект>
  • encoding <строка> По умолчанию: 'utf8'

Синхронная версия fs.mkdtemp(). Возвращает путь к созданной папке.

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

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

• path <строка> | <Буфер> | <URL>
• flags <строка> | <число>
• mode <целое число> По умолчанию: 0o666 (для чтения и записи)
• callback <Функция>
  • err <Ошибка>
  • fd <целое число>

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

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

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

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

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

  Обратите внимание, что это не превращает fs.open() в синхронный блокирующий вызов. Если требуется синхронная работа, fs.openSync() следует использовать.

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

• 'wx' - Как 'w', но завершается ошибкой, если path существует.

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

• 'wx+' - Как 'w+', но завершается ошибкой, если path существует.

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

• 'ax' - Как 'a', но завершается ошибкой, если path существует.

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

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

• 'ax+' - Как 'a+', но завершается ошибкой, если path существует.

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

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

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

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

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

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

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

// 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, как документировано в Naming Files, Paths, and Namespaces. В NTFS, если имя файла содержит двоеточие, Node.js откроет поток файловой системы, как описано в этой странице MSDN.

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

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

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

Синхронная версия fs.open(). Возвращает целое число, представляющее дескриптор файла.

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.readdirSync(path[, options])

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

Синхронная функция readdir(3). Возвращает массив имён файлов, исключая '.' и '..'.

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

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

• path <строка> | <Буфер> | <URL> | <целое число> имя файла или дескриптор файла
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> По умолчанию: '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>
});

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

Примечание: Если дескриптор файла указан в качестве path, он не будет автоматически закрыт.

Примечание: fs.readFile() считывает весь файл в одном потоке. Для минимизации вариаций длительности задач в пуле потоков рекомендуется использовать разделяющие API fs.read() и fs.createReadStream() при чтении файлов в рамках обработки запросов клиента.

fs.readFileSync(path[, options])

• path <строка> | <Буфер> | <URL> | <целое число> имя файла или дескриптор файла
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: null
  • flag <строка> По умолчанию: 'r'

Синхронный вариант fs.readFile(). Возвращает содержимое path.

Если указан параметр 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>'); // => null, <data>

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

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

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

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

fs.readlinkSync(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'

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

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

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

• fd <целое>
• buffer <Buffer> | <Uint8Array>
• offset <целое>
• length <целое>
• position <целое>

Синхронный аналог fs.read(). Возвращает количество bytesRead.

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'
• callback <Функция>
  • err <Ошибка>
  • resolvedPath <string> | <Buffer>

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

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

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

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

fs.realpathSync(path[, options])

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> По умолчанию: 'utf8'

Синхронная функция realpath(3). Возвращает результирующий путь.

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

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

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

fs.rename(oldPath, newPath, callback)

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

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

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

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

fs.renameSync(oldPath, newPath)

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

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

fs.rmdir(path, callback)

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

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

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

fs.rmdirSync(path)

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

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

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

fs.stat(path, callback)

• path <строка> | <Буфер> | <URL>
• 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)

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

Синхронная функция stat(2). Возвращает экземпляр fs.Stats.

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

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

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

Вот пример ниже:

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

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

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

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

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

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

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

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

fs.truncateSync(path[, len])

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

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

fs.unlink(path, callback)

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

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

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

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

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

fs.unlinkSync(path)

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

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

fs.unwatchFile(filename[, listener])

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

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

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

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

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

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

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

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

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

fs.utimesSync(path, atime, mtime)

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

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

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

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> Указывает, следует ли процессу продолжать выполнение, пока файлы отслеживаются. По умолчанию: true.
  • recursive <boolean> Указывает, следует ли отслеживать все подкаталоги или только текущий каталог. Это применимо, когда указан каталог, и только на поддерживаемых платформах (см. Примечания). По умолчанию: false.
  • encoding <string> Указывает кодировку символов, которая должна использоваться для имени файла, переданного слушателю. По умолчанию: 'utf8'.
• listener <Function> | <undefined> По умолчанию: undefined
  • eventType <string>
  • filename <string> | <Buffer>

Отслеживает изменения в filename, где filename — это файл или каталог. Возвращаемый объект — fs.FSWatcher.

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

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

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

Также обратите внимание, что обработчик обратного вызова прикреплен к событию 'change', генерируемому fs.FSWatcher, но это не то же самое, что значение 'change' для eventType.

Примечания

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

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

Доступность

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

• В системах Linux используется inotify
• В системах BSD используется kqueue
• В macOS для файлов используется kqueue, а для каталогов — 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)

• filename <string> | <Buffer> | <URL>
• options <Object>
  • persistent <boolean> По умолчанию: true
  • interval <integer> По умолчанию: 5007
• listener <Function>
  • current <fs.Stats>
  • previous <fs.Stats>

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

Аргумент options может быть опущен. Если он передан, он должен быть объектом. Объект options может содержать boolean значение, названное 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.

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

Примечание: Когда операция fs.watchFile приводит к ошибке ENOENT, она вызовет обработчик обратного вызова один раз, со всеми полями, сброшенными до нуля (или, для дат, эпохи Unix). В Windows поля blksize и blocks будут undefined, вместо нуля. Если файл создается позже, обработчик обратного вызова будет вызван снова с последними объектами stat. Это изменение функциональности по сравнению с версией v0.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)

• fd <целое>
• buffer <Buffer> | <Uint8Array>
• offset <целое>
• length <целое>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffer <Buffer> | <Uint8Array>

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

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

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

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

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

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

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

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

• fd <целое>
• string <строка>
• position <целое>
• encoding <строка>
• callback <Функция>
  • err <Ошибка>
  • written <целое>
  • string <строка>

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

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

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

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

В отличие от записи buffer, вся строка должна быть записана. Подстрока не может быть указана. Это связано с тем, что смещение байта результирующих данных может не совпадать со смещением строки.

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

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

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

• file <строка> | <Buffer> | <URL> | <целое> имя файла или дескриптор файла
• data <строка> | <Buffer> | <Uint8Array>
• options <Объект> | <строка>
  • encoding <строка> | <null> По умолчанию: 'utf8'
  • mode <целое> По умолчанию: 0o666
  • flag <строка> По умолчанию: 'w'
• callback <Функция>
  • err <Ошибка>

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

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

Пример:

fs.writeFile('message.txt', 'Hello Node.js', (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.

Примечание: Если дескриптор файла указан как file, он не будет закрыт автоматически.

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

• file <string> | <Buffer> | <URL> | <целое число> имя файла или дескриптор файла
• data <string> | <Buffer> | <Uint8Array>
• options <Объект> | <string>
  • encoding <string> | <null> По умолчанию: 'utf8'
  • mode <целое число> По умолчанию: 0o666
  • flag <string> По умолчанию: 'w'

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

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

• fd <целое число>
• buffer <Буфер> | <Uint8Array>
• offset <целое число>
• length <целое число>
• position <целое число>

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

• fd <целое число>
• string <строка>
• position <целое число>
• encoding <строка>

Синхронные версии fs.write(). Возвращает количество записанных байтов.

Постоянные значения FS

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

Примечание: Не все константы будут доступны на всех операционных системах.

Постоянные значения доступа к файлам

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

Постоянные значения открытия файла

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

Постоянные значения типа файла

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

Постоянные значения режима файла

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