Skip to content

Commit

Permalink
doc: expand fs.access() mode parameter docs
Browse files Browse the repository at this point in the history
This commit expands the documentation for the mode parameter
passed to the fs.access() family of functions.

PR-URL: #41484
Refs: libuv/libuv#3410
Reviewed-By: Richard Lau
Reviewed-By: Luigi Pinca
Reviewed-By: Tobias Nießen
  • Loading branch information
cjihrig authored and danielleadams committed Feb 1, 2022
1 parent 9242c19 commit c914d95
Showing 1 changed file with 22 additions and 19 deletions.
41 changes: 22 additions & 19 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -689,9 +689,11 @@ added: v10.0.0
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. Check [File access constants][] for possible values
of `mode`. It is possible to create a mask consisting of the bitwise OR of
two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`).
checks to be performed. `mode` should be either the value `fs.constants.F_OK`
or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,
`fs.constants.W_OK`, and `fs.constants.X_OK` (e.g.
`fs.constants.W_OK | fs.constants.R_OK`). Check [File access constants][] for
possible values of `mode`.
If the accessibility check is successful, the promise is resolved with no
value. If any of the accessibility checks fail, the promise is rejected
Expand Down Expand Up @@ -1561,9 +1563,11 @@ changes:
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. Check [File access constants][] for possible values
of `mode`. It is possible to create a mask consisting of the bitwise OR of
two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`).
checks to be performed. `mode` should be either the value `fs.constants.F_OK`
or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,
`fs.constants.W_OK`, and `fs.constants.X_OK` (e.g.
`fs.constants.W_OK | fs.constants.R_OK`). Check [File access constants][] for
possible values of `mode`.
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
Expand All @@ -1590,14 +1594,9 @@ access(file, constants.W_OK, (err) => {
console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});
// Check if the file exists in the current directory, and if it is writable.
access(file, constants.F_OK | constants.W_OK, (err) => {
if (err) {
console.error(
`${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`);
} else {
console.log(`${file} exists, and it is writable`);
}
// Check if the file is readable and writable.
access(file, constants.R_OK | constants.W_OK, (err) => {
console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
});
```
Expand Down Expand Up @@ -4389,10 +4388,11 @@ changes:
Synchronously 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. Check [File access constants][] for
possible values of `mode`. It is possible to create a mask consisting of
the bitwise OR of two or more values
(e.g. `fs.constants.W_OK | fs.constants.R_OK`).
accessibility checks to be performed. `mode` should be either the value
`fs.constants.F_OK` or a mask consisting of the bitwise OR of any of
`fs.constants.R_OK`, `fs.constants.W_OK`, and `fs.constants.X_OK` (e.g.
`fs.constants.W_OK | fs.constants.R_OK`). Check [File access constants][] for
possible values of `mode`.
If any of the accessibility checks fail, an `Error` will be thrown. Otherwise,
the method will return `undefined`.
Expand Down Expand Up @@ -6502,7 +6502,8 @@ open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
##### File access constants
The following constants are meant for use with [`fs.access()`][].
The following constants are meant for use as the `mode` parameter passed to
[`fsPromises.access()`][], [`fs.access()`][], and [`fs.accessSync()`][].
<table>
<tr>
Expand Down Expand Up @@ -7181,6 +7182,7 @@ the file contents.
[`event ports`]: https://illumos.org/man/port_create
[`filehandle.writeFile()`]: #filehandlewritefiledata-options
[`fs.access()`]: #fsaccesspath-mode-callback
[`fs.accessSync()`]: #fsaccesssyncpath-mode
[`fs.chmod()`]: #fschmodpath-mode-callback
[`fs.chown()`]: #fschownpath-uid-gid-callback
[`fs.copyFile()`]: #fscopyfilesrc-dest-mode-callback
Expand Down Expand Up @@ -7215,6 +7217,7 @@ the file contents.
[`fs.write(fd, string...)`]: #fswritefd-string-position-encoding-callback
[`fs.writeFile()`]: #fswritefilefile-data-options-callback
[`fs.writev()`]: #fswritevfd-buffers-position-callback
[`fsPromises.access()`]: #fspromisesaccesspath-mode
[`fsPromises.open()`]: #fspromisesopenpath-flags-mode
[`fsPromises.opendir()`]: #fspromisesopendirpath-options
[`fsPromises.rm()`]: #fspromisesrmpath-options
Expand Down

0 comments on commit c914d95

Please sign in to comment.