Table of Contents

• File System
  • Buffer API
  • Class: fs.FSWatcher
    • Event: 'change'
    • Event: 'error'
    • watcher.close()
  • Class: fs.ReadStream
    • Event: 'close'
    • Event: 'open'
    • readStream.bytesRead
    • readStream.path
  • Class: fs.Stats
    • Stat Time Values
  • Class: fs.WriteStream
    • Event: 'close'
    • Event: 'open'
    • writeStream.bytesWritten
    • writeStream.path
  • fs.access(path[, mode], callback)
  • fs.accessSync(path[, mode])
  • fs.appendFile(file, data[, options], callback)
  • fs.appendFileSync(file, data[, options])
  • fs.chmod(path, mode, callback)
  • fs.chmodSync(path, mode)
  • fs.chown(path, uid, gid, callback)
  • fs.chownSync(path, uid, gid)
  • fs.close(fd, callback)
  • fs.closeSync(fd)
  • fs.constants
  • fs.createReadStream(path[, options])
  • fs.createWriteStream(path[, options])
  • fs.exists(path, callback)
  • fs.existsSync(path)
  • fs.fchmod(fd, mode, callback)
  • fs.fchmodSync(fd, mode)
  • fs.fchown(fd, uid, gid, callback)
  • fs.fchownSync(fd, uid, gid)
  • fs.fdatasync(fd, callback)
  • fs.fdatasyncSync(fd)
  • fs.fstat(fd, callback)
  • fs.fstatSync(fd)
  • fs.fsync(fd, callback)
  • fs.fsyncSync(fd)
  • fs.ftruncate(fd, len, callback)
  • fs.ftruncateSync(fd, len)
  • fs.futimes(fd, atime, mtime, callback)
  • fs.futimesSync(fd, atime, mtime)
  • fs.lchmod(path, mode, callback)
  • fs.lchmodSync(path, mode)
  • fs.lchown(path, uid, gid, callback)
  • fs.lchownSync(path, uid, gid)
  • fs.link(existingPath, newPath, callback)
  • fs.linkSync(existingPath, newPath)
  • fs.lstat(path, callback)
  • fs.lstatSync(path)
  • fs.mkdir(path[, mode], callback)
  • fs.mkdirSync(path[, mode])
  • fs.mkdtemp(prefix[, options], callback)
  • fs.mkdtempSync(prefix[, options])
  • fs.open(path, flags[, mode], callback)
  • fs.openSync(path, flags[, mode])
  • fs.read(fd, buffer, offset, length, position, callback)
  • fs.readdir(path[, options], callback)
  • fs.readdirSync(path[, options])
  • fs.readFile(file[, options], callback)
  • fs.readFileSync(file[, options])
  • fs.readlink(path[, options], callback)
  • fs.readlinkSync(path[, options])
  • fs.readSync(fd, buffer, offset, length, position)
  • fs.realpath(path[, options], callback)
  • fs.realpathSync(path[, options])
  • fs.rename(oldPath, newPath, callback)
  • fs.renameSync(oldPath, newPath)
  • fs.rmdir(path, callback)
  • fs.rmdirSync(path)
  • fs.stat(path, callback)
  • fs.statSync(path)
  • fs.symlink(target, path[, type], callback)
  • fs.symlinkSync(target, path[, type])
  • fs.truncate(path, len, callback)
  • fs.truncateSync(path, len)
  • fs.unlink(path, callback)
  • fs.unlinkSync(path)
  • fs.unwatchFile(filename[, listener])
  • fs.utimes(path, atime, mtime, callback)
  • fs.utimesSync(path, atime, mtime)
  • fs.watch(filename[, options][, listener])
    • Caveats
      • Availability
      • Inodes
      • Filename Argument
  • fs.watchFile(filename[, options], listener)
  • fs.write(fd, buffer[, offset[, length[, position]]], callback)
  • fs.write(fd, string[, position[, encoding]], callback)
  • fs.writeFile(file, data[, options], callback)
  • fs.writeFileSync(file, data[, options])
  • fs.writeSync(fd, buffer[, offset[, length[, position]]])
  • fs.writeSync(fd, string[, position[, encoding]])
  • FS Constants
    • File Access Constants
    • File Open Constants
    • File Type Constants
    • File Mode Constants

File System#

Stability: 2 - Stable

File I/O is provided by simple wrappers around standard POSIX functions. To use this module do require('fs'). All the methods have asynchronous and synchronous forms.

The asynchronous form always takes a completion callback as its last argument. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation was completed successfully, then the first argument will be null or undefined.

When using the synchronous form any exceptions are immediately thrown. You can use try/catch to handle exceptions or allow them to bubble up.

Here is an example of the asynchronous version:

const fs = require('fs');

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

Here is the synchronous version:

const fs = require('fs');

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

With the asynchronous methods there is no guaranteed ordering. So the following is prone to error:

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

It could be that fs.stat is executed before fs.rename. The correct way to do this is to chain the callbacks.

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

In busy processes, the programmer is strongly encouraged to use the asynchronous versions of these calls. The synchronous versions will block the entire process until they complete--halting all connections.

The relative path to a filename can be used. Remember, however, that this path will be relative to process.cwd().

Most fs functions let you omit the callback argument. If you do, a default callback is used that rethrows errors. To get a trace to the original call site, set the NODE_DEBUG environment variable:

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

Buffer API#

fs functions support passing and receiving paths as both strings and Buffers. The latter is intended to make it possible to work with filesystems that allow for non-UTF-8 filenames. For most typical uses, working with paths as Buffers will be unnecessary, as the string API converts to and from UTF-8 automatically.

Note that on certain file systems (such as NTFS and HFS+) filenames will always be encoded as UTF-8. On such file systems, passing non-UTF-8 encoded Buffers to fs functions will not work as expected.

Class: fs.FSWatcher#

Objects returned from fs.watch() are of this type.

The listener callback provided to fs.watch() receives the returned FSWatcher's change events.

The object itself emits these events:

Event: 'change'#

• eventType <string> The type of fs change
• filename <string> | <Buffer> The filename that changed (if relevant/available)

Emitted when something changes in a watched directory or file. See more details in fs.watch().

The filename argument may not be provided depending on operating system support. If filename is provided, it will be provided as a Buffer if fs.watch() is called with its encoding option set to 'buffer', otherwise filename will be a string.

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

Event: 'error'#

• error <Error>

Emitted when an error occurs.

watcher.close()#

Stop watching for changes on the given fs.FSWatcher.

Class: fs.ReadStream#

ReadStream is a Readable Stream.

Event: 'close'#

Emitted when the ReadStream's underlying file descriptor has been closed using the fs.close() method.

Event: 'open'#

• fd <integer> Integer file descriptor used by the ReadStream.

Emitted when the ReadStream's file is opened.

readStream.bytesRead#

The number of bytes read so far.

readStream.path#

The path to the file the stream is reading from as specified in the first argument to fs.createReadStream(). If path is passed as a string, then readStream.path will be a string. If path is passed as a Buffer, then readStream.path will be a Buffer.

Class: fs.Stats#

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their synchronous counterparts are of this type.

• stats.isFile()
• stats.isDirectory()
• stats.isBlockDevice()
• stats.isCharacterDevice()
• stats.isSymbolicLink() (only valid with fs.lstat())
• stats.isFIFO()
• stats.isSocket()

For a regular file util.inspect(stats) would return a string very similar to this:

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 }

Please note that atime, mtime, birthtime, and ctime are instances of Date object and to compare the values of these objects you should use appropriate methods. For most general uses getTime() will return the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC and this integer should be sufficient for any comparison, however there are additional methods which can be used for displaying fuzzy information. More details can be found in the MDN JavaScript Reference page.

Stat Time Values#

The times in the stat object have the following semantics:

• atime "Access Time" - Time when file data last accessed. Changed by the mknod(2), utimes(2), and read(2) system calls.
• mtime "Modified Time" - Time when file data last modified. Changed by the mknod(2), utimes(2), and write(2) system calls.
• ctime "Change Time" - Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), and write(2) system calls.
• birthtime "Birth Time" - Time of file creation. Set once when the file is created. On filesystems where birthtime is not available, this field may instead hold either the ctime or 1970-01-01T00:00Z (ie, unix epoch timestamp 0). Note that this value may be greater than atime or mtime in this case. On Darwin and other FreeBSD variants, also set if the atime is explicitly set to an earlier value than the current birthtime using the utimes(2) system call.

Prior to Node v0.12, the ctime held the birthtime on Windows systems. Note that as of v0.12, ctime is not "creation time", and on Unix systems, it never was.

Class: fs.WriteStream#

WriteStream is a Writable Stream.

Event: 'close'#

Emitted when the WriteStream's underlying file descriptor has been closed using the fs.close() method.

Event: 'open'#

• fd <integer> Integer file descriptor used by the WriteStream.

Emitted when the WriteStream's file is opened.

writeStream.bytesWritten#

The number of bytes written so far. Does not include data that is still queued for writing.

writeStream.path#

The path to the file the stream is writing to as specified in the first argument to fs.createWriteStream(). If path is passed as a string, then writeStream.path will be a string. If path is passed as a Buffer, then writeStream.path will be a Buffer.

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

• path <string> | <Buffer>
• mode <integer>
• callback <Function>

Tests a user's permissions for the file or directory specified by path. The mode argument is an optional integer that specifies the accessibility checks to be performed. The following constants define the possible values of mode. It is possible to create a mask consisting of the bitwise OR of two or more values.

• fs.constants.F_OK - path is visible to the calling process. This is useful for determining if a file exists, but says nothing about rwx permissions. Default if no mode is specified.
• fs.constants.R_OK - path can be read by the calling process.
• fs.constants.W_OK - path can be written by the calling process.
• fs.constants.X_OK - path can be executed by the calling process. This has no effect on Windows (will behave like fs.constants.F_OK).

The final argument, callback, is a callback function that is invoked with a possible error argument. If any of the accessibility checks fail, the error argument will be populated. The following example checks if the file /etc/passwd can be read and written by the current process.

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

Using fs.access() to check for the accessibility of a file before calling fs.open(), fs.readFile() or fs.writeFile() is not recommended. Doing so introduces a race condition, since other processes may change the file's state between the two calls. Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible.

For example:

write (NOT RECOMMENDED)

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

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

write (RECOMMENDED)

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

    throw err;
  }

  writeMyData(fd);
});

read (NOT RECOMMENDED)

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

read (RECOMMENDED)

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

    throw err;
  }

  readMyData(fd);
});

The "not recommended" examples above check for accessibility and then use the file; the "recommended" examples are better because they use the file directly and handle the error, if any.

In general, check for the accessibility of a file only if the file won’t be used directly, for example when its accessibility is a signal from another process.

fs.accessSync(path[, mode])#

• path <string> | <Buffer>
• mode <integer>

Synchronous version of fs.access(). This throws if any accessibility checks fail, and does nothing otherwise.

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

• file <string> | <Buffer> | <number> filename or file descriptor
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> default = 'utf8'
  • mode <integer> default = 0o666
  • flag <string> default = 'a'