Skip to content

Commit

Permalink
doc: sort fs alphabetically
Browse files Browse the repository at this point in the history 
Reorders, with no contextual changes, the fs documentation
alphabetically.

PR-URL: #3662
Reviewed-By: Evan Lucas <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
@tflanagan @rvagg
tflanagan authored and rvagg committed Nov 13, 2015
1 parent ce3ac8d commit c3f5ea7
Showing 1 changed file with 498 additions and 502 deletions.
1,000 changes: 498 additions & 502 deletions doc/api/fs.markdown
View file
Original file line number Diff line number Diff line change
@@ -84,218 +84,397 @@ site, set the NODE_DEBUG environment variable:
at Object.<anonymous> (/path/to/script.js:5:1)
<etc.>

## Class: fs.FSWatcher

## fs.rename(oldPath, newPath, callback)
Objects returned from `fs.watch()` are of this type.

Asynchronous rename(2). No arguments other than a possible exception are given
to the completion callback.
### Event: 'change'

## fs.renameSync(oldPath, newPath)
* `event` {String} The type of fs change
* `filename` {String} The filename that changed (if relevant/available)

Synchronous rename(2). Returns `undefined`.
Emitted when something changes in a watched directory or file.
See more details in [fs.watch](#fs_fs_watch_filename_options_listener).

## fs.ftruncate(fd, len, callback)
### Event: 'error'

Asynchronous ftruncate(2). No arguments other than a possible exception are
given to the completion callback.
* `error` {Error object}

## fs.ftruncateSync(fd, len)
Emitted when an error occurs.

Synchronous ftruncate(2). Returns `undefined`.
### watcher.close()

## fs.truncate(path, len, callback)
Stop watching for changes on the given `fs.FSWatcher`.

Asynchronous truncate(2). No arguments other than a possible exception are
given to the completion callback. A file descriptor can also be passed as the
first argument. In this case, `fs.ftruncate()` is called.
## Class: fs.ReadStream

## fs.truncateSync(path, len)
`ReadStream` is a [Readable Stream](stream.html#stream_class_stream_readable).

Synchronous truncate(2). Returns `undefined`.
### Event: 'open'

## fs.chown(path, uid, gid, callback)
* `fd` {Integer} file descriptor used by the ReadStream.

Asynchronous chown(2). No arguments other than a possible exception are given
to the completion callback.
Emitted when the ReadStream's file is opened.

## fs.chownSync(path, uid, gid)
## Class: fs.Stats

Synchronous chown(2). Returns `undefined`.
Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their
synchronous counterparts are of this type.

## fs.fchown(fd, uid, gid, callback)
- `stats.isFile()`
- `stats.isDirectory()`
- `stats.isBlockDevice()`
- `stats.isCharacterDevice()`
- `stats.isSymbolicLink()` (only valid with `fs.lstat()`)
- `stats.isFIFO()`
- `stats.isSocket()`

Asynchronous fchown(2). No arguments other than a possible exception are given
to the completion callback.
For a regular file `util.inspect(stats)` would return a string very
similar to this:

## fs.fchownSync(fd, uid, gid)
{ 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 }

Synchronous fchown(2). Returns `undefined`.
Please note that `atime`, `mtime`, `birthtime`, and `ctime` are
instances of [Date][MDN-Date] object and to compare the values of
these objects you should use appropriate methods. For most general
uses [getTime()][MDN-Date-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][MDN-Date]
page.

## fs.lchown(path, uid, gid, callback)
[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime

Asynchronous lchown(2). No arguments other than a possible exception are given
to the completion callback.
### Stat Time Values

## fs.lchownSync(path, uid, gid)
The times in the stat object have the following semantics:

Synchronous lchown(2). Returns `undefined`.
* `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`). 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.

## fs.chmod(path, mode, callback)
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.

Asynchronous chmod(2). No arguments other than a possible exception are given
to the completion callback.
## Class: fs.WriteStream

## fs.chmodSync(path, mode)
`WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable).

Synchronous chmod(2). Returns `undefined`.
### Event: 'open'

## fs.fchmod(fd, mode, callback)
* `fd` {Integer} file descriptor used by the WriteStream.

Asynchronous fchmod(2). No arguments other than a possible exception
are given to the completion callback.
Emitted when the WriteStream's file is opened.

## fs.fchmodSync(fd, mode)
### writeStream.bytesWritten

Synchronous fchmod(2). Returns `undefined`.
The number of bytes written so far. Does not include data that is still queued
for writing.

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

Asynchronous lchmod(2). No arguments other than a possible exception
are given to the completion callback.
Tests a user's permissions for the file specified by `path`. `mode` 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.

Only available on Mac OS X.
- `fs.F_OK` - File 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.R_OK` - File can be read by the calling process.
- `fs.W_OK` - File can be written by the calling process.
- `fs.X_OK` - File can be executed by the calling process. This has no effect
on Windows (will behave like `fs.F_OK`).

## fs.lchmodSync(path, mode)
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.

Synchronous lchmod(2). Returns `undefined`.
fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function (err) {
console.log(err ? 'no access!' : 'can read/write');
});

## fs.stat(path, callback)
## fs.accessSync(path[, mode])

Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
`stats` is a [fs.Stats](#fs_class_fs_stats) object. See the [fs.Stats](#fs_class_fs_stats)
section below for more information.
Synchronous version of `fs.access`. This throws if any accessibility checks
fail, and does nothing otherwise.

## fs.lstat(path, callback)
## fs.appendFile(file, data[, options], 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.
* `file` {String | Integer} filename or file descriptor
* `data` {String | Buffer}
* `options` {Object | String}
* `encoding` {String | Null} default = `'utf8'`
* `mode` {Number} default = `0o666`
* `flag` {String} default = `'a'`
* `callback` {Function}

## fs.fstat(fd, callback)
Asynchronously append data to a file, creating the file if it does not yet exist.
`data` can be a string or a buffer.

Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
`stats` is a `fs.Stats` object. `fstat()` is identical to `stat()`, except that
the file to be stat-ed is specified by the file descriptor `fd`.
Example:

## fs.statSync(path)
fs.appendFile('message.txt', 'data to append', function (err) {
if (err) throw err;
console.log('The "data to append" was appended to file!');
});

Synchronous stat(2). Returns an instance of `fs.Stats`.
If `options` is a string, then it specifies the encoding. Example:

## fs.lstatSync(path)
fs.appendFile('message.txt', 'data to append', 'utf8', callback);

Synchronous lstat(2). Returns an instance of `fs.Stats`.
Any specified file descriptor has to have been opened for appending.

## fs.fstatSync(fd)
_Note: Specified file descriptors will not be closed automatically._

Synchronous fstat(2). Returns an instance of `fs.Stats`.
## fs.appendFileSync(file, data[, options])

## fs.link(srcpath, dstpath, callback)
The synchronous version of `fs.appendFile`. Returns `undefined`.

Asynchronous link(2). No arguments other than a possible exception are given to
the completion callback.
## fs.chmod(path, mode, callback)

## fs.linkSync(srcpath, dstpath)
Asynchronous chmod(2). No arguments other than a possible exception are given
to the completion callback.

Synchronous link(2). Returns `undefined`.
## fs.chmodSync(path, mode)

## fs.symlink(destination, path[, type], callback)
Synchronous chmod(2). Returns `undefined`.

Asynchronous symlink(2). No arguments other than a possible exception are given
## fs.chown(path, uid, gid, callback)

Asynchronous chown(2). No arguments other than a possible exception are given
to the completion callback.
The `type` argument can be set to `'dir'`, `'file'`, or `'junction'` (default
is `'file'`) and is only available on Windows (ignored on other platforms).
Note that Windows junction points require the destination path to be absolute. When using
`'junction'`, the `destination` argument will automatically be normalized to absolute path.

## fs.symlinkSync(destination, path[, type])
## fs.chownSync(path, uid, gid)

Synchronous symlink(2). Returns `undefined`.
Synchronous chown(2). Returns `undefined`.

## fs.readlink(path, callback)
## fs.close(fd, callback)

Asynchronous readlink(2). The callback gets two arguments `(err,
linkString)`.
Asynchronous close(2). No arguments other than a possible exception are given
to the completion callback.

## fs.readlinkSync(path)
## fs.closeSync(fd)

Synchronous readlink(2). Returns the symbolic link's string value.
Synchronous close(2). Returns `undefined`.

## fs.realpath(path[, cache], callback)
## fs.createReadStream(path[, options])

Asynchronous realpath(2). The `callback` gets two arguments `(err,
resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an
object literal of mapped paths that can be used to force a specific path
resolution or avoid additional `fs.stat` calls for known real paths.
Returns a new ReadStream object (See `Readable Stream`).

Example:
Be aware that, unlike the default value set for `highWaterMark` on a
readable stream (16 kb), the stream returned by this method has a
default value of 64 kb for the same parameter.

var cache = {'/etc':'/private/etc'};
fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
if (err) throw err;
console.log(resolvedPath);
});
`options` is an object or string with the following defaults:

## fs.realpathSync(path[, cache])
{ flags: 'r',
encoding: null,
fd: null,
mode: 0o666,
autoClose: true
}

Synchronous realpath(2). Returns the resolved path.
`options` can include `start` and `end` values to read a range of bytes from
the file instead of the entire file. Both `start` and `end` are inclusive and
start at 0. The `encoding` can be any one of those accepted by [Buffer][].

## fs.unlink(path, callback)
If `fd` is specified, `ReadStream` will ignore the `path` argument and will use
the specified file descriptor. This means that no `open` event will be emitted.

Asynchronous unlink(2). No arguments other than a possible exception are given
to the completion callback.
If `autoClose` is false, then the file descriptor won't be closed, even if
there's an error. It is your responsibility to close it and make sure
there's no file descriptor leak. If `autoClose` is set to true (default
behavior), on `error` or `end` the file descriptor will be closed
automatically.

## fs.unlinkSync(path)
`mode` sets the file mode (permission and sticky bits), but only if the
file was created.

Synchronous unlink(2). Returns `undefined`.
An example to read the last 10 bytes of a file which is 100 bytes long:

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

Asynchronous rmdir(2). No arguments other than a possible exception are given
If `options` is a string, then it specifies the encoding.

## fs.createWriteStream(path[, options])

Returns a new WriteStream object (See `Writable Stream`).

`options` is an object or string with the following defaults:

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

`options` may also include a `start` option to allow writing data at
some position past the beginning of the file. Modifying a file rather
than replacing it may require a `flags` mode of `r+` rather than the
default mode `w`. The `defaultEncoding` can be any one of those accepted by [Buffer][].

Like `ReadStream` above, if `fd` is specified, `WriteStream` will ignore the
`path` argument and will use the specified file descriptor. This means that no
`open` event will be emitted.

If `options` is a string, then it specifies the encoding.

## fs.exists(path, callback)

Stability: 0 - Deprecated: Use [fs.stat][] or [fs.access][] instead.

Test whether or not the given path exists by checking with the file system.
Then call the `callback` argument with either true or false. Example:

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

`fs.exists()` should not be used to check if a file exists before calling
`fs.open()`. Doing so introduces a race condition since other processes may
change the file's state between the two calls. Instead, user code should
call `fs.open()` directly and handle the error raised if the file is
non-existent.

## fs.existsSync(path)

Synchronous version of [`fs.exists`](fs.html#fs_fs_exists_path_callback).
Returns `true` if the file exists, `false` otherwise.

Stability: 0 - Deprecated: Use [fs.statSync][] or [fs.accessSync][] instead.

## fs.fchmod(fd, mode, callback)

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

## fs.fchmodSync(fd, mode)

Synchronous fchmod(2). Returns `undefined`.

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

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

## fs.rmdirSync(path)
## fs.fchownSync(fd, uid, gid)

Synchronous rmdir(2). Returns `undefined`.
Synchronous fchown(2). Returns `undefined`.

## fs.mkdir(path[, mode], callback)
## fs.fstat(fd, callback)

Asynchronous mkdir(2). No arguments other than a possible exception are given
to the completion callback. `mode` defaults to `0o777`.
Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
`stats` is a `fs.Stats` object. `fstat()` is identical to `stat()`, except that
the file to be stat-ed is specified by the file descriptor `fd`.

## fs.mkdirSync(path[, mode])
## fs.fstatSync(fd)

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

## fs.readdir(path, callback)
## fs.fsync(fd, 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 `'..'`.
Asynchronous fsync(2). No arguments other than a possible exception are given
to the completion callback.

## fs.readdirSync(path)
## fs.fsyncSync(fd)

Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
`'..'`.
Synchronous fsync(2). Returns `undefined`.

## fs.close(fd, callback)
## fs.ftruncate(fd, len, callback)

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

## fs.ftruncateSync(fd, len)

Synchronous ftruncate(2). Returns `undefined`.

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

Change the file timestamps of a file referenced by the supplied file
descriptor.

## fs.futimesSync(fd, atime, mtime)

Synchronous version of `fs.futimes()`. Returns `undefined`.

## fs.lchmod(path, mode, callback)

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

Only available on Mac OS X.

## fs.lchmodSync(path, mode)

Synchronous lchmod(2). Returns `undefined`.

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

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

## fs.closeSync(fd)
## fs.lchownSync(path, uid, gid)

Synchronous close(2). Returns `undefined`.
Synchronous lchown(2). Returns `undefined`.

## fs.link(srcpath, dstpath, callback)

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

## fs.linkSync(srcpath, dstpath)

Synchronous link(2). Returns `undefined`.

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

## fs.lstatSync(path)

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

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

Asynchronous mkdir(2). No arguments other than a possible exception are given
to the completion callback. `mode` defaults to `0o777`.

## fs.mkdirSync(path[, mode])

Synchronous mkdir(2). Returns `undefined`.

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

@@ -359,255 +538,158 @@ the end of the file.
Synchronous version of `fs.open()`. Returns an integer representing the file
descriptor.

## fs.utimes(path, atime, mtime, callback)
## fs.read(fd, buffer, offset, length, position, callback)

Change file timestamps of the file referenced by the supplied path.
Read data from the file specified by `fd`.

Note: the arguments `atime` and `mtime` of the following related functions does
follow the below rules:
`buffer` is the buffer that the data will be written to.

- If the value is a numberable string like "123456789", the value would get
converted to corresponding number.
- If the value is `NaN` or `Infinity`, the value would get converted to
`Date.now()`.
`offset` is the offset in the buffer to start writing at.

## fs.utimesSync(path, atime, mtime)
`length` is an integer specifying the number of bytes to read.

Synchronous version of `fs.utimes()`. Returns `undefined`.
`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 three arguments, `(err, bytesRead, buffer)`.

## fs.futimes(fd, atime, mtime, callback)
## fs.readdir(path, callback)

Change the file timestamps of a file referenced by the supplied file
descriptor.
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 `'..'`.

## fs.futimesSync(fd, atime, mtime)
## fs.readdirSync(path)

Synchronous version of `fs.futimes()`. Returns `undefined`.
Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
`'..'`.

## fs.fsync(fd, callback)
## fs.readFile(file[, options], callback)

Asynchronous fsync(2). No arguments other than a possible exception are given
to the completion callback.
* `file` {String | Integer} filename or file descriptor
* `options` {Object | String}
* `encoding` {String | Null} default = `null`
* `flag` {String} default = `'r'`
* `callback` {Function}

## fs.fsyncSync(fd)
Asynchronously reads the entire contents of a file. Example:

Synchronous fsync(2). Returns `undefined`.
fs.readFile('/etc/passwd', function (err, data) {
if (err) throw err;
console.log(data);
});

## fs.write(fd, buffer, offset, length[, position], callback)
The callback is passed two arguments `(err, data)`, where `data` is the
contents of the file.

Write `buffer` to the file specified by `fd`.
If no encoding is specified, then the raw buffer is returned.

`offset` and `length` determine the part of the buffer to be written.
If `options` is a string, then it specifies the encoding. Example:

`position` refers to the offset from the beginning of the file where this data
should be written. If `typeof position !== 'number'`, the data will be written
at the current position. See pwrite(2).
fs.readFile('/etc/passwd', 'utf8', callback);

The callback will be given three arguments `(err, written, buffer)` where
`written` specifies how many _bytes_ were written from `buffer`.
Any specified file descriptor has to support reading.

Note that it is unsafe to use `fs.write` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.
_Note: Specified file descriptors will not be closed automatically._

On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.
## fs.readFileSync(file[, options])

## fs.write(fd, data[, position[, encoding]], callback)
Synchronous version of `fs.readFile`. Returns the contents of the `file`.

Write `data` to the file specified by `fd`. If `data` is not a Buffer instance
then the value will be coerced to a string.
If the `encoding` option is specified then this function returns a
string. Otherwise it returns a buffer.

`position` refers to the offset from the beginning of the file where this data
should be written. If `typeof position !== 'number'` the data will be written at
the current position. See pwrite(2).
## fs.readlink(path, callback)

`encoding` is the expected string encoding.
Asynchronous readlink(2). The callback gets two arguments `(err,
linkString)`.

The callback will receive the arguments `(err, written, string)` where `written`
specifies how many _bytes_ the passed string required to be written. Note that
bytes written is not the same as string characters. See
[Buffer.byteLength](buffer.html#buffer_class_method_buffer_bytelength_string_encoding).
## fs.readlinkSync(path)

Unlike when writing `buffer`, the entire string must be written. No substring
may be specified. This is because the byte offset of the resulting data may not
be the same as the string offset.
Synchronous readlink(2). Returns the symbolic link's string value.

Note that it is unsafe to use `fs.write` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.

On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

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

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

Synchronous versions of `fs.write()`. Returns the number of bytes written.

## 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 the offset in the buffer to start writing at.

`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 three arguments, `(err, bytesRead, buffer)`.

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

Synchronous version of `fs.read`. Returns the number of `bytesRead`.

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

* `file` {String | Integer} filename or file descriptor
* `options` {Object | String}
* `encoding` {String | Null} default = `null`
* `flag` {String} default = `'r'`
* `callback` {Function}

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.

If `options` is a string, then it specifies the encoding. Example:

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

Any specified file descriptor has to support reading.

_Note: Specified file descriptors will not be closed automatically._

## fs.readFileSync(file[, options])

Synchronous version of `fs.readFile`. Returns the contents of the `file`.

If the `encoding` option is specified then this function returns a
string. Otherwise it returns a buffer.

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

* `file` {String | Integer} filename or file descriptor
* `data` {String | Buffer}
* `options` {Object | String}
* `encoding` {String | Null} default = `'utf8'`
* `mode` {Number} default = `0o666`
* `flag` {String} default = `'w'`
* `callback` {Function}

Asynchronously writes data to a file, replacing the file if it already exists.
`data` can be a string or a buffer.
## fs.realpath(path[, cache], callback)

The `encoding` option is ignored if `data` is a buffer. It defaults
to `'utf8'`.
Asynchronous realpath(2). The `callback` gets two arguments `(err,
resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an
object literal of mapped paths that can be used to force a specific path
resolution or avoid additional `fs.stat` calls for known real paths.

Example:

fs.writeFile('message.txt', 'Hello Node.js', function (err) {
var cache = {'/etc':'/private/etc'};
fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
if (err) throw err;
console.log('It\'s saved!');
console.log(resolvedPath);
});

If `options` is a string, then it specifies the encoding. Example:
## fs.readSync(fd, buffer, offset, length, position)

fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
Synchronous version of `fs.read`. Returns the number of `bytesRead`.

Any specified file descriptor has to support writing.
## fs.realpathSync(path[, cache])

Note that it is unsafe to use `fs.writeFile` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.
Synchronous realpath(2). Returns the resolved path.

_Note: Specified file descriptors will not be closed automatically._
## fs.rename(oldPath, newPath, callback)

## fs.writeFileSync(file, data[, options])
Asynchronous rename(2). No arguments other than a possible exception are given
to the completion callback.

The synchronous version of `fs.writeFile`. Returns `undefined`.
## fs.renameSync(oldPath, newPath)

## fs.appendFile(file, data[, options], callback)
Synchronous rename(2). Returns `undefined`.

* `file` {String | Integer} filename or file descriptor
* `data` {String | Buffer}
* `options` {Object | String}
* `encoding` {String | Null} default = `'utf8'`
* `mode` {Number} default = `0o666`
* `flag` {String} default = `'a'`
* `callback` {Function}
## fs.rmdir(path, callback)

Asynchronously append data to a file, creating the file if it does not yet exist.
`data` can be a string or a buffer.
Asynchronous rmdir(2). No arguments other than a possible exception are given
to the completion callback.

Example:
## fs.rmdirSync(path)

fs.appendFile('message.txt', 'data to append', function (err) {
if (err) throw err;
console.log('The "data to append" was appended to file!');
});
Synchronous rmdir(2). Returns `undefined`.

If `options` is a string, then it specifies the encoding. Example:
## fs.stat(path, callback)

fs.appendFile('message.txt', 'data to append', 'utf8', callback);
Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
`stats` is a [fs.Stats](#fs_class_fs_stats) object. See the [fs.Stats](#fs_class_fs_stats)
section below for more information.

Any specified file descriptor has to have been opened for appending.
## fs.statSync(path)

_Note: Specified file descriptors will not be closed automatically._
Synchronous stat(2). Returns an instance of `fs.Stats`.

## fs.appendFileSync(file, data[, options])
## fs.symlink(destination, path[, type], callback)

The synchronous version of `fs.appendFile`. Returns `undefined`.
Asynchronous symlink(2). No arguments other than a possible exception are given
to the completion callback.
The `type` argument can be set to `'dir'`, `'file'`, or `'junction'` (default
is `'file'`) and is only available on Windows (ignored on other platforms).
Note that Windows junction points require the destination path to be absolute. When using
`'junction'`, the `destination` argument will automatically be normalized to absolute path.

## fs.watchFile(filename[, options], listener)
## fs.symlinkSync(destination, path[, type])

Watch for changes on `filename`. The callback `listener` will be called each
time the file is accessed.
Synchronous symlink(2). Returns `undefined`.

The `options` argument may be omitted. If provided, it should be an object. The
`options` object may contain a boolean named `persistent` that indicates
whether the process should continue to run as long as files are being watched.
The `options` object may specify an `interval` property indicating how often the
target should be polled in milliseconds. The default is
`{ persistent: true, interval: 5007 }`.
## fs.truncate(path, len, callback)

The `listener` gets two arguments the current stat object and the previous
stat object:
Asynchronous truncate(2). No arguments other than a possible exception are
given to the completion callback. A file descriptor can also be passed as the
first argument. In this case, `fs.ftruncate()` is called.

fs.watchFile('message.text', function (curr, prev) {
console.log('the current mtime is: ' + curr.mtime);
console.log('the previous mtime was: ' + prev.mtime);
});
## fs.truncateSync(path, len)

These stat objects are instances of `fs.Stat`.
Synchronous truncate(2). Returns `undefined`.

If you want to be notified when the file was modified, not just accessed,
you need to compare `curr.mtime` and `prev.mtime`.
## fs.unlink(path, callback)

_Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will
invoke the listener once, with all the fields zeroed (or, for dates, the Unix
Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead
of zero. If the file is created later on, the listener will be called again,
with the latest stat objects. This is a change in functionality since v0.10._
Asynchronous unlink(2). No arguments other than a possible exception are given
to the completion callback.

_Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`
when possible._
## fs.unlinkSync(path)

Synchronous unlink(2). Returns `undefined`.

## fs.unwatchFile(filename[, listener])

@@ -622,6 +704,22 @@ _Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`
when possible._

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

Change file timestamps of the file referenced by the supplied path.

Note: the arguments `atime` and `mtime` of the following related functions does
follow the below rules:

- If the value is a numberable string like "123456789", the value would get
converted to corresponding number.
- If the value is `NaN` or `Infinity`, the value would get converted to
`Date.now()`.

## fs.utimesSync(path, atime, mtime)

Synchronous version of `fs.utimes()`. Returns `undefined`.

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

Watch for changes on `filename`, where `filename` is either a file or a
@@ -674,7 +772,7 @@ less reliable.

<!--type=misc-->

Providing `filename` argument in the callback is only supported on Linux and
Providing `filename` argument in the callback is only supported on Linux and
Windows. Even on supported platforms, `filename` is not always guaranteed to
be provided. Therefore, don't assume that `filename` argument is always
provided in the callback, and have some fallback logic if it is null.
@@ -688,239 +786,137 @@ provided in the callback, and have some fallback logic if it is null.
}
});

## fs.exists(path, callback)

Stability: 0 - Deprecated: Use [fs.stat][] or [fs.access][] instead.

Test whether or not the given path exists by checking with the file system.
Then call the `callback` argument with either true or false. Example:

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

`fs.exists()` should not be used to check if a file exists before calling
`fs.open()`. Doing so introduces a race condition since other processes may
change the file's state between the two calls. Instead, user code should
call `fs.open()` directly and handle the error raised if the file is
non-existent.

## fs.existsSync(path)

Synchronous version of [`fs.exists`](fs.html#fs_fs_exists_path_callback).
Returns `true` if the file exists, `false` otherwise.

Stability: 0 - Deprecated: Use [fs.statSync][] or [fs.accessSync][] instead.

## fs.access(path[, mode], callback)
## fs.watchFile(filename[, options], listener)

Tests a user's permissions for the file specified by `path`. `mode` 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.
Watch for changes on `filename`. The callback `listener` will be called each
time the file is accessed.

- `fs.F_OK` - File 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.R_OK` - File can be read by the calling process.
- `fs.W_OK` - File can be written by the calling process.
- `fs.X_OK` - File can be executed by the calling process. This has no effect
on Windows (will behave like `fs.F_OK`).
The `options` argument may be omitted. If provided, it should be an object. The
`options` object may contain a boolean named `persistent` that indicates
whether the process should continue to run as long as files are being watched.
The `options` object may specify an `interval` property indicating how often the
target should be polled in milliseconds. The default is
`{ persistent: true, interval: 5007 }`.

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.
The `listener` gets two arguments the current stat object and the previous
stat object:

fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function (err) {
console.log(err ? 'no access!' : 'can read/write');
fs.watchFile('message.text', function (curr, prev) {
console.log('the current mtime is: ' + curr.mtime);
console.log('the previous mtime was: ' + prev.mtime);
});

## fs.accessSync(path[, mode])

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

## 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:

{ 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][MDN-Date] object and to compare the values of
these objects you should use appropriate methods. For most general
uses [getTime()][MDN-Date-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][MDN-Date]
page.

[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime

### 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`). 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.

## fs.createReadStream(path[, options])

Returns a new ReadStream object (See `Readable Stream`).

Be aware that, unlike the default value set for `highWaterMark` on a
readable stream (16 kb), the stream returned by this method has a
default value of 64 kb for the same parameter.

`options` is an object or string with the following defaults:

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

`options` can include `start` and `end` values to read a range of bytes from
the file instead of the entire file. Both `start` and `end` are inclusive and
start at 0. The `encoding` can be any one of those accepted by [Buffer][].

If `fd` is specified, `ReadStream` will ignore the `path` argument and will use
the specified file descriptor. This means that no `open` event will be emitted.

If `autoClose` is false, then the file descriptor won't be closed, even if
there's an error. It is your responsibility to close it and make sure
there's no file descriptor leak. If `autoClose` is set to true (default
behavior), on `error` or `end` the file descriptor will be closed
automatically.

`mode` sets the file mode (permission and sticky bits), but only if the
file was created.
These stat objects are instances of `fs.Stat`.

An example to read the last 10 bytes of a file which is 100 bytes long:
If you want to be notified when the file was modified, not just accessed,
you need to compare `curr.mtime` and `prev.mtime`.

fs.createReadStream('sample.txt', {start: 90, end: 99});
_Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will
invoke the listener once, with all the fields zeroed (or, for dates, the Unix
Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead
of zero. If the file is created later on, the listener will be called again,
with the latest stat objects. This is a change in functionality since v0.10._

If `options` is a string, then it specifies the encoding.
_Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`
when possible._

## Class: fs.ReadStream
## fs.write(fd, buffer, offset, length[, position], callback)

`ReadStream` is a [Readable Stream](stream.html#stream_class_stream_readable).
Write `buffer` to the file specified by `fd`.

### Event: 'open'
`offset` and `length` determine the part of the buffer to be written.

* `fd` {Integer} file descriptor used by the ReadStream.
`position` refers to the offset from the beginning of the file where this data
should be written. If `typeof position !== 'number'`, the data will be written
at the current position. See pwrite(2).

Emitted when the ReadStream's file is opened.
The callback will be given three arguments `(err, written, buffer)` where
`written` specifies how many _bytes_ were written from `buffer`.

Note that it is unsafe to use `fs.write` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.

## fs.createWriteStream(path[, options])
On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

Returns a new WriteStream object (See `Writable Stream`).
## fs.write(fd, data[, position[, encoding]], callback)

`options` is an object or string with the following defaults:
Write `data` to the file specified by `fd`. If `data` is not a Buffer instance
then the value will be coerced to a string.

{ flags: 'w',
defaultEncoding: 'utf8',
fd: null,
mode: 0o666 }
`position` refers to the offset from the beginning of the file where this data
should be written. If `typeof position !== 'number'` the data will be written at
the current position. See pwrite(2).

`options` may also include a `start` option to allow writing data at
some position past the beginning of the file. Modifying a file rather
than replacing it may require a `flags` mode of `r+` rather than the
default mode `w`. The `defaultEncoding` can be any one of those accepted by [Buffer][].
`encoding` is the expected string encoding.

Like `ReadStream` above, if `fd` is specified, `WriteStream` will ignore the
`path` argument and will use the specified file descriptor. This means that no
`open` event will be emitted.
The callback will receive the arguments `(err, written, string)` where `written`
specifies how many _bytes_ the passed string required to be written. Note that
bytes written is not the same as string characters. See
[Buffer.byteLength](buffer.html#buffer_class_method_buffer_bytelength_string_encoding).

If `options` is a string, then it specifies the encoding.
Unlike when writing `buffer`, the entire string must be written. No substring
may be specified. This is because the byte offset of the resulting data may not
be the same as the string offset.

## Class: fs.WriteStream
Note that it is unsafe to use `fs.write` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.

`WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable).
On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

### Event: 'open'
## fs.writeFile(file, data[, options], callback)

* `fd` {Integer} file descriptor used by the WriteStream.
* `file` {String | Integer} filename or file descriptor
* `data` {String | Buffer}
* `options` {Object | String}
* `encoding` {String | Null} default = `'utf8'`
* `mode` {Number} default = `0o666`
* `flag` {String} default = `'w'`
* `callback` {Function}

Emitted when the WriteStream's file is opened.
Asynchronously writes data to a file, replacing the file if it already exists.
`data` can be a string or a buffer.

### file.bytesWritten
The `encoding` option is ignored if `data` is a buffer. It defaults
to `'utf8'`.

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

## Class: fs.FSWatcher
fs.writeFile('message.txt', 'Hello Node.js', function (err) {
if (err) throw err;
console.log('It\'s saved!');
});

Objects returned from `fs.watch()` are of this type.
If `options` is a string, then it specifies the encoding. Example:

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

Stop watching for changes on the given `fs.FSWatcher`.
Any specified file descriptor has to support writing.

### Event: 'change'
Note that it is unsafe to use `fs.writeFile` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.

* `event` {String} The type of fs change
* `filename` {String} The filename that changed (if relevant/available)
_Note: Specified file descriptors will not be closed automatically._

Emitted when something changes in a watched directory or file.
See more details in [fs.watch](#fs_fs_watch_filename_options_listener).
## fs.writeFileSync(file, data[, options])

### Event: 'error'
The synchronous version of `fs.writeFile`. Returns `undefined`.

* `error` {Error object}
## fs.writeSync(fd, buffer, offset, length[, position])

Emitted when an error occurs.
## fs.writeSync(fd, data[, position[, encoding]])

Synchronous versions of `fs.write()`. Returns the number of bytes written.

[fs.stat]: #fs_fs_stat_path_callback
[fs.access]: #fs_fs_access_path_mode_callback
[fs.statSync]: #fs_fs_statsync_path
[fs.accessSync]: #fs_fs_accesssync_path_mode
[Buffer]: buffer.html#buffer_buffer
[Buffer]: buffer.html#buffer_buffer

0 comments on commit c3f5ea7

Please sign in to comment.