Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

test,doc: improve fs.access() mode docs and test #41484

Merged
merged 2 commits into from Jan 14, 2022
Merged

test,doc: improve fs.access() mode docs and test #41484

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e54f52f
test: do not OR F_OK in fs.access() test
cjihrig Jan 11, 2022
91b9052
doc: expand fs.access() mode parameter docs
cjihrig Jan 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
41 changes: 22 additions & 19 deletions doc/api/fs.md
View file
Open in desktop
Expand Up @@ -738,9 +738,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 @@ -1616,9 +1618,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 @@ -1645,14 +1649,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 @@ -4459,10 +4458,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 @@ -6579,7 +6579,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 @@ -7258,6 +7259,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 @@ -7292,6 +7294,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
6 changes: 3 additions & 3 deletions test/parallel/test-fs-access.js
View file
Open in desktop
Expand Up @@ -82,10 +82,10 @@ fs.access(__filename, fs.R_OK, common.mustCall(function(...args) {
fs.promises.access(__filename, fs.R_OK)
.then(common.mustCall())
.catch(throwNextTick);
fs.access(readOnlyFile, fs.F_OK | fs.R_OK, common.mustCall(function(...args) {
fs.access(readOnlyFile, fs.R_OK, common.mustCall(function(...args) {
assert.deepStrictEqual(args, [null]);
}));
fs.promises.access(readOnlyFile, fs.F_OK | fs.R_OK)
fs.promises.access(readOnlyFile, fs.R_OK)
.then(common.mustCall())
.catch(throwNextTick);

Expand Down Expand Up @@ -153,7 +153,7 @@ assert.throws(

// Regular access should not throw.
fs.accessSync(__filename);
const mode = fs.F_OK | fs.R_OK | fs.W_OK;
const mode = fs.R_OK | fs.W_OK;
fs.accessSync(readWriteFile, mode);

// Invalid modes should throw.
Expand Down