<!--name=fs-->

File I/O is provided by simple wrappers around standard POSIX functions. To

use this module do `require('fs')`. All the methods have asynchronous and

The arguments passed to the completion callback depend on the method, but the

first argument is always reserved for an exception. If the operation was

completed successfully, then the first argument will be `null` or `undefined`.

Exceptions may be handled using `try`/`catch`, or they may be allowed to

bubble up.

Here is an example of the asynchronous version:

```js

const fs = require('fs');

fs.unlink('/tmp/hello', (err) => {

if (err) throw err;

console.log('successfully deleted /tmp/hello');

});

```

Here is the synchronous version:

```js

const fs = require('fs');

fs.unlinkSync('/tmp/hello');

console.log('successfully deleted /tmp/hello');

```

With the asynchronous methods there is no guaranteed ordering. So the

following is prone to error:

```js

fs.rename('/tmp/hello', '/tmp/world', (err) => {

if (err) throw err;

console.log('renamed complete');

});

fs.stat('/tmp/world', (err, stats) => {

if (err) throw err;

console.log(`stats: ${JSON.stringify(stats)}`);

});

```

It could be that `fs.stat` is executed before `fs.rename`.

The correct way to do this is to chain the callbacks.

```js

fs.rename('/tmp/hello', '/tmp/world', (err) => {

if (err) throw err;

fs.stat('/tmp/world', (err, stats) => {

if (err) throw err;

console.log(`stats: ${JSON.stringify(stats)}`);

});

});

```

In busy processes, the programmer is _strongly encouraged_ to use the

asynchronous versions of these calls. The synchronous versions will block

the entire process until they complete--halting all connections.

The relative path to a filename can be used. Remember, however, that this path

will be relative to `process.cwd()`.

While it is not recommended, most fs functions allow the callback argument to

be omitted, in which case a default callback is used that rethrows errors. To

get a trace to the original call site, set the `NODE_DEBUG` environment

variable:

*Note*: Omitting the callback function on asynchronous fs functions is

deprecated and may result in an error being thrown in the future.

$ cat script.js

function bad() {

require('fs').readFile('/');

}

bad();

$ env NODE_DEBUG=fs node script.js

fs.js:88

throw backtrace;

^

Error: EISDIR: illegal operation on a directory, read

<stack trace.>

*Note:* On Windows Node.js follows the concept of per-drive working directory.

This behavior can be observed when using a drive path without a backslash. For

example `fs.readdirSync('c:\\')` can potentially return a different result than

`fs.readdirSync('c:')`. For more information, see

[this MSDN page][MSDN-Rel-Path].

## WHATWG URL object support

<!-- YAML

added: v7.6.0

-->

> Stability: 1 - Experimental

For most `fs` module functions, the `path` or `filename` argument may be passed

as a WHATWG [`URL`][] object. Only [`URL`][] objects using the `file:` protocol

are supported.

```js

const fs = require('fs');

const { URL } = require('url');

const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

```

*Note*: `file:` URLs are always absolute paths.

Using WHATWG [`URL`][] objects might introduce platform-specific behaviors.

On Windows, `file:` URLs with a hostname convert to UNC paths, while `file:`

URLs with drive letters convert to local absolute paths. `file:` URLs without a

hostname nor a drive letter will result in a throw :

```js

// On Windows :

// - WHATWG file URLs with hostname convert to UNC path

// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file

fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - WHATWG file URLs with drive letters convert to absolute path

// file:///C:/tmp/hello => C:\tmp\hello

fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - WHATWG file URLs without hostname must have a drive letters

fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));

fs.readFileSync(new URL('file:///c/p/a/t/h/file'));

// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

```

*Note*: `file:` URLs with drive letters must use `:` as a separator just after

the drive letter. Using another separator will result in a throw.

On all other platforms, `file:` URLs with a hostname are unsupported and will

result in a throw:

```js

// On other platforms:

// - WHATWG file URLs with hostname are unsupported

// file://hostname/p/a/t/h/file => throw!

fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG file URLs convert to absolute path

// file:///tmp/hello => /tmp/hello

fs.readFileSync(new URL('file:///tmp/hello'));

```

A `file:` URL having encoded slash characters will result in a throw on all

platforms:

```js

// On Windows

fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));

fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));

/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded

\ or / characters */

// On POSIX

fs.readFileSync(new URL('file:///p/a/t/h/%2F'));

fs.readFileSync(new URL('file:///p/a/t/h/%2f'));

/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded

/ characters */

```

On Windows, `file:` URLs having encoded backslash will result in a throw:

```js

// On Windows

fs.readFileSync(new URL('file:///C:/path/%5C'));

fs.readFileSync(new URL('file:///C:/path/%5c'));

/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded

\ or / characters */

```

<!-- YAML

added: v6.0.0

-->

`fs` functions support passing and receiving paths as both strings

and Buffers. The latter is intended to make it possible to work with

filesystems that allow for non-UTF-8 filenames. For most typical

uses, working with paths as Buffers will be unnecessary, as the string

API converts to and from UTF-8 automatically.

non-UTF-8 encoded Buffers to `fs` functions will not work as expected.

<!-- YAML

added: v0.5.8

-->

Objects returned from [`fs.watch()`][] are of this type.

The `listener` callback provided to `fs.watch()` receives the returned FSWatcher's

`change` events.

The object itself emits these events:

<!-- YAML

added: v0.5.8

-->

The `filename` argument may not be provided depending on operating system

support. If `filename` is provided, it will be provided as a `Buffer` if

`filename` will be a string.

```js

if (filename)

console.log(filename);

// Prints: <Buffer ...>

});

```

<!-- YAML

added: v0.5.8

-->

<!-- YAML

added: v0.5.8

-->

<!-- YAML

added: v0.1.93

-->

<!-- YAML

added: v0.1.93

-->

Emitted when the `ReadStream`'s underlying file descriptor has been closed

using the `fs.close()` method.

<!-- YAML

added: v0.1.93

-->

Emitted when the ReadStream's file is opened.

### readStream.bytesRead

<!-- YAML

-->

The number of bytes read so far.

<!-- YAML

added: v0.1.93

-->

The path to the file the stream is reading from as specified in the first

argument to `fs.createReadStream()`. If `path` is passed as a string, then

`readStream.path` will be a string. If `path` is passed as a `Buffer`, then

`readStream.path` will be a `Buffer`.

<!-- YAML

added: v0.1.21

changes:

- version: REPLACEME

pr-url: https://github.com/nodejs/node/pull/13173

description: Added times as numbers.

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.isFIFO()`

- `stats.isSocket()`

dev: 2114,

ino: 48064969,

mode: 33188,

nlink: 1,

uid: 85,

gid: 100,

rdev: 0,

size: 527,

blksize: 4096,

blocks: 8,

atimeMs: 1318289051000.1,

mtimeMs: 1318289051000.1,

ctimeMs: 1318289051000.1,

birthtimeMs: 1318289051000.1,

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,

*Note*: `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` are [numbers][MDN-Number]

that hold the corresponding times in milliseconds. Their precision is platform

specific. `atime`, `mtime`, `ctime`, and `birthtime` are [`Date`][MDN-Date]

object alternate representations of the various times. The `Date` and number

values are not connected. Assigning a new number value, or mutating the `Date`

value, will not be reflected in the corresponding alternate representation.

(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`). Note that this

value may be greater than `atime` or `mtime` in this case. On Darwin

and other FreeBSD variants, also set if the `atime` is explicitly

set to an earlier value than the current `birthtime` using the

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.

<!-- YAML

added: v0.1.93

-->

<!-- YAML

added: v0.1.93

-->

Emitted when the `WriteStream`'s underlying file descriptor has been closed

using the `fs.close()` method.

<!-- YAML

added: v0.1.93

-->

Emitted when the WriteStream's file is opened.

<!-- YAML

added: v0.4.7

-->

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

for writing.

<!-- YAML

added: v0.1.93

-->

The path to the file the stream is writing to as specified in the first

argument to `fs.createWriteStream()`. If `path` is passed as a string, then

`writeStream.path` will be a string. If `path` is passed as a `Buffer`, then

`writeStream.path` will be a `Buffer`.

changes:

- version: v7.6.0

pr-url: https://github.com/nodejs/node/pull/10739

description: The `path` parameter can be a WHATWG `URL` object using `file:`

protocol. Support is currently still *experimental*.

* `callback` {Function}

Tests a user's permissions for the file or directory specified by `path`.

The `mode` argument 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.constants.R_OK` - `path` can be read by the calling process.

- `fs.constants.W_OK` - `path` can be written by the calling process.

- `fs.constants.X_OK` - `path` can be executed by the calling process. This has

no effect on Windows (will behave like `fs.constants.F_OK`).

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.

console.log(err ? 'no access!' : 'can read/write');

});

```

Using `fs.access()` to check for the accessibility of a file before calling

`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing

so introduces a race condition, since other processes may change the file's

state between the two calls. Instead, user code should open/read/write the

file directly and handle the error raised if the file is not accessible.

For example:

**write (NOT RECOMMENDED)**

```js

fs.access('myfile', (err) => {

if (!err) {

console.error('myfile already exists');

return;

}

fs.open('myfile', 'wx', (err, fd) => {

if (err) throw err;

writeMyData(fd);

});

});

```

**write (RECOMMENDED)**

```js

fs.open('myfile', 'wx', (err, fd) => {

if (err) {

console.error('myfile already exists');

return;

}

throw err;

}

writeMyData(fd);

});

```

**read (NOT RECOMMENDED)**

```js

fs.access('myfile', (err) => {

if (err) {