doc/api/fs.markdown

   1 # File System
   2
   3     Stability: 3 - Stable
   4
   5 <!--name=fs-->
   6
   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
   9 synchronous forms.
  10
  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`.
  15
  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.
  18
  19 Here is an example of the asynchronous version:
  20
  21     var fs = require('fs');
  22
  23     fs.unlink('/tmp/hello', function (err) {
  24       if (err) throw err;
  25       console.log('successfully deleted /tmp/hello');
  26     });
  27
  28 Here is the synchronous version:
  29
  30     var fs = require('fs');
  31
  32     fs.unlinkSync('/tmp/hello')
  33     console.log('successfully deleted /tmp/hello');
  34
  35 With the asynchronous methods there is no guaranteed ordering. So the
  36 following is prone to error:
  37
  38     fs.rename('/tmp/hello', '/tmp/world', function (err) {
  39       if (err) throw err;
  40       console.log('renamed complete');
  41     });
  42     fs.stat('/tmp/world', function (err, stats) {
  43       if (err) throw err;
  44       console.log('stats: ' + JSON.stringify(stats));
  45     });
  46
  47 It could be that `fs.stat` is executed before `fs.rename`.
  48 The correct way to do this is to chain the callbacks.
  49
  50     fs.rename('/tmp/hello', '/tmp/world', function (err) {
  51       if (err) throw err;
  52       fs.stat('/tmp/world', function (err, stats) {
  53         if (err) throw err;
  54         console.log('stats: ' + JSON.stringify(stats));
  55       });
  56     });
  57
  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.
  61
  62 Relative path to filename can be used, remember however that this path will be
  63 relative to `process.cwd()`.
  64
  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:
  68
  69     $ cat script.js
  70     function bad() {
  71       require('fs').readFile('/');
  72     }
  73     bad();
  74
  75     $ env NODE_DEBUG=fs node script.js
  76     fs.js:66
  77             throw err;
  78                   ^
  79     Error: EISDIR, read
  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)
  85         <etc.>
  86
  87
  88 ## fs.rename(oldPath, newPath, callback)
  89
  90 Asynchronous rename(2). No arguments other than a possible exception are given
  91 to the completion callback.
  92
  93 ## fs.renameSync(oldPath, newPath)
  94
  95 Synchronous rename(2).
  96
  97 ## fs.ftruncate(fd, len, callback)
  98
  99 Asynchronous ftruncate(2). No arguments other than a possible exception are
 100 given to the completion callback.
 101
 102 ## fs.ftruncateSync(fd, len)
 103
 104 Synchronous ftruncate(2).
 105
 106 ## fs.truncate(path, len, callback)
 107
 108 Asynchronous truncate(2). No arguments other than a possible exception are
 109 given to the completion callback.
 110
 111 ## fs.truncateSync(path, len)
 112
 113 Synchronous truncate(2).
 114
 115 ## fs.chown(path, uid, gid, callback)
 116
 117 Asynchronous chown(2). No arguments other than a possible exception are given
 118 to the completion callback.
 119
 120 ## fs.chownSync(path, uid, gid)
 121
 122 Synchronous chown(2).
 123
 124 ## fs.fchown(fd, uid, gid, callback)
 125
 126 Asynchronous fchown(2). No arguments other than a possible exception are given
 127 to the completion callback.
 128
 129 ## fs.fchownSync(fd, uid, gid)
 130
 131 Synchronous fchown(2).
 132
 133 ## fs.lchown(path, uid, gid, callback)
 134
 135 Asynchronous lchown(2). No arguments other than a possible exception are given
 136 to the completion callback.
 137
 138 ## fs.lchownSync(path, uid, gid)
 139
 140 Synchronous lchown(2).
 141
 142 ## fs.chmod(path, mode, callback)
 143
 144 Asynchronous chmod(2). No arguments other than a possible exception are given
 145 to the completion callback.
 146
 147 ## fs.chmodSync(path, mode)
 148
 149 Synchronous chmod(2).
 150
 151 ## fs.fchmod(fd, mode, callback)
 152
 153 Asynchronous fchmod(2). No arguments other than a possible exception
 154 are given to the completion callback.
 155
 156 ## fs.fchmodSync(fd, mode)
 157
 158 Synchronous fchmod(2).
 159
 160 ## fs.lchmod(path, mode, callback)
 161
 162 Asynchronous lchmod(2). No arguments other than a possible exception
 163 are given to the completion callback.
 164
 165 Only available on Mac OS X.
 166
 167 ## fs.lchmodSync(path, mode)
 168
 169 Synchronous lchmod(2).
 170
 171 ## fs.stat(path, callback)
 172
 173 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
 174 `stats` is a [fs.Stats](#fs_class_fs_stats) object.  See the [fs.Stats](#fs_class_fs_stats)
 175 section below for more information.
 176
 177 ## fs.lstat(path, callback)
 178
 179 Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
 180 `stats` is a `fs.Stats` object. `lstat()` is identical to `stat()`, except that if
 181 `path` is a symbolic link, then the link itself is stat-ed, not the file that it
 182 refers to.
 183
 184 ## fs.fstat(fd, callback)
 185
 186 Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
 187 `stats` is a `fs.Stats` object. `fstat()` is identical to `stat()`, except that
 188 the file to be stat-ed is specified by the file descriptor `fd`.
 189
 190 ## fs.statSync(path)
 191
 192 Synchronous stat(2). Returns an instance of `fs.Stats`.
 193
 194 ## fs.lstatSync(path)
 195
 196 Synchronous lstat(2). Returns an instance of `fs.Stats`.
 197
 198 ## fs.fstatSync(fd)
 199
 200 Synchronous fstat(2). Returns an instance of `fs.Stats`.
 201
 202 ## fs.link(srcpath, dstpath, callback)
 203
 204 Asynchronous link(2). No arguments other than a possible exception are given to
 205 the completion callback.
 206
 207 ## fs.linkSync(srcpath, dstpath)
 208
 209 Synchronous link(2).
 210
 211 ## fs.symlink(srcpath, dstpath, [type], callback)
 212
 213 Asynchronous symlink(2). No arguments other than a possible exception are given
 214 to the completion callback.
 215 `type` argument can be either `'dir'`, `'file'`, or `'junction'` (default is `'file'`).  It is only
 216 used on Windows (ignored on other platforms).
 217 Note that Windows junction points require the destination path to be absolute.  When using
 218 `'junction'`, the `destination` argument will automatically be normalized to absolute path.
 219
 220 ## fs.symlinkSync(srcpath, dstpath, [type])
 221
 222 Synchronous symlink(2).
 223
 224 ## fs.readlink(path, callback)
 225
 226 Asynchronous readlink(2). The callback gets two arguments `(err,
 227 linkString)`.
 228
 229 ## fs.readlinkSync(path)
 230
 231 Synchronous readlink(2). Returns the symbolic link's string value.
 232
 233 ## fs.realpath(path, [cache], callback)
 234
 235 Asynchronous realpath(2). The `callback` gets two arguments `(err,
 236 resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an
 237 object literal of mapped paths that can be used to force a specific path
 238 resolution or avoid additional `fs.stat` calls for known real paths.
 239
 240 Example:
 241
 242     var cache = {'/etc':'/private/etc'};
 243     fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
 244       if (err) throw err;
 245       console.log(resolvedPath);
 246     });
 247
 248 ## fs.realpathSync(path, [cache])
 249
 250 Synchronous realpath(2). Returns the resolved path.
 251
 252 ## fs.unlink(path, callback)
 253
 254 Asynchronous unlink(2). No arguments other than a possible exception are given
 255 to the completion callback.
 256
 257 ## fs.unlinkSync(path)
 258
 259 Synchronous unlink(2).
 260
 261 ## fs.rmdir(path, callback)
 262
 263 Asynchronous rmdir(2). No arguments other than a possible exception are given
 264 to the completion callback.
 265
 266 ## fs.rmdirSync(path)
 267
 268 Synchronous rmdir(2).
 269
 270 ## fs.mkdir(path, [mode], callback)
 271
 272 Asynchronous mkdir(2). No arguments other than a possible exception are given
 273 to the completion callback. `mode` defaults to `0777`.
 274
 275 ## fs.mkdirSync(path, [mode])
 276
 277 Synchronous mkdir(2).
 278
 279 ## fs.readdir(path, callback)
 280
 281 Asynchronous readdir(3).  Reads the contents of a directory.
 282 The callback gets two arguments `(err, files)` where `files` is an array of
 283 the names of the files in the directory excluding `'.'` and `'..'`.
 284
 285 ## fs.readdirSync(path)
 286
 287 Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
 288 `'..'`.
 289
 290 ## fs.close(fd, callback)
 291
 292 Asynchronous close(2).  No arguments other than a possible exception are given
 293 to the completion callback.
 294
 295 ## fs.closeSync(fd)
 296
 297 Synchronous close(2).
 298
 299 ## fs.open(path, flags, [mode], callback)
 300
 301 Asynchronous file open. See open(2). `flags` can be:
 302
 303 * `'r'` - Open file for reading.
 304 An exception occurs if the file does not exist.
 305
 306 * `'r+'` - Open file for reading and writing.
 307 An exception occurs if the file does not exist.
 308
 309 * `'rs'` - Open file for reading in synchronous mode. Instructs the operating
 310   system to bypass the local file system cache.
 311
 312   This is primarily useful for opening files on NFS mounts as it allows you to
 313   skip the potentially stale local cache. It has a very real impact on I/O
 314   performance so don't use this mode unless you need it.
 315
 316   Note that this doesn't turn `fs.open()` into a synchronous blocking call.
 317   If that's what you want then you should be using `fs.openSync()`
 318
 319 * `'rs+'` - Open file for reading and writing, telling the OS to open it
 320   synchronously. See notes for `'rs'` about using this with caution.
 321
 322 * `'w'` - Open file for writing.
 323 The file is created (if it does not exist) or truncated (if it exists).
 324
 325 * `'wx'` - Like `'w'` but opens the file in exclusive mode.
 326
 327 * `'w+'` - Open file for reading and writing.
 328 The file is created (if it does not exist) or truncated (if it exists).
 329
 330 * `'wx+'` - Like `'w+'` but opens the file in exclusive mode.
 331
 332 * `'a'` - Open file for appending.
 333 The file is created if it does not exist.
 334
 335 * `'ax'` - Like `'a'` but opens the file in exclusive mode.
 336
 337 * `'a+'` - Open file for reading and appending.
 338 The file is created if it does not exist.
 339
 340 * `'ax+'` - Like `'a+'` but opens the file in exclusive mode.
 341
 342 `mode` defaults to `0666`. The callback gets two arguments `(err, fd)`.
 343
 344 Exclusive mode (`O_EXCL`) ensures that `path` is newly created. `fs.open()`
 345 fails if a file by that name already exists. On POSIX systems, symlinks are
 346 not followed. Exclusive mode may or may not work with network file systems.
 347
 348 ## fs.openSync(path, flags, [mode])
 349
 350 Synchronous open(2).
 351
 352 ## fs.utimes(path, atime, mtime, callback)
 353 ## fs.utimesSync(path, atime, mtime)
 354
 355 Change file timestamps of the file referenced by the supplied path.
 356
 357 ## fs.futimes(fd, atime, mtime, callback)
 358 ## fs.futimesSync(fd, atime, mtime)
 359
 360 Change the file timestamps of a file referenced by the supplied file
 361 descriptor.
 362
 363 ## fs.fsync(fd, callback)
 364
 365 Asynchronous fsync(2). No arguments other than a possible exception are given
 366 to the completion callback.
 367
 368 ## fs.fsyncSync(fd)
 369
 370 Synchronous fsync(2).
 371
 372 ## fs.write(fd, buffer, offset, length, position, callback)
 373
 374 Write `buffer` to the file specified by `fd`.
 375
 376 `offset` and `length` determine the part of the buffer to be written.
 377
 378 `position` refers to the offset from the beginning of the file where this data
 379 should be written. If `position` is `null`, the data will be written at the
 380 current position.
 381 See pwrite(2).
 382
 383 The callback will be given three arguments `(err, written, buffer)` where `written`
 384 specifies how many _bytes_ were written from `buffer`.
 385
 386 Note that it is unsafe to use `fs.write` multiple times on the same file
 387 without waiting for the callback. For this scenario,
 388 `fs.createWriteStream` is strongly recommended.
 389
 390 ## fs.writeSync(fd, buffer, offset, length, position)
 391
 392 Synchronous version of `fs.write()`. Returns the number of bytes written.
 393
 394 ## fs.read(fd, buffer, offset, length, position, callback)
 395
 396 Read data from the file specified by `fd`.
 397
 398 `buffer` is the buffer that the data will be written to.
 399
 400 `offset` is offset within the buffer where reading will start.
 401
 402 `length` is an integer specifying the number of bytes to read.
 403
 404 `position` is an integer specifying where to begin reading from in the file.
 405 If `position` is `null`, data will be read from the current file position.
 406
 407 The callback is given the three arguments, `(err, bytesRead, buffer)`.
 408
 409 ## fs.readSync(fd, buffer, offset, length, position)
 410
 411 Synchronous version of `fs.read`. Returns the number of `bytesRead`.
 412
 413 ## fs.readFile(filename, [options], callback)
 414
 415 * `filename` {String}
 416 * `options` {Object}
 417   * `encoding` {String | Null} default = `null`
 418   * `flag` {String} default = `'r'`
 419 * `callback` {Function}
 420
 421 Asynchronously reads the entire contents of a file. Example:
 422
 423     fs.readFile('/etc/passwd', function (err, data) {
 424       if (err) throw err;
 425       console.log(data);
 426     });
 427
 428 The callback is passed two arguments `(err, data)`, where `data` is the
 429 contents of the file.
 430
 431 If no encoding is specified, then the raw buffer is returned.
 432
 433
 434 ## fs.readFileSync(filename, [options])
 435
 436 Synchronous version of `fs.readFile`. Returns the contents of the `filename`.
 437
 438 If the `encoding` option is specified then this function returns a
 439 string. Otherwise it returns a buffer.
 440
 441
 442 ## fs.writeFile(filename, data, [options], callback)
 443
 444 * `filename` {String}
 445 * `data` {String | Buffer}
 446 * `options` {Object}
 447   * `encoding` {String | Null} default = `'utf8'`
 448   * `mode` {Number} default = `438` (aka `0666` in Octal)
 449   * `flag` {String} default = `'w'`
 450 * `callback` {Function}
 451
 452 Asynchronously writes data to a file, replacing the file if it already exists.
 453 `data` can be a string or a buffer.
 454
 455 The `encoding` option is ignored if `data` is a buffer. It defaults
 456 to `'utf8'`.
 457
 458 Example:
 459
 460     fs.writeFile('message.txt', 'Hello Node', function (err) {
 461       if (err) throw err;
 462       console.log('It\'s saved!');
 463     });
 464
 465 ## fs.writeFileSync(filename, data, [options])
 466
 467 The synchronous version of `fs.writeFile`.
 468
 469 ## fs.appendFile(filename, data, [options], callback)
 470
 471 * `filename` {String}
 472 * `data` {String | Buffer}
 473 * `options` {Object}
 474   * `encoding` {String | Null} default = `'utf8'`
 475   * `mode` {Number} default = `438` (aka `0666` in Octal)
 476   * `flag` {String} default = `'a'`
 477 * `callback` {Function}
 478
 479 Asynchronously append data to a file, creating the file if it not yet exists.
 480 `data` can be a string or a buffer.
 481
 482 Example:
 483
 484     fs.appendFile('message.txt', 'data to append', function (err) {
 485       if (err) throw err;
 486       console.log('The "data to append" was appended to file!');
 487     });
 488
 489 ## fs.appendFileSync(filename, data, [options])
 490
 491 The synchronous version of `fs.appendFile`.
 492
 493 ## fs.watchFile(filename, [options], listener)
 494
 495     Stability: 2 - Unstable.  Use fs.watch instead, if possible.
 496
 497 Watch for changes on `filename`. The callback `listener` will be called each
 498 time the file is accessed.
 499
 500 The second argument is optional. The `options` if provided should be an object
 501 containing two members a boolean, `persistent`, and `interval`. `persistent`
 502 indicates whether the process should continue to run as long as files are
 503 being watched. `interval` indicates how often the target should be polled,
 504 in milliseconds. The default is `{ persistent: true, interval: 5007 }`.
 505
 506 The `listener` gets two arguments the current stat object and the previous
 507 stat object:
 508
 509     fs.watchFile('message.text', function (curr, prev) {
 510       console.log('the current mtime is: ' + curr.mtime);
 511       console.log('the previous mtime was: ' + prev.mtime);
 512     });
 513
 514 These stat objects are instances of `fs.Stat`.
 515
 516 If you want to be notified when the file was modified, not just accessed
 517 you need to compare `curr.mtime` and `prev.mtime`.
 518
 519 ## fs.unwatchFile(filename, [listener])
 520
 521     Stability: 2 - Unstable.  Use fs.watch instead, if available.
 522
 523 Stop watching for changes on `filename`. If `listener` is specified, only that
 524 particular listener is removed. Otherwise, *all* listeners are removed and you
 525 have effectively stopped watching `filename`.
 526
 527 Calling `fs.unwatchFile()` with a filename that is not being watched is a
 528 no-op, not an error.
 529
 530 ## fs.watch(filename, [options], [listener])
 531
 532     Stability: 2 - Unstable.
 533
 534 Watch for changes on `filename`, where `filename` is either a file or a
 535 directory.  The returned object is a [fs.FSWatcher](#fs_class_fs_fswatcher).
 536
 537 The second argument is optional. The `options` if provided should be an object
 538 containing a boolean member `persistent`, which indicates whether the process
 539 should continue to run as long as files are being watched. The default is
 540 `{ persistent: true }`.
 541
 542 The listener callback gets two arguments `(event, filename)`.  `event` is either
 543 'rename' or 'change', and `filename` is the name of the file which triggered
 544 the event.
 545
 546 ### Caveats
 547
 548 <!--type=misc-->
 549
 550 The `fs.watch` API is not 100% consistent across platforms, and is
 551 unavailable in some situations.
 552
 553 #### Availability
 554
 555 <!--type=misc-->
 556
 557 This feature depends on the underlying operating system providing a way
 558 to be notified of filesystem changes.
 559
 560 * On Linux systems, this uses `inotify`.
 561 * On BSD systems (including OS X), this uses `kqueue`.
 562 * On SunOS systems (including Solaris and SmartOS), this uses `event ports`.
 563 * On Windows systems, this feature depends on `ReadDirectoryChangesW`.
 564
 565 If the underlying functionality is not available for some reason, then
 566 `fs.watch` will not be able to function.  For example, watching files or
 567 directories on network file systems (NFS, SMB, etc.) often doesn't work
 568 reliably or at all.
 569
 570 You can still use `fs.watchFile`, which uses stat polling, but it is slower and
 571 less reliable.
 572
 573 #### Filename Argument
 574
 575 <!--type=misc-->
 576
 577 Providing `filename` argument in the callback is not supported
 578 on every platform (currently it's only supported on Linux and Windows).  Even
 579 on supported platforms `filename` is not always guaranteed to be provided.
 580 Therefore, don't assume that `filename` argument is always provided in the
 581 callback, and have some fallback logic if it is null.
 582
 583     fs.watch('somedir', function (event, filename) {
 584       console.log('event is: ' + event);
 585       if (filename) {
 586         console.log('filename provided: ' + filename);
 587       } else {
 588         console.log('filename not provided');
 589       }
 590     });
 591
 592 ## fs.exists(path, callback)
 593
 594 Test whether or not the given path exists by checking with the file system.
 595 Then call the `callback` argument with either true or false.  Example:
 596
 597     fs.exists('/etc/passwd', function (exists) {
 598       util.debug(exists ? "it's there" : "no passwd!");
 599     });
 600
 601
 602 ## fs.existsSync(path)
 603
 604 Synchronous version of `fs.exists`.
 605
 606 ## Class: fs.Stats
 607
 608 Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their
 609 synchronous counterparts are of this type.
 610
 611  - `stats.isFile()`
 612  - `stats.isDirectory()`
 613  - `stats.isBlockDevice()`
 614  - `stats.isCharacterDevice()`
 615  - `stats.isSymbolicLink()` (only valid with  `fs.lstat()`)
 616  - `stats.isFIFO()`
 617  - `stats.isSocket()`
 618
 619 For a regular file `util.inspect(stats)` would return a string very
 620 similar to this:
 621
 622     { dev: 2114,
 623       ino: 48064969,
 624       mode: 33188,
 625       nlink: 1,
 626       uid: 85,
 627       gid: 100,
 628       rdev: 0,
 629       size: 527,
 630       blksize: 4096,
 631       blocks: 8,
 632       atime: Mon, 10 Oct 2011 23:24:11 GMT,
 633       mtime: Mon, 10 Oct 2011 23:24:11 GMT,
 634       ctime: Mon, 10 Oct 2011 23:24:11 GMT }
 635
 636 Please note that `atime`, `mtime` and `ctime` are instances
 637 of [Date][MDN-Date] object and to compare the values of
 638 these objects you should use appropriate methods. For most
 639 general uses [getTime()][MDN-Date-getTime] will return
 640 the number of milliseconds elapsed since _1 January 1970
 641 00:00:00 UTC_ and this integer should be sufficient for
 642 any comparison, however there additional methods which can
 643 be used for displaying fuzzy information. More details can
 644 be found in the [MDN JavaScript Reference][MDN-Date] page.
 645
 646 [MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
 647 [MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
 648
 649
 650 ## fs.createReadStream(path, [options])
 651
 652 Returns a new ReadStream object (See `Readable Stream`).
 653
 654 `options` is an object with the following defaults:
 655
 656     { flags: 'r',
 657       encoding: null,
 658       fd: null,
 659       mode: 0666,
 660       bufferSize: 64 * 1024,
 661       autoClose: true
 662     }
 663
 664 `options` can include `start` and `end` values to read a range of bytes from
 665 the file instead of the entire file.  Both `start` and `end` are inclusive and
 666 start at 0. The `encoding` can be `'utf8'`, `'ascii'`, or `'base64'`.
 667
 668 If `autoClose` is false, then the file descriptor won't be closed, even if
 669 there's an error.  It is your responsiblity to close it and make sure
 670 there's no file descriptor leak.  If `autoClose` is set to true (default
 671 behavior), on `error` or `end` the file descriptor will be closed
 672 automatically.
 673
 674 An example to read the last 10 bytes of a file which is 100 bytes long:
 675
 676     fs.createReadStream('sample.txt', {start: 90, end: 99});
 677
 678
 679 ## Class: fs.ReadStream
 680
 681 `ReadStream` is a [Readable Stream](stream.html#stream_readable_stream).
 682
 683 ### Event: 'open'
 684
 685 * `fd` {Integer} file descriptor used by the ReadStream.
 686
 687 Emitted when the ReadStream's file is opened.
 688
 689
 690 ## fs.createWriteStream(path, [options])
 691
 692 Returns a new WriteStream object (See `Writable Stream`).
 693
 694 `options` is an object with the following defaults:
 695
 696     { flags: 'w',
 697       encoding: null,
 698       mode: 0666 }
 699
 700 `options` may also include a `start` option to allow writing data at
 701 some position past the beginning of the file.  Modifying a file rather
 702 than replacing it may require a `flags` mode of `r+` rather than the
 703 default mode `w`.
 704
 705 ## fs.WriteStream
 706
 707 `WriteStream` is a [Writable Stream](stream.html#stream_writable_stream).
 708
 709 ### Event: 'open'
 710
 711 * `fd` {Integer} file descriptor used by the WriteStream.
 712
 713 Emitted when the WriteStream's file is opened.
 714
 715 ### file.bytesWritten
 716
 717 The number of bytes written so far. Does not include data that is still queued
 718 for writing.
 719
 720 ## Class: fs.FSWatcher
 721
 722 Objects returned from `fs.watch()` are of this type.
 723
 724 ### watcher.close()
 725
 726 Stop watching for changes on the given `fs.FSWatcher`.
 727
 728 ### Event: 'change'
 729
 730 * `event` {String} The type of fs change
 731 * `filename` {String} The filename that changed (if relevant/available)
 732
 733 Emitted when something changes in a watched directory or file.
 734 See more details in [fs.watch](#fs_fs_watch_filename_options_listener).
 735
 736 ### Event: 'error'
 737
 738 * `error` {Error object}
 739
 740 Emitted when an error occurs.