From b2c8ecb5b586afee468c785c8afb8f8373b95b26 Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Thu, 2 Jun 2016 13:39:39 -0400 Subject: [PATCH 1/2] doc: clarify fs.access works on directories too. Cherry picked from d976d66cfc3159e0405ab66dcac3cb14fba2c5da --- doc/api/fs.md | 243 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 232 insertions(+), 11 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 6648974b261476..b7de6c8edf909a 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -309,18 +309,19 @@ added: v1.0.0 * `mode` {Integer} * `callback` {Function} -Tests a user's permissions for the file specified by `path`. `mode` 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.F_OK` - File is visible to the calling process. This is useful for -determining if a file exists, but says nothing about `rwx` permissions. +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.F_OK` - `path` is visible to the calling process. This is useful +for determining if a file exists, but says nothing about `rwx` permissions. Default if no `mode` is specified. -- `fs.R_OK` - File can be read by the calling process. -- `fs.W_OK` - File can be written by the calling process. -- `fs.X_OK` - File can be executed by the calling process. This has no effect -on Windows (will behave like `fs.F_OK`). +- `fs.R_OK` - `path` can be read by the calling process. +- `fs.W_OK` - `path` can be written by the calling process. +- `fs.X_OK` - `path` can be executed by the calling process. This has +no effect on Windows (will behave like `fs.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 @@ -1692,6 +1693,226 @@ added: v0.11.5 Synchronous versions of [`fs.write()`][]. Returns the number of bytes written. +## FS Constants + +The following constants are exported by `fs.constants`. **Note:** Not every +constant will be available on every operating system. + +### File Access Constants + +The following constants are meant for use with [`fs.access()`][]. + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
F_OKFlag indicating that the file is visible to the calling process.
R_OKFlag indicating that the file can be read by the calling process.
W_OKFlag indicating that the file can be written by the calling + process.
X_OKFlag indicating that the file can be executed by the calling + process.
+ +### File Open Constants + +The following constants are meant for use with `fs.open()`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
O_RDONLYFlag indicating to open a file for read-only access.
O_WRONLYFlag indicating to open a file for write-only access.
O_RDWRFlag indicating to open a file for read-write access.
O_CREATFlag indicating to create the file if it does not already exist.
O_EXCLFlag indicating that opening a file should fail if the + O_CREAT flag is set and the file already exists.
O_NOCTTYFlag indicating that if path identifies a terminal device, opening the + path shall not cause that terminal to become the controlling terminal for + the process (if the process does not already have one).
O_TRUNCFlag indicating that if the file exists and is a regular file, and the + file is opened successfully for write access, its length shall be truncated + to zero.
O_APPENDFlag indicating that data will be appended to the end of the file.
O_DIRECTORYFlag indicating that the open should fail if the path is not a + directory.
O_NOATIMEFlag indicating reading accesses to the file system will no longer + result in an update to the `atime` information associated with the file. + This flag is available on Linux operating systems only.
O_NOFOLLOWFlag indicating that the open should fail if the path is a symbolic + link.
O_SYNCFlag indicating that the file is opened for synchronous I/O.
O_SYMLINKFlag indicating to open the symbolic link itself rather than the + resource it is pointing to.
O_DIRECTWhen set, an attempt will be made to minimize caching effects of file + I/O.
O_NONBLOCKFlag indicating to open the file in nonblocking mode when possible.
+ +### File Type Constants + +The following constants are meant for use with the [`fs.Stats`][] object's +`mode` property for determining a file's type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
S_IFMTBit mask used to extract the file type code.
S_IFREGFile type constant for a regular file.
S_IFDIRFile type constant for a directory.
S_IFCHRFile type constant for a character-oriented device file.
S_IFBLKFile type constant for a block-oriented device file.
S_IFIFOFile type constant for a FIFO/pipe.
S_IFLNKFile type constant for a symbolic link.
S_IFSOCKFile type constant for a socket.
+ +### File Mode Constants + +The following constants are meant for use with the [`fs.Stats`][] object's +`mode` property for determining the access permissions for a file. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstantDescription
S_IRWXUFile mode indicating readable, writable and executable by owner.
S_IRUSRFile mode indicating readable by owner.
S_IWUSRFile mode indicating writable by owner.
S_IXUSRFile mode indicating executable by owner.
S_IRWXGFile mode indicating readable, writable and executable by group.
S_IRGRPFile mode indicating readable by group.
S_IWGRPFile mode indicating writable by group.
S_IXGRPFile mode indicating executable by group.
S_IRWXOFile mode indicating readable, writable and executable by others.
S_IROTHFile mode indicating readable by others.
S_IWOTHFile mode indicating writable by others.
S_IXOTHFile mode indicating executable by others.
+ [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding [`Buffer`]: buffer.html#buffer_buffer [Caveats]: #fs_caveats From cd2ae828825df3cbe8069ecda97b4a3a54562d7f Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Mon, 20 Jun 2016 12:10:01 -0400 Subject: [PATCH 2/2] doc: Remove FS Constants the docs for v6x. These changes should not have been carried over from master. --- doc/api/fs.md | 220 -------------------------------------------------- 1 file changed, 220 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index b7de6c8edf909a..a25e59b6c3aeb9 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1693,226 +1693,6 @@ added: v0.11.5 Synchronous versions of [`fs.write()`][]. Returns the number of bytes written. -## FS Constants - -The following constants are exported by `fs.constants`. **Note:** Not every -constant will be available on every operating system. - -### File Access Constants - -The following constants are meant for use with [`fs.access()`][]. - - - - - - - - - - - - - - - - - - - - - - -
ConstantDescription
F_OKFlag indicating that the file is visible to the calling process.
R_OKFlag indicating that the file can be read by the calling process.
W_OKFlag indicating that the file can be written by the calling - process.
X_OKFlag indicating that the file can be executed by the calling - process.
- -### File Open Constants - -The following constants are meant for use with `fs.open()`. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConstantDescription
O_RDONLYFlag indicating to open a file for read-only access.
O_WRONLYFlag indicating to open a file for write-only access.
O_RDWRFlag indicating to open a file for read-write access.
O_CREATFlag indicating to create the file if it does not already exist.
O_EXCLFlag indicating that opening a file should fail if the - O_CREAT flag is set and the file already exists.
O_NOCTTYFlag indicating that if path identifies a terminal device, opening the - path shall not cause that terminal to become the controlling terminal for - the process (if the process does not already have one).
O_TRUNCFlag indicating that if the file exists and is a regular file, and the - file is opened successfully for write access, its length shall be truncated - to zero.
O_APPENDFlag indicating that data will be appended to the end of the file.
O_DIRECTORYFlag indicating that the open should fail if the path is not a - directory.
O_NOATIMEFlag indicating reading accesses to the file system will no longer - result in an update to the `atime` information associated with the file. - This flag is available on Linux operating systems only.
O_NOFOLLOWFlag indicating that the open should fail if the path is a symbolic - link.
O_SYNCFlag indicating that the file is opened for synchronous I/O.
O_SYMLINKFlag indicating to open the symbolic link itself rather than the - resource it is pointing to.
O_DIRECTWhen set, an attempt will be made to minimize caching effects of file - I/O.
O_NONBLOCKFlag indicating to open the file in nonblocking mode when possible.
- -### File Type Constants - -The following constants are meant for use with the [`fs.Stats`][] object's -`mode` property for determining a file's type. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConstantDescription
S_IFMTBit mask used to extract the file type code.
S_IFREGFile type constant for a regular file.
S_IFDIRFile type constant for a directory.
S_IFCHRFile type constant for a character-oriented device file.
S_IFBLKFile type constant for a block-oriented device file.
S_IFIFOFile type constant for a FIFO/pipe.
S_IFLNKFile type constant for a symbolic link.
S_IFSOCKFile type constant for a socket.
- -### File Mode Constants - -The following constants are meant for use with the [`fs.Stats`][] object's -`mode` property for determining the access permissions for a file. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConstantDescription
S_IRWXUFile mode indicating readable, writable and executable by owner.
S_IRUSRFile mode indicating readable by owner.
S_IWUSRFile mode indicating writable by owner.
S_IXUSRFile mode indicating executable by owner.
S_IRWXGFile mode indicating readable, writable and executable by group.
S_IRGRPFile mode indicating readable by group.
S_IWGRPFile mode indicating writable by group.
S_IXGRPFile mode indicating executable by group.
S_IRWXOFile mode indicating readable, writable and executable by others.
S_IROTHFile mode indicating readable by others.
S_IWOTHFile mode indicating writable by others.
S_IXOTHFile mode indicating executable by others.
- [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding [`Buffer`]: buffer.html#buffer_buffer [Caveats]: #fs_caveats