1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: bad/better examples for fs.access() and fs.exists()

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/7832
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
This commit is contained in:
Dan Fabulich 2016-07-22 00:30:45 -07:00 committed by James M Snell
parent baa0ffdab3
commit 143d38c650
1 changed files with 164 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

169
doc/api/fs.md
View File

@ -347,6 +347,93 @@ fs.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK, (err) => {
});
```
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) {
if (err.code === "EEXIST") {
console.error('myfile already exists');
return;
} else {
throw err;
}
}
writeMyData(fd);
});
```
**read (NOT RECOMMENDED)**
```js
fs.access('myfile', (err) => {
if (err) {
if (err.code === "ENOENT") {
console.error('myfile does not exist');
return;
} else {
throw err;
}
}
fs.open('myfile', 'r', (err, fd) => {
if (err) throw err;
readMyData(fd);
});
});
```
**read (RECOMMENDED)**
```js
fs.open('myfile', 'r', (err, fd) => {
if (err) {
if (err.code === "ENOENT") {
console.error('myfile does not exist');
return;
} else {
throw err;
}
}
readMyData(fd);
});
```
The "not recommended" examples above check for accessibility and then use the
file; the "recommended" examples are better because they use the file directly
and handle the error, if any.
In general, check for the accessibility of a file only if the file won’t be
used directly, for example when its accessibility is a signal from another
process.
## fs.accessSync(path[, mode])
<!-- YAML
added: v0.11.15
@ -606,11 +693,83 @@ fs.exists('/etc/passwd', (exists) => {
});
```
`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.
Using `fs.exists()` to check for the existence 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 does not exist.
For example:
**write (NOT RECOMMENDED)**
```js
fs.exists('myfile', (exists) => {
if (exists) {
console.error('myfile already exists');
} else {
fs.open('myfile', 'wx', (err, fd) => {
if (err) throw err;
writeMyData(fd);
});
}
});
```
**write (RECOMMENDED)**
```js
fs.open('myfile', 'wx', (err, fd) => {
if (err) {
if (err.code === "EEXIST") {
console.error('myfile already exists');
return;
} else {
throw err;
}
}
writeMyData(fd);
});
```
**read (NOT RECOMMENDED)**
```js
fs.exists('myfile', (exists) => {
if (exists) {
fs.open('myfile', 'r', (err, fd) => {
readMyData(fd);
});
} else {
console.error('myfile does not exist');
}
});
```
**read (RECOMMENDED)**
```js
fs.open('myfile', 'r', (err, fd) => {
if (err) {
if (err.code === "ENOENT") {
console.error('myfile does not exist');
return;
} else {
throw err;
}
} else {
readMyData(fd);
}
});
```
The "not recommended" examples above check for existence and then use the
file; the "recommended" examples are better because they use the file directly
and handle the error, if any.
In general, check for the existence of a file only if the file won’t be
used directly, for example when its existence is a signal from another
process.
## fs.existsSync(path)
<!-- YAML