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
-
- Parameters:
- {string} path
- {{flags:string|encoding:string|mode:string|bufferSize:number}=} options
- Returns:
- {node.fs.ReadStream}
-
- 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)
wherestats
is afs.Stats
object.- Parameters:
- {string} fd
- {function(Error?|node.fs.Stats)=} callback
-
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)
wherestats
is afs.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. Ifposition
isnull
, 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)
wherefiles
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)
, wheredata
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 thefilename
. Ifencoding
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 ofbytesRead
.- 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)
wherestats
is afs.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 thefs.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 callbacklistener
will be called each time the file is accessed. The second argument is optional. Theoptions
if provided should be an object containing two members a boolean,persistent
, andinterval
, a polling value in milliseconds. The default is{ persistent: true, interval: 0 }
. Thelistener
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 offs.Stat
. If you want to be notified when the file was modified, not just accessed you need to comparecurr.mtime
and `prev.mtime.- Parameters:
- {string} filename
-
static node.fs.write(fd, buffer, offset, length, position, callback)Write
buffer
to the file specified byfd
.offset
andlength
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. Ifposition
isnull
, the data will be written at the current position. See pwrite(2). The callback will be given two arguments(err, written)
wherewritten
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