Skip to content

Commit 763fa85

Browse files
dfabulichMylesBorins
dfabulich
authored and
MylesBorins
committed
doc: bad/better examples for fs.access() and fs.exists()
PR-URL: #7832 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>
1 parent e64063c commit 763fa85

File tree

1 file changed

+164
-5
lines changed

1 file changed

+164
-5
lines changed

‎doc/api/fs.md‎

Lines changed: 164 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,93 @@ fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => {
300300
});
301301
```
302302

303+
Using `fs.access()` to check for the accessibility of a file before calling
304+
`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing
305+
so introduces a race condition, since other processes may change the file's
306+
state between the two calls. Instead, user code should open/read/write the
307+
file directly and handle the error raised if the file is not accessible.
308+
309+
For example:
310+
311+
312+
**write (NOT RECOMMENDED)**
313+
314+
```js
315+
fs.access('myfile', (err) => {
316+
if (!err) {
317+
console.error('myfile already exists');
318+
return;
319+
}
320+
321+
fs.open('myfile', 'wx', (err, fd) => {
322+
if (err) throw err;
323+
writeMyData(fd);
324+
});
325+
});
326+
```
327+
328+
**write (RECOMMENDED)**
329+
330+
```js
331+
fs.open('myfile', 'wx', (err, fd) => {
332+
if (err) {
333+
if (err.code === "EEXIST") {
334+
console.error('myfile already exists');
335+
return;
336+
} else {
337+
throw err;
338+
}
339+
}
340+
341+
writeMyData(fd);
342+
});
343+
```
344+
345+
**read (NOT RECOMMENDED)**
346+
347+
```js
348+
fs.access('myfile', (err) => {
349+
if (err) {
350+
if (err.code === "ENOENT") {
351+
console.error('myfile does not exist');
352+
return;
353+
} else {
354+
throw err;
355+
}
356+
}
357+
358+
fs.open('myfile', 'r', (err, fd) => {
359+
if (err) throw err;
360+
readMyData(fd);
361+
});
362+
});
363+
```
364+
365+
**read (RECOMMENDED)**
366+
367+
```js
368+
fs.open('myfile', 'r', (err, fd) => {
369+
if (err) {
370+
if (err.code === "ENOENT") {
371+
console.error('myfile does not exist');
372+
return;
373+
} else {
374+
throw err;
375+
}
376+
}
377+
378+
readMyData(fd);
379+
});
380+
```
381+
382+
The "not recommended" examples above check for accessibility and then use the
383+
file; the "recommended" examples are better because they use the file directly
384+
and handle the error, if any.
385+
386+
In general, check for the accessibility of a file only if the file won’t be
387+
used directly, for example when its accessibility is a signal from another
388+
process.
389+
303390
## fs.accessSync(path[, mode])
304391
<!-- YAML
305392
added: v0.11.15
@@ -487,11 +574,83 @@ fs.exists('/etc/passwd', (exists) => {
487574
});
488575
```
489576

490-
`fs.exists()` should not be used to check if a file exists before calling
491-
`fs.open()`. Doing so introduces a race condition since other processes may
492-
change the file's state between the two calls. Instead, user code should
493-
call `fs.open()` directly and handle the error raised if the file is
494-
non-existent.
577+
Using `fs.exists()` to check for the existence of a file before calling
578+
`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing
579+
so introduces a race condition, since other processes may change the file's
580+
state between the two calls. Instead, user code should open/read/write the
581+
file directly and handle the error raised if the file does not exist.
582+
583+
For example:
584+
585+
**write (NOT RECOMMENDED)**
586+
587+
```js
588+
fs.exists('myfile', (exists) => {
589+
if (exists) {
590+
console.error('myfile already exists');
591+
} else {
592+
fs.open('myfile', 'wx', (err, fd) => {
593+
if (err) throw err;
594+
writeMyData(fd);
595+
});
596+
}
597+
});
598+
```
599+
600+
**write (RECOMMENDED)**
601+
602+
```js
603+
fs.open('myfile', 'wx', (err, fd) => {
604+
if (err) {
605+
if (err.code === "EEXIST") {
606+
console.error('myfile already exists');
607+
return;
608+
} else {
609+
throw err;
610+
}
611+
}
612+
writeMyData(fd);
613+
});
614+
```
615+
616+
**read (NOT RECOMMENDED)**
617+
618+
```js
619+
fs.exists('myfile', (exists) => {
620+
if (exists) {
621+
fs.open('myfile', 'r', (err, fd) => {
622+
readMyData(fd);
623+
});
624+
} else {
625+
console.error('myfile does not exist');
626+
}
627+
});
628+
```
629+
630+
**read (RECOMMENDED)**
631+
632+
```js
633+
fs.open('myfile', 'r', (err, fd) => {
634+
if (err) {
635+
if (err.code === "ENOENT") {
636+
console.error('myfile does not exist');
637+
return;
638+
} else {
639+
throw err;
640+
}
641+
} else {
642+
readMyData(fd);
643+
}
644+
});
645+
```
646+
647+
The "not recommended" examples above check for existence and then use the
648+
file; the "recommended" examples are better because they use the file directly
649+
and handle the error, if any.
650+
651+
In general, check for the existence of a file only if the file won’t be
652+
used directly, for example when its existence is a signal from another
653+
process.
495654

496655
## fs.existsSync(path)
497656
<!-- YAML

0 commit comments

Comments
 (0)