From 6cd06c131956529332353af69edf6549fcd1edcf Mon Sep 17 00:00:00 2001 From: Tristian Flanagan Date: Wed, 4 Nov 2015 12:07:07 -0500 Subject: [PATCH] doc: sort fs alphabetically Reorders, with no contextual changes, the fs documentation alphabetically. PR-URL: https://github.com/nodejs/node/pull/3662 Reviewed-By: Evan Lucas Reviewed-By: James M Snell Reviewed-By: Jeremiah Senkpiel --- doc/api/fs.markdown | 990 ++++++++++++++++++++++---------------------- 1 file changed, 500 insertions(+), 490 deletions(-) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index bfd9750d22b312..0692d697e258a6 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -84,218 +84,397 @@ site, set the NODE_DEBUG environment variable: at Object. (/path/to/script.js:5:1) +## Class: fs.FSWatcher -## fs.rename(oldPath, newPath, callback) - -Asynchronous rename(2). No arguments other than a possible exception are given -to the completion callback. - -## fs.renameSync(oldPath, newPath) - -Synchronous rename(2). Returns `undefined`. +Objects returned from `fs.watch()` are of this type. -## fs.ftruncate(fd, len, callback) +### Event: 'change' -Asynchronous ftruncate(2). No arguments other than a possible exception are -given to the completion callback. +* `event` {String} The type of fs change +* `filename` {String} The filename that changed (if relevant/available) -## fs.ftruncateSync(fd, len) +Emitted when something changes in a watched directory or file. +See more details in [fs.watch](#fs_fs_watch_filename_options_listener). -Synchronous ftruncate(2). Returns `undefined`. +### Event: 'error' -## fs.truncate(path, len, callback) +* `error` {Error 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. +Emitted when an error occurs. -## fs.truncateSync(path, len) +### watcher.close() -Synchronous truncate(2). Returns `undefined`. +Stop watching for changes on the given `fs.FSWatcher`. -## fs.chown(path, uid, gid, callback) +## Class: fs.ReadStream -Asynchronous chown(2). No arguments other than a possible exception are given -to the completion callback. +`ReadStream` is a [Readable Stream](stream.html#stream_class_stream_readable). -## fs.chownSync(path, uid, gid) +### Event: 'open' -Synchronous chown(2). Returns `undefined`. +* `fd` {Integer} file descriptor used by the ReadStream. -## fs.fchown(fd, uid, gid, callback) +Emitted when the ReadStream's file is opened. -Asynchronous fchown(2). No arguments other than a possible exception are given -to the completion callback. +## Class: fs.Stats -## fs.fchownSync(fd, uid, gid) +Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their +synchronous counterparts are of this type. -Synchronous fchown(2). Returns `undefined`. + - `stats.isFile()` + - `stats.isDirectory()` + - `stats.isBlockDevice()` + - `stats.isCharacterDevice()` + - `stats.isSymbolicLink()` (only valid with `fs.lstat()`) + - `stats.isFIFO()` + - `stats.isSocket()` -## fs.lchown(path, uid, gid, callback) +For a regular file `util.inspect(stats)` would return a string very +similar to this: -Asynchronous lchown(2). No arguments other than a possible exception are given -to the completion callback. + { 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 } -## fs.lchownSync(path, uid, gid) +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. -Synchronous lchown(2). Returns `undefined`. +[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 -## fs.chmod(path, mode, callback) +### Stat Time Values -Asynchronous chmod(2). No arguments other than a possible exception are given -to the completion callback. +The times in the stat object have the following semantics: -## fs.chmodSync(path, mode) +* `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. -Synchronous chmod(2). Returns `undefined`. +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.fchmod(fd, mode, callback) +## Class: fs.WriteStream -Asynchronous fchmod(2). No arguments other than a possible exception -are given to the completion callback. +`WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable). -## fs.fchmodSync(fd, mode) +### Event: 'open' -Synchronous fchmod(2). Returns `undefined`. +* `fd` {Integer} file descriptor used by the WriteStream. -## fs.lchmod(path, mode, callback) +Emitted when the WriteStream's file is opened. -Asynchronous lchmod(2). No arguments other than a possible exception -are given to the completion callback. +### writeStream.bytesWritten -Only available on Mac OS X. +The number of bytes written so far. Does not include data that is still queued +for writing. -## fs.lchmodSync(path, mode) +## fs.access(path[, mode], callback) -Synchronous lchmod(2). Returns `undefined`. +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. -## fs.stat(path, callback) +- `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`). -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. +The final argument, `callback`, is a callback function that is invoked with +a possible error argument. If any of the accessibility checks fail, the error +argument will be populated. The following example checks if the file +`/etc/passwd` can be read and written by the current process. -## fs.lstat(path, callback) + fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function (err) { + console.log(err ? 'no access!' : 'can read/write'); + }); -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.accessSync(path[, mode]) -## fs.fstat(fd, callback) +Synchronous version of `fs.access`. This throws if any accessibility checks +fail, and does nothing otherwise. -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.appendFile(file, data[, options], callback) -## fs.statSync(path) +* `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} -Synchronous stat(2). Returns an instance of `fs.Stats`. +Asynchronously append data to a file, creating the file if it does not yet exist. +`data` can be a string or a buffer. -## fs.lstatSync(path) +Example: -Synchronous lstat(2). Returns an instance of `fs.Stats`. + fs.appendFile('message.txt', 'data to append', function (err) { + if (err) throw err; + console.log('The "data to append" was appended to file!'); + }); -## fs.fstatSync(fd) +If `options` is a string, then it specifies the encoding. Example: -Synchronous fstat(2). Returns an instance of `fs.Stats`. + fs.appendFile('message.txt', 'data to append', 'utf8', callback); -## fs.link(srcpath, dstpath, callback) +Any specified file descriptor has to have been opened for appending. -Asynchronous link(2). No arguments other than a possible exception are given to -the completion callback. +_Note: Specified file descriptors will not be closed automatically._ -## fs.linkSync(srcpath, dstpath) +## fs.appendFileSync(file, data[, options]) -Synchronous link(2). Returns `undefined`. +The synchronous version of `fs.appendFile`. Returns `undefined`. -## fs.symlink(destination, path[, type], callback) +## fs.chmod(path, mode, callback) -Asynchronous symlink(2). No arguments other than a possible exception are given +Asynchronous chmod(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.chmodSync(path, mode) -Synchronous symlink(2). Returns `undefined`. +Synchronous chmod(2). Returns `undefined`. -## fs.readlink(path, callback) +## fs.chown(path, uid, gid, callback) -Asynchronous readlink(2). The callback gets two arguments `(err, -linkString)`. +Asynchronous chown(2). No arguments other than a possible exception are given +to the completion callback. -## fs.readlinkSync(path) +## fs.chownSync(path, uid, gid) -Synchronous readlink(2). Returns the symbolic link's string value. +Synchronous chown(2). Returns `undefined`. -## fs.realpath(path[, cache], callback) +## fs.close(fd, callback) -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. +Asynchronous close(2). No arguments other than a possible exception are given +to the completion callback. -Example: +## fs.closeSync(fd) - var cache = {'/etc':'/private/etc'}; - fs.realpath('/etc/passwd', cache, function (err, resolvedPath) { - if (err) throw err; - console.log(resolvedPath); - }); +Synchronous close(2). Returns `undefined`. -## fs.realpathSync(path[, cache]) +## fs.createReadStream(path[, options]) -Synchronous realpath(2). Returns the resolved path. +Returns a new ReadStream object (See `Readable Stream`). -## fs.unlink(path, callback) +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. -Asynchronous unlink(2). No arguments other than a possible exception are given -to the completion callback. +`options` is an object or string with the following defaults: -## fs.unlinkSync(path) + { flags: 'r', + encoding: null, + fd: null, + mode: 0o666, + autoClose: true + } -Synchronous unlink(2). Returns `undefined`. +`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.rmdir(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 rmdir(2). No arguments other than a possible exception are given +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. + +An example to read the last 10 bytes of a file which is 100 bytes long: + + fs.createReadStream('sample.txt', {start: 90, end: 99}); + +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,241 +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. +## fs.realpath(path[, cache], callback) -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(filename[, options], callback) - -* `filename` {String} -* `options` {Object | String} - * `encoding` {String | Null} default = `null` - * `flag` {String} default = `'r'` -* `callback` {Function} +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. -Asynchronously reads the entire contents of a file. Example: +Example: - fs.readFile('/etc/passwd', function (err, data) { + var cache = {'/etc':'/private/etc'}; + fs.realpath('/etc/passwd', cache, function (err, resolvedPath) { if (err) throw err; - console.log(data); + console.log(resolvedPath); }); -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); - - -## fs.readFileSync(filename[, options]) - -Synchronous version of `fs.readFile`. Returns the contents of the `filename`. - -If the `encoding` option is specified then this function returns a -string. Otherwise it returns a buffer. - - -## fs.writeFile(filename, data[, options], callback) +## fs.readSync(fd, buffer, offset, length, position) -* `filename` {String} -* `data` {String | Buffer} -* `options` {Object | String} - * `encoding` {String | Null} default = `'utf8'` - * `mode` {Number} default = `0o666` - * `flag` {String} default = `'w'` -* `callback` {Function} +Synchronous version of `fs.read`. Returns the number of `bytesRead`. -Asynchronously writes data to a file, replacing the file if it already exists. -`data` can be a string or a buffer. +## fs.realpathSync(path[, cache]) -The `encoding` option is ignored if `data` is a buffer. It defaults -to `'utf8'`. +Synchronous realpath(2). Returns the resolved path. -Example: +## fs.rename(oldPath, newPath, callback) - fs.writeFile('message.txt', 'Hello Node.js', function (err) { - if (err) throw err; - console.log('It\'s saved!'); - }); +Asynchronous rename(2). No arguments other than a possible exception are given +to the completion callback. -If `options` is a string, then it specifies the encoding. Example: +## fs.renameSync(oldPath, newPath) - fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback); +Synchronous rename(2). Returns `undefined`. -## fs.writeFileSync(filename, data[, options]) +## fs.rmdir(path, callback) -The synchronous version of `fs.writeFile`. Returns `undefined`. +Asynchronous rmdir(2). No arguments other than a possible exception are given +to the completion callback. -## fs.appendFile(filename, data[, options], callback) +## fs.rmdirSync(path) -* `filename` {String} -* `data` {String | Buffer} -* `options` {Object | String} - * `encoding` {String | Null} default = `'utf8'` - * `mode` {Number} default = `0o666` - * `flag` {String} default = `'a'` -* `callback` {Function} +Synchronous rmdir(2). Returns `undefined`. -Asynchronously append data to a file, creating the file if it does not yet exist. -`data` can be a string or a buffer. +## fs.stat(path, callback) -Example: +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. - fs.appendFile('message.txt', 'data to append', function (err) { - if (err) throw err; - console.log('The "data to append" was appended to file!'); - }); +## fs.statSync(path) -If `options` is a string, then it specifies the encoding. Example: +Synchronous stat(2). Returns an instance of `fs.Stats`. - fs.appendFile('message.txt', 'data to append', 'utf8', callback); +## fs.symlink(destination, path[, type], callback) -## fs.appendFileSync(filename, data[, options]) +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. -The synchronous version of `fs.appendFile`. Returns `undefined`. +## fs.symlinkSync(destination, path[, type]) -## fs.watchFile(filename[, options], listener) +Synchronous symlink(2). Returns `undefined`. -Watch for changes on `filename`. The callback `listener` will be called each -time the file is accessed. +## fs.truncate(path, len, callback) -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 }`. +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. -The `listener` gets two arguments the current stat object and the previous -stat object: +## fs.truncateSync(path, len) - fs.watchFile('message.text', function (curr, prev) { - console.log('the current mtime is: ' + curr.mtime); - console.log('the previous mtime was: ' + prev.mtime); - }); +Synchronous truncate(2). Returns `undefined`. -These stat objects are instances of `fs.Stat`. +## fs.unlink(path, callback) -If you want to be notified when the file was modified, not just accessed, -you need to compare `curr.mtime` and `prev.mtime`. +Asynchronous unlink(2). No arguments other than a possible exception are given +to the completion 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._ +## fs.unlinkSync(path) -_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._ +Synchronous unlink(2). Returns `undefined`. ## fs.unwatchFile(filename[, listener]) @@ -608,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 @@ -660,7 +772,7 @@ less reliable. -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. @@ -674,236 +786,134 @@ 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