Namespace node.fs

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 take 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. Here is an example of the asynchronous version:

    var fs = require('fs');

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

Here is the synchronous version:

    var 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', function (err) {
      if (err) throw err;
      console.log('renamed complete');
    });
    fs.stat('/tmp/world', function (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', function (err) {
      if (err) throw err;
      fs.stat('/tmp/world', function (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.

Defined in: node.fs.js

Method Summary

Method Attributes	Method Name and Description
static	node.fs.chmod(path, mode, callback) Asynchronous chmod(2).
static	node.fs.chmodSync(path, mode) Synchronous chmod(2).
static	node.fs.chown(path, uid, gid, callback)
static	node.fs.chownSync(path, uid, gid)
static	node.fs.close(fd, callback) Asynchronous close(2).
static	node.fs.closeSync(fd) Synchronous close(2).
static	node.fs.createReadStream(path, options)
static	node.fs.createWriteStream(path, options)
static	node.fs.fdatasync(fd, callback)
static	node.fs.fdatasyncSync(fd)
static	node.fs.fstat(fd, callback) Asynchronous fstat(2).
static	node.fs.fstatSync(fd) Synchronous fstat(2).
static	node.fs.fsync(fd, callback)
static	node.fs.fsyncSync(fd)
static	node.fs.futimes(fd, atime, mtime, callback)
static	node.fs.futimesSync(fd, atime, mtime) Change file timestamps with the difference that if filename refers to a symbolic link, then the link is not dereferenced.
static	node.fs.link(srcpath, dstpath, callback) Asynchronous link(2).
static	node.fs.linkSync(srcpath, dstpath) Synchronous link(2).
static	node.fs.lstat(path, callback) Asynchronous lstat(2).
static	node.fs.lstatSync(path) Synchronous lstat(2).
static	node.fs.mkdir(path, mode, callback) Asynchronous mkdir(2).
static	node.fs.mkdirSync(path, mode) Synchronous mkdir(2).
static	node.fs.open(path, flags, mode, callback) Asynchronous file open.
static	node.fs.openSync(path, flags, mode) Synchronous open(2).
static	node.fs.read(fd, buffer, offset, length, position, callback) Read data from the file specified by `fd`.
static	node.fs.readdir(path, callback) Asynchronous readdir(3).
static	node.fs.readdirSync(path) Synchronous readdir(3).
static	node.fs.readFile(path, encoding_) Asynchronously reads the entire contents of a file.
static	node.fs.readFileSync(path, encoding) Synchronous version of `fs.readFile`.
static	node.fs.readlink(path, callback) Asynchronous readlink(2).
static	node.fs.readlinkSync(path) Synchronous readlink(2).
static	node.fs.readSync(fd, buffer, offset, length, position) Synchronous version of string-based `fs.read`.
static	node.fs.realpath(p, cache, cb) Asynchronous realpath(2).
static	node.fs.realpathSync(p, cache) Synchronous realpath(2).
static	node.fs.rename(oldPath, newPath, callback) Asynchronous rename(2).
static	node.fs.renameSync(oldPath, newPath) Synchronous rename(2).
static	node.fs.rmdir(path, callback) Asynchronous rmdir(2).
static	node.fs.rmdirSync(path) Synchronous rmdir(2).
static	node.fs.sendfile(outFd, inFd, inOffset, length, callback)
static	node.fs.sendfileSync(outFd, inFd, inOffset, length)
static	node.fs.stat(path, callback) Asynchronous stat(2).
static	node.fs.statSync(path) Synchronous stat(2).
static	node.fs.symlink(destination, path, callback) Asynchronous symlink(2).
static	node.fs.symlinkSync(destination, path) Synchronous symlink(2).
static	node.fs.truncate(fd, len, callback) Asynchronous ftruncate(2).
static	node.fs.truncateSync(fd, len) Synchronous ftruncate(2).
static	node.fs.unlink(path, callback) Asynchronous unlink(2).
static	node.fs.unlinkSync(path) Synchronous unlink(2).
static	node.fs.unwatchFile(filename) Stop watching for changes on `filename`.
static	node.fs.utimes(path, atime, mtime, callback)
static	node.fs.utimesSync(path, atime, mtime) Change file timestamps.
static	node.fs.watchFile(filename) Watch for changes on `filename`.
static	node.fs.write(fd, buffer, offset, length, position, callback) Write `buffer` to the file specified by `fd`.
static	node.fs.writeFile(path, data, encoding_, callback) Asynchronously writes data to a file.
static	node.fs.writeFileSync(path, data, encoding) The synchronous version of `fs.writeFile`.
static	node.fs.writeSync(fd, buffer, offset, length, position) Synchronous version of string-based `fs.write()`.

Method Detail

static node.fs.chmod(path, mode, callback)

Asynchronous chmod(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} path

The path to change mode on

{string=} mode

mode defaults to 0666

{function(Error=)=} callback

The callback gets one argument (err). Which is undefined if no error occurred.
static node.fs.chmodSync(path, mode)

Synchronous chmod(2).

Parameters:

{string} path

The path to change mode on

{string} mode

mode defaults to 0666
static node.fs.chown(path, uid, gid, callback)

Parameters:

{string} path

The path to change owners on

{string} uid

The user id

{string} gid

The group id

{function(Error=)} callback

The callback gets one argument (err). Which is undefined if no error occurred.
static node.fs.chownSync(path, uid, gid)

Parameters:

{string} path

{string} uid

{string} gid
static node.fs.close(fd, callback)

Asynchronous close(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} fd

{function(Error=)} callback

The callback gets one argument (err). Which is undefined if no error occurred.
static node.fs.closeSync(fd)

Synchronous close(2).

Parameters:

{string} fd
static {node.fs.ReadStream} node.fs.createReadStream(path, options)

Parameters:

{string} path

{{flags:string|encoding:string|mode:string|bufferSize:number}=} options

Returns:

{node.fs.ReadStream}
static {node.fs.WriteStream} node.fs.createWriteStream(path, options)

Parameters:

{string} path

{{flags:string|encoding:string|mode:string|bufferSize:number}=} options

Returns:

{node.fs.WriteStream}
static node.fs.fdatasync(fd, callback)

Parameters:

{string} fd

{function(Error?|...[*]):undefined=} callback
static node.fs.fdatasyncSync(fd)

Parameters:

{string} fd
static node.fs.fstat(fd, callback)

Asynchronous fstat(2). The callback gets two arguments (err, stats) where stats is a fs.Stats object.

Parameters:

{string} fd

{function(Error?|node.fs.Stats)=} callback
static {node.fs.Stats} node.fs.fstatSync(fd)

Synchronous fstat(2). Returns an instance of fs.Stats.

Parameters:

{string} fd

Returns:

{node.fs.Stats}
static node.fs.fsync(fd, callback)

Parameters:

{string} fd

{function(Error?|...[*]):undefined=} callback
static node.fs.fsyncSync(fd)

Parameters:

{string} fd
static node.fs.futimes(fd, atime, mtime, callback)

Parameters:

{string} fd

{string} atime

{string} mtime

{function(Error?|...[*]):undefined=} callback
static node.fs.futimesSync(fd, atime, mtime)

Change file timestamps with the difference that if filename refers to a symbolic link, then the link is not dereferenced.

Parameters:

{string} fd

{string} atime

{string} mtime
static node.fs.link(srcpath, dstpath, callback)

Asynchronous link(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} srcpath

{string} dstpath

{function(Error?|...[*]):undefined=} callback
static node.fs.linkSync(srcpath, dstpath)

Synchronous link(2).

Parameters:

{string} srcpath

{string} dstpath
static node.fs.lstat(path, callback)

Asynchronous lstat(2). The callback gets two arguments (err, stats) where stats is a fs.Stats object. lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

Parameters:

{string} path

{function(Error?|...[*]):undefined=} callback
static node.fs.lstatSync(path)

Synchronous lstat(2). Returns an instance of fs.Stats.

Parameters:

{string} path
static node.fs.mkdir(path, mode, callback)

Asynchronous mkdir(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} path

{string} mode

{function(Error?|...[*]):undefined=} callback
static node.fs.mkdirSync(path, mode)

Synchronous mkdir(2).

Parameters:

{string} path

{string} mode
static node.fs.open(path, flags, mode, callback)

Asynchronous file open. See open(2). Flags can be 'r', 'r+', 'w', 'w+', 'a', or 'a+'. mode defaults to 0666. The callback gets two arguments (err, fd).

Parameters:

{string} path

{string} flags

{string} mode

{function(Error?|...[*]):undefined=} callback
static node.fs.openSync(path, flags, mode)

Synchronous open(2).

Parameters:

{string} path

{string} flags

{string} mode
static node.fs.read(fd, buffer, offset, length, position, callback)

Read data from the file specified by fd. buffer is the buffer that the data will be written to. offset is offset within the buffer where writing will start. length is an integer specifying the number of bytes to read. position is an integer specifying where to begin reading from in the file. If position is null, data will be read from the current file position. The callback is given the two arguments, (err, bytesRead).

Parameters:

{string} fd

{node.buffer.Buffer} buffer

{number} offset

{number} length

{number} position

{function(Error?|...[*]):undefined=} callback
static node.fs.readdir(path, callback)

Asynchronous readdir(3). Reads the contents of a directory. The callback gets two arguments (err, files) where files is an array of the names of the files in the directory excluding '.' and '..'.

Parameters:

{string} path

{function(Error?|...[*]):undefined=} callback
static node.fs.readdirSync(path)

Synchronous readdir(3). Returns an array of filenames excluding '.' and '..'.

Parameters:

{string} path
static node.fs.readFile(path, encoding_)
Asynchronously reads the entire contents of a file. Example:
```
    fs.readFile('/etc/passwd', function (err, data) {
      if (err) throw err;
      console.log(data);
    });
```
The callback is passed two arguments (err, data), where data is the contents of the file. If no encoding is specified, then the raw buffer is returned.
Parameters:

{string} path

{string} encoding_
static node.fs.readFileSync(path, encoding)

Synchronous version of fs.readFile. Returns the contents of the filename. If encoding is specified then this function returns a string. Otherwise it returns a buffer.

Parameters:

{string} path

{string=} encoding
static node.fs.readlink(path, callback)

Asynchronous readlink(2). The callback gets two arguments (err, resolvedPath).

Parameters:

{string} path

{function(Error?|...[*]):undefined=} callback
static node.fs.readlinkSync(path)

Synchronous readlink(2). Returns the resolved path.

Parameters:

{string} path
static node.fs.readSync(fd, buffer, offset, length, position)

Synchronous version of string-based fs.read. Returns the number of bytesRead.

Parameters:

{string} fd

{node.buffer.Buffer} buffer

{number} offset

{number} length

{number} position
static node.fs.realpath(p, cache, cb)

Asynchronous realpath(2). The callback gets two arguments (err, resolvedPath).

Parameters:

{string} p

{string=} cache

{function(Error?|...[*]):undefined=} cb
static node.fs.realpathSync(p, cache)

Synchronous realpath(2). Returns the resolved path.

Parameters:

{string} p

{string=} cache
static node.fs.rename(oldPath, newPath, callback)

Asynchronous rename(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} oldPath

{string} newPath

{function(Error?|...[*]):undefined=} callback
static node.fs.renameSync(oldPath, newPath)

Synchronous rename(2).

Parameters:

{string} oldPath

{string} newPath
static node.fs.rmdir(path, callback)

Asynchronous rmdir(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} path

{function(Error?|...[*]):undefined=} callback
static node.fs.rmdirSync(path)

Synchronous rmdir(2).

Parameters:

{string} path
static node.fs.sendfile(outFd, inFd, inOffset, length, callback)

Parameters:

{string} outFd

{string} inFd

{number} inOffset

{number} length

{function(Error?|...[*]):undefined=} callback
static node.fs.sendfileSync(outFd, inFd, inOffset, length)

Parameters:

{string} outFd

{string} inFd

{number} inOffset

{number} length

static node.fs.stat(path, callback)

Asynchronous stat(2). The callback gets two arguments (err, stats) where stats is a fs.Stats object. It looks like this:

    { dev: 2049,
      ino: 305352,
      mode: 16877,
      nlink: 12,
      uid: 1000,
      gid: 1000,
      rdev: 0,
      size: 4096,
      blksize: 4096,
      blocks: 8,
      atime: '2009-06-29T11:11:55Z',
      mtime: '2009-06-29T11:11:40Z',
      ctime: '2009-06-29T11:11:40Z' }

See the fs.Stats section below for more information.

Parameters:
{string} path
{function(Error?|...[*]):undefined=} callback

static node.fs.statSync(path)

Synchronous stat(2). Returns an instance of fs.Stats.

Parameters:

{string} path
static node.fs.symlink(destination, path, callback)

Asynchronous symlink(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} destination

{string} path

{function(Error?|...[*]):undefined=} callback
static node.fs.symlinkSync(destination, path)

Synchronous symlink(2).

Parameters:

{string} destination

{string} path
static node.fs.truncate(fd, len, callback)

Asynchronous ftruncate(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} fd

{string} len

{function(Error?|...[*]):undefined=} callback
static node.fs.truncateSync(fd, len)

Synchronous ftruncate(2).

Parameters:

{string} fd

{string} len
static node.fs.unlink(path, callback)

Asynchronous unlink(2). No arguments other than a possible exception are given to the completion callback.

Parameters:

{string} path

{function(Error?|...[*]):undefined=} callback
static node.fs.unlinkSync(path)

Synchronous unlink(2).

Parameters:

{string} path
static node.fs.unwatchFile(filename)

Stop watching for changes on filename.

Parameters:

{string} filename
static node.fs.utimes(path, atime, mtime, callback)

Parameters:

{string} path

{string} atime

{string} mtime

{function(Error?|...[*]):undefined=} callback
static node.fs.utimesSync(path, atime, mtime)

Change file timestamps.

Parameters:

{string} path

{string} atime

{string} mtime
static node.fs.watchFile(filename)
Watch for changes on filename. The callback listener will be called each time the file is accessed. The second argument is optional. The options if provided should be an object containing two members a boolean, persistent, and interval, a polling value in milliseconds. The default is { persistent: true, interval: 0 }. The listener gets two arguments the current stat object and the previous stat object:
```
    fs.watchFile(f, function (curr, prev) {
      console.log('the current mtime is: ' + curr.mtime);
      console.log('the previous mtime was: ' + prev.mtime);
    });
```
These stat objects are instances of fs.Stat. If you want to be notified when the file was modified, not just accessed you need to compare curr.mtime and `prev.mtime.
Parameters:

{string} filename
static node.fs.write(fd, buffer, offset, length, position, callback)

Write buffer to the file specified by fd. offset and length determine the part of the buffer to be written. position refers to the offset from the beginning of the file where this data should be written. If position is null, the data will be written at the current position. See pwrite(2). The callback will be given two arguments (err, written) where written specifies how many bytes were written.

Parameters:

{string} fd

{node.buffer.Buffer} buffer

{number} offset

{number} length

{number} position

{function(Error?|...[*]):undefined=} callback
static node.fs.writeFile(path, data, encoding_, callback)
Asynchronously writes data to a file. data can be a string or a buffer. Example:
```
    fs.writeFile('message.txt', 'Hello Node', function (err) {
      if (err) throw err;
      console.log('It\'s saved!');
    });
```
Parameters:

{string} path

{string} data

{string} encoding_

{function(Error?|...[*]):undefined=} callback
static node.fs.writeFileSync(path, data, encoding)

The synchronous version of fs.writeFile.

Parameters:

{string} path

{string} data

{string=} encoding
static node.fs.writeSync(fd, buffer, offset, length, position)

Synchronous version of string-based fs.write(). Returns the number of bytes written.

Parameters:

{string} fd

{node.buffer.Buffer} buffer

{number} offset

{number} length

{number} position

Classes

Namespace node.fs

Method Summary

Method Detail