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

Ввод-вывод файлов предоставляется простыми оболочками стандартных функций 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:66
        throw err;
              ^
Error: EISDIR, read
    at rethrow (fs.js:61:21)
    at maybeCallback (fs.js:79:42)
    at Object.fs.readFile (fs.js:153:18)
    at bad (/path/to/script.js:2:17)
    at Object.<anonymous> (/path/to/script.js:5:1)
    <etc.>

Класс: fs.FSWatcher

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

Событие: 'change'

• event <Строка> Тип изменения в файловой системе
• filename <Строка> Имя изменённого файла (если применимо/доступно)

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

Событие: 'error'

• error <Ошибка>

Используется при возникновении ошибки.

watcher.close()

Прекратить наблюдение за изменениями в заданном fs.FSWatcher.

Класс: fs.ReadStream

ReadStream является Потоком для чтения.

Событие: 'open'

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

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

Событие: 'close'

Используется при закрытии дескриптора файла, связанного с ReadStream, с помощью метода fs.close().

readStream.path

Путь к файлу, из которого считывает поток.

Класс: 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) вернёт строку, очень похожую на эту:

{
  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'

Используется при закрытии дескриптора файла, связанного с WriteStream, с помощью метода fs.close().

writeStream.bytesWritten

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

writeStream.path

Путь к файлу, в который записывает поток.

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

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

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

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

fs.access('/etc/passwd', fs.R_OK | fs.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;
    } else {
      throw err;
    }
  }

  writeMyData(fd);
});

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

fs.access('myfile', (err) => {
  if (err) {
    if (err.code === "ENOENT") {
      console.error('myfile does not exist');
      return;
    } else {
      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;
    } else {
      throw err;
    }
  }

  readMyData(fd);
});

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

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

fs.accessSync(path[, mode])

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

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

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

Асинхронно добавляет данные в файл, создавая файл, если он еще не существует. 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);

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

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

fs.chmod(path, mode, callback)

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

fs.chmodSync(path, mode)

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

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

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

fs.chownSync(path, uid, gid)

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

fs.close(fd, callback)

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

fs.closeSync(fd)

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

fs.createReadStream(path[, options])

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

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

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

{
  flags: 'r',
  encoding: null,
  fd: null,
  mode: 0o666,
  autoClose: true
}

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 устанавливает режим файла (разрешения и биты «привязки»), но только если файл был создан.

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

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

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

fs.createWriteStream(path[, options])

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

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

{
  flags: 'w',
  defaultEncoding: 'utf8',
  fd: null,
  mode: 0o666
}

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

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

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

fs.exists(path, callback)

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

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

Использование 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;
    } else {
      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;
    } else {
      throw err;
    }
  } else {
    readMyData(fd);
  }
});

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

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

fs.existsSync(path)

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

fs.fchmod(fd, mode, callback)

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

fs.fchmodSync(fd, mode)

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

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

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

fs.fchownSync(fd, uid, gid)

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

fs.fdatasync(fd, callback)

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

fs.fdatasyncSync(fd)

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

fs.fstat(fd, callback)

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

fs.fstatSync(fd)

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

fs.fsync(fd, callback)

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

fs.fsyncSync(fd)

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

fs.ftruncate(fd, len, callback)

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

fs.ftruncateSync(fd, len)

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

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

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

fs.futimesSync(fd, atime, mtime)

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

fs.lchmod(path, mode, callback)

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

Доступно только в Mac OS X.

fs.lchmodSync(path, mode)

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

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

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

fs.lchownSync(path, uid, gid)

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

fs.link(srcpath, dstpath, callback)

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

fs.linkSync(srcpath, dstpath)

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

fs.lstat(path, callback)

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

fs.lstatSync(path)

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

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

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

fs.mkdirSync(path[, mode])

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

fs.mkdtemp(prefix, callback)

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

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

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

Пример:

fs.mkdtemp('/tmp/foo-', (err, folder) => {
  console.log(folder);
    // Prints: /tmp/foo-itXde2
});

fs.mkdtempSync(template)

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

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

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

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

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

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

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

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

• 'rs+' - Открытие файла для чтения и записи, сообщая ОС открыть его синхронно. Смотрите примечания к 'rs' о том, как использовать это со вниманием.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fs.readdir(path, callback)

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

fs.readdirSync(path)

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

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

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

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

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

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

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

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

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

fs.readFileSync(file[, options])

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

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

fs.readlink(path, callback)

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

fs.readlinkSync(path)

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

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

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

Пример:

var cache = {'/etc':'/private/etc'};
fs.realpath('/etc/passwd', cache, (err, resolvedPath) => {
  if (err) throw err;
  console.log(resolvedPath);
});

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

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

fs.realpathSync(path[, cache])

Синхронный realpath(2). Возвращает разрешённый путь. cache — объект сопоставленных путей, который можно использовать для принудительного разрешения пути или избежания дополнительных fs.stat вызовов для известных реальных путей.

fs.rename(oldPath, newPath, callback)

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

fs.renameSync(oldPath, newPath)

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

fs.rmdir(path, callback)

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

fs.rmdirSync(path)

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

fs.stat(path, callback)

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

fs.statSync(path)

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

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

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

Вот пример:

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

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

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

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

fs.truncate(path, len, callback)

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

fs.truncateSync(path, len)

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

fs.unlink(path, callback)

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

fs.unlinkSync(path)

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

fs.unwatchFile(filename[, listener])

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

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

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

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

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

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

• Если значение — строка, преобразуемая в число, например, '123456789', она преобразуется в соответствующее число.
• Если значение — NaN или Infinity, оно преобразуется в Date.now().

fs.utimesSync(path, atime, mtime)

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

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

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

Второй аргумент необязателен. Если он задан, options должен быть объектом. Поддерживаемые булевы члены — persistent и recursive. persistent указывает, должен ли процесс продолжаться, пока файлы отслеживаются. recursive указывает, следует ли следить за всеми подкаталогами или только за текущим каталогом. Это относится к каталогу, и только на поддерживаемых платформах (см. Примечание).

Значение по умолчанию — { persistent: true, recursive: false }.

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

Ограничения

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

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

Доступность

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

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

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

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

Иноды

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

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

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

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

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

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

Аргумент options можно опустить. Если он указан, то он должен быть объектом. Объект options может содержать булево значение, названное persistent, которое указывает, нужно ли процессу продолжать работу, пока файлы отслеживаются. Объект options может содержать свойство interval, указывающее, как часто нужно опрашивать целевой объект в миллисекундах. По умолчанию значение равно { 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. Это изменение функциональности с версии 0.10.

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

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

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

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

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

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

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

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

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

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

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 <Функция>

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

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

Пример:

fs.writeFile('message.txt', 'Hello Node.js', (err) => {
  if (err) throw err;
  console.log('It\'s saved!');
});

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

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

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

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

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

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

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

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