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.

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
  • 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
  • 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
  • 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
  • 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