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

Ввод-вывод файлов реализован с помощью простых обёртки над стандартными функциями 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:

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

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 — это Поток чтения.

Событие: 'open'

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

Срабатывает при открытии файла потоком чтения.

Событие: 'close'

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

Срабатывает, когда 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,
  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 }

Обратите внимание, что atime, mtime, birthtime, и ctime являются экземплярами объекта Date, и для сравнения значений этих объектов нужно использовать соответствующие методы. Для большинства общих случаев getTime() вернёт количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 UTC, и этого целого числа достаточно для любого сравнения, однако существуют дополнительные методы, которые могут использоваться для отображения неопределённой информации. Более подробную информацию можно найти на странице справочника JavaScript MDN.

Значения времени в объекте 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 — это Поток записи.

Событие: 'open'

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

Срабатывает при открытии файла потоком записи.

Событие: 'close'

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

Срабатывает, когда WriteStream закрыт.

writeStream.bytesWritten

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

writeStream.path

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

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

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

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

• 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, — это функция обратного вызова, которая вызывается с возможным аргументом ошибки. Если любая из проверок доступа завершается неудачно, аргумент ошибки будет заполнен. Следующий пример проверяет, может ли файл /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);
});

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

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

fs.accessSync(path[, mode])

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

Синхронная версия fs.access(). Выбрасывает ошибку, если какие-либо проверки доступа завершаются неудачно, и ничего не делает в противном случае.

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

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

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

Пример:

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.appendFileSync(file, data[, options])

• file <строка> | <Буфер> | <число> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <null> значение по умолчанию = 'utf8'
  • mode <целое> значение по умолчанию = 0o666
  • flag <строка> значение по умолчанию = 'a'

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

fs.chmod(path, mode, callback)

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

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

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

fs.chmodSync(path, mode)

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

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

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

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

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

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

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

fs.chownSync(path, uid, gid)

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

fs.createReadStream(path[, options])

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

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

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

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

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

fs.createWriteStream(path[, options])

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

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

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

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

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

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

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

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

fs.exists(path, callback)

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

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

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

fs.fchmod(fd, mode, callback)

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

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

fs.fchmodSync(fd, mode)

• fd <целое>
• mode <целое>

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

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

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

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

fs.fchownSync(fd, uid, gid)

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

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

fs.fdatasync(fd, callback)

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

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

fs.fdatasyncSync(fd)

• fd <целое>

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

fs.fstat(fd, callback)

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

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

fs.fstatSync(fd)

• fd <целое>

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

fs.fsync(fd, callback)

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

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

fs.fsyncSync(fd)

• fd <целое>

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

fs.ftruncate(fd, len, callback)

• fd <целое>
• len <целое> default = 0
• callback <Функция>
  • err <Ошибка>

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

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

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

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

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

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

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

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

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

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

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

fs.ftruncateSync(fd, len)

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

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

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

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

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

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

fs.futimesSync(fd, atime, mtime)

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

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

fs.lchmod(path, mode, callback)

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

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

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

fs.lchmodSync(path, mode)

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

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

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

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

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

fs.lchownSync(path, uid, gid)

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

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

fs.link(existingPath, newPath, callback)

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

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

fs.linkSync(existingPath, newPath)

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

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

fs.lstat(path, callback)

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

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

fs.lstatSync(path)

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

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

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

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

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

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

fs.mkdirSync(path[, mode])

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

Синхронно создаёт директорию. Возвращает 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 <строка> | <Буфер>
• flags <строка> | <число>
• mode <целое число>
• 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 существует.

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

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

mode устанавливает режим файла (разрешения и биты сохранения), но только если файл был создан. По умолчанию он равен 0o666 (доступен для чтения и записи).

Коллбэк получает два аргумента (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, как описано в Имена файлов, пути и имена. В NTFS, если имя файла содержит двоеточие, Node.js откроет поток файловой системы, как описано в этой странице MSDN.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.readdirSync(path[, options])

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

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

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

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

• file <строка> | <Буфер> | <целое> имя файла или дескриптор файла
• 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.readFileSync(file[, options])

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

Синхронная версия fs.readFile. Возвращает содержимое файла file.

Если указан параметр 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 <строка> | <Buffer>
• options <строка> | <Объект>
  • encoding <строка> значение по умолчанию = 'utf8'
• callback <Функция>
  • err <Ошибка>
  • linkString <строка> | <Buffer>

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

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

fs.readlinkSync(path[, options])

• path <строка> | <Buffer>
• options <строка> | <Объект>
  • encoding <строка> значение по умолчанию = 'utf8'

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

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

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

• fd <целое>
• buffer <строка> | <Buffer>
• offset <целое>
• length <целое>
• position <целое>

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

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

• path <строка> | <Buffer>
• options <строка> | <Объект>
  • encoding <строка> значение по умолчанию = 'utf8'
• callback <Функция>
  • err <Ошибка>
  • resolvedPath <строка> | <Buffer>

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

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

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

fs.realpathSync(path[, options])

• path <строка> | <Buffer>;
• options <строка> | <Объект>
  • encoding <строка> значение по умолчанию = 'utf8'

Синхронная realpath(3). Возвращает разрешенный путь.

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

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

fs.rename(oldPath, newPath, callback)

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

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

fs.renameSync(oldPath, newPath)

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

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

fs.rmdir(path, callback)

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

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

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

fs.rmdirSync(path)

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

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

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

fs.stat(path, callback)

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

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

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

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

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

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

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

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

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

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

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

fs.truncate(path, len, callback)

• path <строка> | <Buffer>
• len <целое> по умолчанию = 0
• callback <Функция>
  • err <Ошибка>

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

fs.truncateSync(path, len)

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

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

fs.unlink(path, callback)

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

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

fs.unlinkSync(path)

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

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

fs.unwatchFile(filename[, listener])

• filename <строка> | <Buffer>
• listener <Функция>
  • eventType <строка>
  • filename <строка> | <Buffer>

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

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

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

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

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

Изменение временных меток файла, на который ссылается указанный путь.

Примечание: аргументы atime и mtime следующих связанных функций следуют этим правилам:

• Значение должно быть unix-временем в секундах. Например, Date.now() возвращает миллисекунды, поэтому его нужно разделить на 1000 перед передачей.
• Если значение является строковым числом, например, '123456789', значение будет преобразовано в соответствующее число.
• Если значение равно NaN или Infinity, значение будет преобразовано в Date.now() / 1000.

fs.utimesSync(path, atime, mtime)

• path <строка> | <Buffer>
• atime <целое>
• mtime <целое>

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

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

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

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

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

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

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

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

Примечания

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

Рекурсивный параметр поддерживается только на 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() разрешает путь к иноду inode и отслеживает инод. Если отслеживаемый путь удален и пересоздан, ему присваивается новый инод. При удалении watch будет вызывать событие, но продолжит отслеживать исходный inode. События для нового инода не будут вызваны. Это ожидаемое поведение.

В AIX сохранение и закрытие наблюдаемого файла вызывает две уведомления: одно для добавления нового содержимого и одно для усечения. Кроме того, операции сохранения и закрытия на некоторых платформах вызывают изменения инодов, которые делают операции watch недействительными и неэффективными. AIX сохраняет inode в течение всего срока службы файла, и таким образом, хотя это отличается от Linux / OS X, это улучшает удобство использования отслеживания файлов. Это ожидаемое поведение.

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

Предоставление filename аргумента в обратном вызове поддерживается только в Linux и Windows. Даже на поддерживаемых платформах 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 <строка> | <Buffer>
• options <Объект>
  • persistent <логическое>
  • interval <целое>
• listener <Функция>
  • current <fs.Stats>
  • previous <fs.Stats>

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

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

Обратный вызов 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 Epoch). В 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 <Буфер>
• offset <целое>
• length <целое>
• position <целое>
• callback <Функция>
  • err <Ошибка>
  • bytesWritten <целое>
  • buffer <Буфер> | <Uint8Массив>

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

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

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

Обратный вызов получит три аргумента (err, written, buffer) , где written указывает количество записанных байтов из 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 <строка> | <Буфер> | <целое> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <Null> по умолчанию = 'utf8'
  • mode <целое> по умолчанию = 0o666
  • flag <строка> по умолчанию = 'w'
• callback <Функция>
  • err <Ошибка>

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

Опция encoding игнорируется, если data является буфером. По умолчанию 'utf8'.

Пример:

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 <строка> | <Буфер> | <целое> имя файла или дескриптор файла
• data <строка> | <Буфер>
• options <Объект> | <строка>
  • encoding <строка> | <Null> по умолчанию = 'utf8'
  • mode <целое> по умолчанию = 0o666
  • flag <строка> по умолчанию = 'w'

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

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

• fd <целое>
• buffer <Буфер>
• offset <целое>
• length <целое>
• position <целое>

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

• fd <integer>
• string <string>
• position <integer>
• encoding <string>

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

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

Следующие константы экспортируются fs.constants. Примечание: Не все константы будут доступны на всех операционных системах.

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

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

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

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

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

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

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

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