7 File I/O is provided by simple wrappers around standard POSIX functions. To
8 use this module do `require('fs')`. All the methods have asynchronous and
11 The asynchronous form always take a completion callback as its last argument.
12 The arguments passed to the completion callback depend on the method, but the
13 first argument is always reserved for an exception. If the operation was
14 completed successfully, then the first argument will be `null` or `undefined`.
16 When using the synchronous form any exceptions are immediately thrown.
17 You can use try/catch to handle exceptions or allow them to bubble up.
19 Here is an example of the asynchronous version:
21 var fs = require('fs');
23 fs.unlink('/tmp/hello', function (err) {
25 console.log('successfully deleted /tmp/hello');
28 Here is the synchronous version:
30 var fs = require('fs');
32 fs.unlinkSync('/tmp/hello');
33 console.log('successfully deleted /tmp/hello');
35 With the asynchronous methods there is no guaranteed ordering. So the
36 following is prone to error:
38 fs.rename('/tmp/hello', '/tmp/world', function (err) {
40 console.log('renamed complete');
42 fs.stat('/tmp/world', function (err, stats) {
44 console.log('stats: ' + JSON.stringify(stats));
47 It could be that `fs.stat` is executed before `fs.rename`.
48 The correct way to do this is to chain the callbacks.
50 fs.rename('/tmp/hello', '/tmp/world', function (err) {
52 fs.stat('/tmp/world', function (err, stats) {
54 console.log('stats: ' + JSON.stringify(stats));
58 In busy processes, the programmer is _strongly encouraged_ to use the
59 asynchronous versions of these calls. The synchronous versions will block
60 the entire process until they complete--halting all connections.
62 Relative path to filename can be used, remember however that this path will be
63 relative to `process.cwd()`.
65 Most fs functions let you omit the callback argument. If you do, a default
66 callback is used that rethrows errors. To get a trace to the original call
67 site, set the NODE_DEBUG environment variable:
71 require('fs').readFile('/');
75 $ env NODE_DEBUG=fs iojs script.js
80 at rethrow (fs.js:61:21)
81 at maybeCallback (fs.js:79:42)
82 at Object.fs.readFile (fs.js:153:18)
83 at bad (/path/to/script.js:2:17)
84 at Object.<anonymous> (/path/to/script.js:5:1)
88 ## fs.rename(oldPath, newPath, callback)
90 Asynchronous rename(2). No arguments other than a possible exception are given
91 to the completion callback.
93 ## fs.renameSync(oldPath, newPath)
95 Synchronous rename(2).
97 ## fs.ftruncate(fd, len, callback)
99 Asynchronous ftruncate(2). No arguments other than a possible exception are
100 given to the completion callback.
102 ## fs.ftruncateSync(fd, len)
104 Synchronous ftruncate(2).
106 ## fs.truncate(path, len, callback)
108 Asynchronous truncate(2). No arguments other than a possible exception are
109 given to the completion callback. A file descriptor can also be passed as the
110 first argument. In this case, `fs.ftruncate()` is called.
112 ## fs.truncateSync(path, len)
114 Synchronous truncate(2).
116 ## fs.chown(path, uid, gid, callback)
118 Asynchronous chown(2). No arguments other than a possible exception are given
119 to the completion callback.
121 ## fs.chownSync(path, uid, gid)
123 Synchronous chown(2).
125 ## fs.fchown(fd, uid, gid, callback)
127 Asynchronous fchown(2). No arguments other than a possible exception are given
128 to the completion callback.
130 ## fs.fchownSync(fd, uid, gid)
132 Synchronous fchown(2).
134 ## fs.lchown(path, uid, gid, callback)
136 Asynchronous lchown(2). No arguments other than a possible exception are given
137 to the completion callback.
139 ## fs.lchownSync(path, uid, gid)
141 Synchronous lchown(2).
143 ## fs.chmod(path, mode, callback)
145 Asynchronous chmod(2). No arguments other than a possible exception are given
146 to the completion callback.
148 ## fs.chmodSync(path, mode)
150 Synchronous chmod(2).
152 ## fs.fchmod(fd, mode, callback)
154 Asynchronous fchmod(2). No arguments other than a possible exception
155 are given to the completion callback.
157 ## fs.fchmodSync(fd, mode)
159 Synchronous fchmod(2).
161 ## fs.lchmod(path, mode, callback)
163 Asynchronous lchmod(2). No arguments other than a possible exception
164 are given to the completion callback.
166 Only available on Mac OS X.
168 ## fs.lchmodSync(path, mode)
170 Synchronous lchmod(2).
172 ## fs.stat(path, callback)
174 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
175 `stats` is a [fs.Stats](#fs_class_fs_stats) object. See the [fs.Stats](#fs_class_fs_stats)
176 section below for more information.
178 ## fs.lstat(path, callback)
180 Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
181 `stats` is a `fs.Stats` object. `lstat()` is identical to `stat()`, except that if
182 `path` is a symbolic link, then the link itself is stat-ed, not the file that it
185 ## fs.fstat(fd, callback)
187 Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
188 `stats` is a `fs.Stats` object. `fstat()` is identical to `stat()`, except that
189 the file to be stat-ed is specified by the file descriptor `fd`.
193 Synchronous stat(2). Returns an instance of `fs.Stats`.
195 ## fs.lstatSync(path)
197 Synchronous lstat(2). Returns an instance of `fs.Stats`.
201 Synchronous fstat(2). Returns an instance of `fs.Stats`.
203 ## fs.link(srcpath, dstpath, callback)
205 Asynchronous link(2). No arguments other than a possible exception are given to
206 the completion callback.
208 ## fs.linkSync(srcpath, dstpath)
212 ## fs.symlink(destination, path[, type], callback)
214 Asynchronous symlink(2). No arguments other than a possible exception are given
215 to the completion callback.
216 The `type` argument can be set to `'dir'`, `'file'`, or `'junction'` (default
217 is `'file'`) and is only available on Windows (ignored on other platforms).
218 Note that Windows junction points require the destination path to be absolute. When using
219 `'junction'`, the `destination` argument will automatically be normalized to absolute path.
221 ## fs.symlinkSync(destination, path[, type])
223 Synchronous symlink(2).
225 ## fs.readlink(path, callback)
227 Asynchronous readlink(2). The callback gets two arguments `(err,
230 ## fs.readlinkSync(path)
232 Synchronous readlink(2). Returns the symbolic link's string value.
234 ## fs.realpath(path[, cache], callback)
236 Asynchronous realpath(2). The `callback` gets two arguments `(err,
237 resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an
238 object literal of mapped paths that can be used to force a specific path
239 resolution or avoid additional `fs.stat` calls for known real paths.
243 var cache = {'/etc':'/private/etc'};
244 fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
246 console.log(resolvedPath);
249 ## fs.realpathSync(path[, cache])
251 Synchronous realpath(2). Returns the resolved path.
253 ## fs.unlink(path, callback)
255 Asynchronous unlink(2). No arguments other than a possible exception are given
256 to the completion callback.
258 ## fs.unlinkSync(path)
260 Synchronous unlink(2).
262 ## fs.rmdir(path, callback)
264 Asynchronous rmdir(2). No arguments other than a possible exception are given
265 to the completion callback.
267 ## fs.rmdirSync(path)
269 Synchronous rmdir(2).
271 ## fs.mkdir(path[, mode], callback)
273 Asynchronous mkdir(2). No arguments other than a possible exception are given
274 to the completion callback. `mode` defaults to `0o777`.
276 ## fs.mkdirSync(path[, mode])
278 Synchronous mkdir(2).
280 ## fs.readdir(path, callback)
282 Asynchronous readdir(3). Reads the contents of a directory.
283 The callback gets two arguments `(err, files)` where `files` is an array of
284 the names of the files in the directory excluding `'.'` and `'..'`.
286 ## fs.readdirSync(path)
288 Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
291 ## fs.close(fd, callback)
293 Asynchronous close(2). No arguments other than a possible exception are given
294 to the completion callback.
298 Synchronous close(2).
300 ## fs.open(path, flags[, mode], callback)
302 Asynchronous file open. See open(2). `flags` can be:
304 * `'r'` - Open file for reading.
305 An exception occurs if the file does not exist.
307 * `'r+'` - Open file for reading and writing.
308 An exception occurs if the file does not exist.
310 * `'rs'` - Open file for reading in synchronous mode. Instructs the operating
311 system to bypass the local file system cache.
313 This is primarily useful for opening files on NFS mounts as it allows you to
314 skip the potentially stale local cache. It has a very real impact on I/O
315 performance so don't use this flag unless you need it.
317 Note that this doesn't turn `fs.open()` into a synchronous blocking call.
318 If that's what you want then you should be using `fs.openSync()`
320 * `'rs+'` - Open file for reading and writing, telling the OS to open it
321 synchronously. See notes for `'rs'` about using this with caution.
323 * `'w'` - Open file for writing.
324 The file is created (if it does not exist) or truncated (if it exists).
326 * `'wx'` - Like `'w'` but fails if `path` exists.
328 * `'w+'` - Open file for reading and writing.
329 The file is created (if it does not exist) or truncated (if it exists).
331 * `'wx+'` - Like `'w+'` but fails if `path` exists.
333 * `'a'` - Open file for appending.
334 The file is created if it does not exist.
336 * `'ax'` - Like `'a'` but fails if `path` exists.
338 * `'a+'` - Open file for reading and appending.
339 The file is created if it does not exist.
341 * `'ax+'` - Like `'a+'` but fails if `path` exists.
343 `mode` sets the file mode (permission and sticky bits), but only if the file was
344 created. It defaults to `0666`, readable and writeable.
346 The callback gets two arguments `(err, fd)`.
348 The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly
349 created. On POSIX systems, `path` is considered to exist even if it is a symlink
350 to a non-existent file. The exclusive flag may or may not work with network file
353 On Linux, positional writes don't work when the file is opened in append mode.
354 The kernel ignores the position argument and always appends the data to
357 ## fs.openSync(path, flags[, mode])
359 Synchronous version of `fs.open()`.
361 ## fs.utimes(path, atime, mtime, callback)
362 ## fs.utimesSync(path, atime, mtime)
364 Change file timestamps of the file referenced by the supplied path.
366 ## fs.futimes(fd, atime, mtime, callback)
367 ## fs.futimesSync(fd, atime, mtime)
369 Change the file timestamps of a file referenced by the supplied file
372 ## fs.fsync(fd, callback)
374 Asynchronous fsync(2). No arguments other than a possible exception are given
375 to the completion callback.
379 Synchronous fsync(2).
381 ## fs.write(fd, buffer, offset, length[, position], callback)
383 Write `buffer` to the file specified by `fd`.
385 `offset` and `length` determine the part of the buffer to be written.
387 `position` refers to the offset from the beginning of the file where this data
388 should be written. If `typeof position !== 'number'`, the data will be written
389 at the current position. See pwrite(2).
391 The callback will be given three arguments `(err, written, buffer)` where
392 `written` specifies how many _bytes_ were written from `buffer`.
394 Note that it is unsafe to use `fs.write` multiple times on the same file
395 without waiting for the callback. For this scenario,
396 `fs.createWriteStream` is strongly recommended.
398 On Linux, positional writes don't work when the file is opened in append mode.
399 The kernel ignores the position argument and always appends the data to
402 ## fs.write(fd, data[, position[, encoding]], callback)
404 Write `data` to the file specified by `fd`. If `data` is not a Buffer instance
405 then the value will be coerced to a string.
407 `position` refers to the offset from the beginning of the file where this data
408 should be written. If `typeof position !== 'number'` the data will be written at
409 the current position. See pwrite(2).
411 `encoding` is the expected string encoding.
413 The callback will receive the arguments `(err, written, string)` where `written`
414 specifies how many _bytes_ the passed string required to be written. Note that
415 bytes written is not the same as string characters. See
416 [Buffer.byteLength](buffer.html#buffer_class_method_buffer_bytelength_string_encoding).
418 Unlike when writing `buffer`, the entire string must be written. No substring
419 may be specified. This is because the byte offset of the resulting data may not
420 be the same as the string offset.
422 Note that it is unsafe to use `fs.write` multiple times on the same file
423 without waiting for the callback. For this scenario,
424 `fs.createWriteStream` is strongly recommended.
426 On Linux, positional writes don't work when the file is opened in append mode.
427 The kernel ignores the position argument and always appends the data to
430 ## fs.writeSync(fd, buffer, offset, length[, position])
432 ## fs.writeSync(fd, data[, position[, encoding]])
434 Synchronous versions of `fs.write()`. Returns the number of bytes written.
436 ## fs.read(fd, buffer, offset, length, position, callback)
438 Read data from the file specified by `fd`.
440 `buffer` is the buffer that the data will be written to.
442 `offset` is the offset in the buffer to start writing at.
444 `length` is an integer specifying the number of bytes to read.
446 `position` is an integer specifying where to begin reading from in the file.
447 If `position` is `null`, data will be read from the current file position.
449 The callback is given the three arguments, `(err, bytesRead, buffer)`.
451 ## fs.readSync(fd, buffer, offset, length, position)
453 Synchronous version of `fs.read`. Returns the number of `bytesRead`.
455 ## fs.readFile(filename[, options], callback)
457 * `filename` {String}
459 * `encoding` {String | Null} default = `null`
460 * `flag` {String} default = `'r'`
461 * `callback` {Function}
463 Asynchronously reads the entire contents of a file. Example:
465 fs.readFile('/etc/passwd', function (err, data) {
470 The callback is passed two arguments `(err, data)`, where `data` is the
471 contents of the file.
473 If no encoding is specified, then the raw buffer is returned.
476 ## fs.readFileSync(filename[, options])
478 Synchronous version of `fs.readFile`. Returns the contents of the `filename`.
480 If the `encoding` option is specified then this function returns a
481 string. Otherwise it returns a buffer.
484 ## fs.writeFile(filename, data[, options], callback)
486 * `filename` {String}
487 * `data` {String | Buffer}
489 * `encoding` {String | Null} default = `'utf8'`
490 * `mode` {Number} default = `0o666`
491 * `flag` {String} default = `'w'`
492 * `callback` {Function}
494 Asynchronously writes data to a file, replacing the file if it already exists.
495 `data` can be a string or a buffer.
497 The `encoding` option is ignored if `data` is a buffer. It defaults
502 fs.writeFile('message.txt', 'Hello io.js', function (err) {
504 console.log('It\'s saved!');
507 ## fs.writeFileSync(filename, data[, options])
509 The synchronous version of `fs.writeFile`.
511 ## fs.appendFile(filename, data[, options], callback)
513 * `filename` {String}
514 * `data` {String | Buffer}
516 * `encoding` {String | Null} default = `'utf8'`
517 * `mode` {Number} default = `0o666`
518 * `flag` {String} default = `'a'`
519 * `callback` {Function}
521 Asynchronously append data to a file, creating the file if it does not yet exist.
522 `data` can be a string or a buffer.
526 fs.appendFile('message.txt', 'data to append', function (err) {
528 console.log('The "data to append" was appended to file!');
531 ## fs.appendFileSync(filename, data[, options])
533 The synchronous version of `fs.appendFile`.
535 ## fs.watchFile(filename[, options], listener)
537 Stability: 2 - Unstable. Use fs.watch instead, if possible.
539 Watch for changes on `filename`. The callback `listener` will be called each
540 time the file is accessed.
542 The second argument is optional. The `options` if provided should be an object
543 containing two members a boolean, `persistent`, and `interval`. `persistent`
544 indicates whether the process should continue to run as long as files are
545 being watched. `interval` indicates how often the target should be polled,
546 in milliseconds. The default is `{ persistent: true, interval: 5007 }`.
548 The `listener` gets two arguments the current stat object and the previous
551 fs.watchFile('message.text', function (curr, prev) {
552 console.log('the current mtime is: ' + curr.mtime);
553 console.log('the previous mtime was: ' + prev.mtime);
556 These stat objects are instances of `fs.Stat`.
558 If you want to be notified when the file was modified, not just accessed
559 you need to compare `curr.mtime` and `prev.mtime`.
561 ## fs.unwatchFile(filename[, listener])
563 Stability: 2 - Unstable. Use fs.watch instead, if possible.
565 Stop watching for changes on `filename`. If `listener` is specified, only that
566 particular listener is removed. Otherwise, *all* listeners are removed and you
567 have effectively stopped watching `filename`.
569 Calling `fs.unwatchFile()` with a filename that is not being watched is a
572 ## fs.watch(filename[, options][, listener])
574 Stability: 2 - Unstable.
576 Watch for changes on `filename`, where `filename` is either a file or a
577 directory. The returned object is a [fs.FSWatcher](#fs_class_fs_fswatcher).
579 The second argument is optional. The `options` if provided should be an object.
580 The supported boolean members are `persistent` and `recursive`. `persistent`
581 indicates whether the process should continue to run as long as files are being
582 watched. `recursive` indicates whether all subdirectories should be watched, or
583 only the current directory. This applies when a directory is specified, and only
584 on supported platforms (See Caveats below).
586 The default is `{ persistent: true, recursive: false }`.
588 The listener callback gets two arguments `(event, filename)`. `event` is either
589 'rename' or 'change', and `filename` is the name of the file which triggered
596 The `fs.watch` API is not 100% consistent across platforms, and is
597 unavailable in some situations.
599 The recursive option is currently supported on OS X. Only FSEvents supports this
600 type of file watching so it is unlikely any additional platforms will be added
607 This feature depends on the underlying operating system providing a way
608 to be notified of filesystem changes.
610 * On Linux systems, this uses `inotify`.
611 * On BSD systems, this uses `kqueue`.
612 * On OS X, this uses `kqueue` for files and 'FSEvents' for directories.
613 * On SunOS systems (including Solaris and SmartOS), this uses `event ports`.
614 * On Windows systems, this feature depends on `ReadDirectoryChangesW`.
616 If the underlying functionality is not available for some reason, then
617 `fs.watch` will not be able to function. For example, watching files or
618 directories on network file systems (NFS, SMB, etc.) often doesn't work
621 You can still use `fs.watchFile`, which uses stat polling, but it is slower and
624 #### Filename Argument
628 Providing `filename` argument in the callback is not supported
629 on every platform (currently it's only supported on Linux and Windows). Even
630 on supported platforms `filename` is not always guaranteed to be provided.
631 Therefore, don't assume that `filename` argument is always provided in the
632 callback, and have some fallback logic if it is null.
634 fs.watch('somedir', function (event, filename) {
635 console.log('event is: ' + event);
637 console.log('filename provided: ' + filename);
639 console.log('filename not provided');
643 ## fs.exists(path, callback)
645 Test whether or not the given path exists by checking with the file system.
646 Then call the `callback` argument with either true or false. Example:
648 fs.exists('/etc/passwd', function (exists) {
649 util.debug(exists ? "it's there" : "no passwd!");
652 `fs.exists()` is an anachronism and exists only for historical reasons.
653 There should almost never be a reason to use it in your own code.
655 In particular, checking if a file exists before opening it is an anti-pattern
656 that leaves you vulnerable to race conditions: another process may remove the
657 file between the calls to `fs.exists()` and `fs.open()`. Just open the file
658 and handle the error when it's not there.
660 `fs.exists()` is **deprecated**.
662 ## fs.existsSync(path)
664 Synchronous version of `fs.exists`.
666 `fs.existsSync()` is **deprecated**.
668 ## fs.access(path[, mode], callback)
670 Tests a user's permissions for the file specified by `path`. `mode` is an
671 optional integer that specifies the accessibility checks to be performed. The
672 following constants define the possible values of `mode`. It is possible to
673 create a mask consisting of the bitwise OR of two or more values.
675 - `fs.F_OK` - File is visible to the calling process. This is useful for
676 determining if a file exists, but says nothing about `rwx` permissions.
677 Default if no `mode` is specified.
678 - `fs.R_OK` - File can be read by the calling process.
679 - `fs.W_OK` - File can be written by the calling process.
680 - `fs.X_OK` - File can be executed by the calling process. This has no effect
681 on Windows (will behave like `fs.F_OK`).
683 The final argument, `callback`, is a callback function that is invoked with
684 a possible error argument. If any of the accessibility checks fail, the error
685 argument will be populated. The following example checks if the file
686 `/etc/passwd` can be read and written by the current process.
688 fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function(err) {
689 util.debug(err ? 'no access!' : 'can read/write');
692 ## fs.accessSync(path[, mode])
694 Synchronous version of `fs.access`. This throws if any accessibility checks
695 fail, and does nothing otherwise.
699 Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their
700 synchronous counterparts are of this type.
703 - `stats.isDirectory()`
704 - `stats.isBlockDevice()`
705 - `stats.isCharacterDevice()`
706 - `stats.isSymbolicLink()` (only valid with `fs.lstat()`)
710 For a regular file `util.inspect(stats)` would return a string very
723 atime: Mon, 10 Oct 2011 23:24:11 GMT,
724 mtime: Mon, 10 Oct 2011 23:24:11 GMT,
725 ctime: Mon, 10 Oct 2011 23:24:11 GMT,
726 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
728 Please note that `atime`, `mtime`, `birthtime`, and `ctime` are
729 instances of [Date][MDN-Date] object and to compare the values of
730 these objects you should use appropriate methods. For most general
731 uses [getTime()][MDN-Date-getTime] will return the number of
732 milliseconds elapsed since _1 January 1970 00:00:00 UTC_ and this
733 integer should be sufficient for any comparison, however there are
734 additional methods which can be used for displaying fuzzy information.
735 More details can be found in the [MDN JavaScript Reference][MDN-Date]
738 [MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
739 [MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
743 The times in the stat object have the following semantics:
745 * `atime` "Access Time" - Time when file data last accessed. Changed
746 by the `mknod(2)`, `utimes(2)`, and `read(2)` system calls.
747 * `mtime` "Modified Time" - Time when file data last modified.
748 Changed by the `mknod(2)`, `utimes(2)`, and `write(2)` system calls.
749 * `ctime` "Change Time" - Time when file status was last changed
750 (inode data modification). Changed by the `chmod(2)`, `chown(2)`,
751 `link(2)`, `mknod(2)`, `rename(2)`, `unlink(2)`, `utimes(2)`,
752 `read(2)`, and `write(2)` system calls.
753 * `birthtime` "Birth Time" - Time of file creation. Set once when the
754 file is created. On filesystems where birthtime is not available,
755 this field may instead hold either the `ctime` or
756 `1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). On Darwin and
757 other FreeBSD variants, also set if the `atime` is explicitly set to
758 an earlier value than the current `birthtime` using the `utimes(2)`
761 Prior to io.js v1.0 and Node v0.12, the `ctime` held the `birthtime` on Windows
762 systems. Note that as of v0.12, `ctime` is not "creation time", and
763 on Unix systems, it never was.
765 ## fs.createReadStream(path[, options])
767 Returns a new ReadStream object (See `Readable Stream`).
769 `options` is an object with the following defaults:
778 `options` can include `start` and `end` values to read a range of bytes from
779 the file instead of the entire file. Both `start` and `end` are inclusive and
780 start at 0. The `encoding` can be `'utf8'`, `'ascii'`, or `'base64'`.
782 If `fd` is specified, `ReadStream` will ignore the `path` argument and will use
783 the specified file descriptor. This means that no `open` event will be emitted.
785 If `autoClose` is false, then the file descriptor won't be closed, even if
786 there's an error. It is your responsibility to close it and make sure
787 there's no file descriptor leak. If `autoClose` is set to true (default
788 behavior), on `error` or `end` the file descriptor will be closed
791 An example to read the last 10 bytes of a file which is 100 bytes long:
793 fs.createReadStream('sample.txt', {start: 90, end: 99});
796 ## Class: fs.ReadStream
798 `ReadStream` is a [Readable Stream](stream.html#stream_class_stream_readable).
802 * `fd` {Integer} file descriptor used by the ReadStream.
804 Emitted when the ReadStream's file is opened.
807 ## fs.createWriteStream(path[, options])
809 Returns a new WriteStream object (See `Writable Stream`).
811 `options` is an object with the following defaults:
818 `options` may also include a `start` option to allow writing data at
819 some position past the beginning of the file. Modifying a file rather
820 than replacing it may require a `flags` mode of `r+` rather than the
823 Like `ReadStream` above, if `fd` is specified, `WriteStream` will ignore the
824 `path` argument and will use the specified file descriptor. This means that no
825 `open` event will be emitted.
828 ## Class: fs.WriteStream
830 `WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable).
834 * `fd` {Integer} file descriptor used by the WriteStream.
836 Emitted when the WriteStream's file is opened.
838 ### file.bytesWritten
840 The number of bytes written so far. Does not include data that is still queued
843 ## Class: fs.FSWatcher
845 Objects returned from `fs.watch()` are of this type.
849 Stop watching for changes on the given `fs.FSWatcher`.
853 * `event` {String} The type of fs change
854 * `filename` {String} The filename that changed (if relevant/available)
856 Emitted when something changes in a watched directory or file.
857 See more details in [fs.watch](#fs_fs_watch_filename_options_listener).
861 * `error` {Error object}
863 Emitted when an error occurs.