Skip to content

Commit dcccbfd

Browse files
jasnelljasnell
committed
src: refactor require('constants')
The require('constants') module is currently undocumented and mashes together unrelated constants. This refactors the require('constants') in favor of distinct os.constants, fs.constants, and crypto.constants that are specific to the modules for which they are relevant. The next step is to document those within the specific modules. PR-URL: #6534 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Robert Lindstaedt <[email protected]>
1 parent f856234 commit dcccbfd

29 files changed

+1485
-117
lines changed

‎doc/api/crypto.md

Lines changed: 349 additions & 32 deletions
Large diffs are not rendered by default.

‎doc/api/fs.md

Lines changed: 252 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -266,21 +266,21 @@ optional integer that specifies the accessibility checks to be performed. The
266266
following constants define the possible values of `mode`. It is possible to
267267
create a mask consisting of the bitwise OR of two or more values.
268268

269-
- `fs.F_OK` - File is visible to the calling process. This is useful for
270-
determining if a file exists, but says nothing about `rwx` permissions.
269+
- `fs.constants.F_OK` - File is visible to the calling process. This is useful
270+
for determining if a file exists, but says nothing about `rwx` permissions.
271271
Default if no `mode` is specified.
272-
- `fs.R_OK` - File can be read by the calling process.
273-
- `fs.W_OK` - File can be written by the calling process.
274-
- `fs.X_OK` - File can be executed by the calling process. This has no effect
275-
on Windows (will behave like `fs.F_OK`).
272+
- `fs.constants.R_OK` - File can be read by the calling process.
273+
- `fs.constants.W_OK` - File can be written by the calling process.
274+
- `fs.constants.X_OK` - File can be executed by the calling process. This has no
275+
effect on Windows (will behave like `fs.constants.F_OK`).
276276

277277
The final argument, `callback`, is a callback function that is invoked with
278278
a possible error argument. If any of the accessibility checks fail, the error
279279
argument will be populated. The following example checks if the file
280280
`/etc/passwd` can be read and written by the current process.
281281

282282
```js
283-
fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => {
283+
fs.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK, (err) => {
284284
console.log(err ? 'no access!' : 'can read/write');
285285
});
286286
```
@@ -290,8 +290,8 @@ fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => {
290290
* `path` {String | Buffer}
291291
* `mode` {Integer}
292292

293-
Synchronous version of [`fs.access()`][]. This throws if any accessibility checks
294-
fail, and does nothing otherwise.
293+
Synchronous version of [`fs.access()`][]. This throws if any accessibility
294+
checks fail, and does nothing otherwise.
295295

296296
## fs.appendFile(file, data[, options], callback)
297297

@@ -384,6 +384,12 @@ to the completion callback.
384384

385385
Synchronous close(2). Returns `undefined`.
386386

387+
## fs.constants
388+
389+
Returns an object containing commonly used constants for file system
390+
operations. The specific constants currently defined are described in
391+
[FS Constants][].
392+
387393
## fs.createReadStream(path[, options])
388394

389395
* `path` {String | Buffer}
@@ -419,9 +425,9 @@ the file instead of the entire file. Both `start` and `end` are inclusive and
419425
start at 0. The `encoding` can be any one of those accepted by [`Buffer`][].
420426

421427
If `fd` is specified, `ReadStream` will ignore the `path` argument and will use
422-
the specified file descriptor. This means that no `'open'` event will be emitted.
423-
Note that `fd` should be blocking; non-blocking `fd`s should be passed to
424-
[`net.Socket`][].
428+
the specified file descriptor. This means that no `'open'` event will be
429+
emitted. Note that `fd` should be blocking; non-blocking `fd`s should be passed
430+
to [`net.Socket`][].
425431

426432
If `autoClose` is false, then the file descriptor won't be closed, even if
427433
there's an error. It is your responsibility to close it and make sure
@@ -468,7 +474,8 @@ Returns a new [`WriteStream`][] object. (See [Writable Stream][]).
468474
`options` may also include a `start` option to allow writing data at
469475
some position past the beginning of the file. Modifying a file rather
470476
than replacing it may require a `flags` mode of `r+` rather than the
471-
default mode `w`. The `defaultEncoding` can be any one of those accepted by [`Buffer`][].
477+
default mode `w`. The `defaultEncoding` can be any one of those accepted by
478+
[`Buffer`][].
472479

473480
If `autoClose` is set to true (default behavior) on `error` or `end`
474481
the file descriptor will be closed automatically. If `autoClose` is false,
@@ -507,7 +514,8 @@ non-existent.
507514

508515
## fs.existsSync(path)
509516

510-
Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] instead.
517+
Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][]
518+
instead.
511519

512520
* `path` {String | Buffer}
513521

@@ -789,7 +797,7 @@ to a non-existent file. The exclusive flag may or may not work with network file
789797
systems.
790798

791799
`flags` can also be a number as documented by open(2); commonly used constants
792-
are available from `require('constants')`. On Windows, flags are translated to
800+
are available from `fs.constants`. On Windows, flags are translated to
793801
their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
794802
or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW.
795803

@@ -1038,11 +1046,11 @@ Synchronous stat(2). Returns an instance of [`fs.Stats`][].
10381046
* `callback` {Function}
10391047

10401048
Asynchronous symlink(2). No arguments other than a possible exception are given
1041-
to the completion callback.
1042-
The `type` argument can be set to `'dir'`, `'file'`, or `'junction'` (default
1043-
is `'file'`) and is only available on Windows (ignored on other platforms).
1044-
Note that Windows junction points require the destination path to be absolute. When using
1045-
`'junction'`, the `target` argument will automatically be normalized to absolute path.
1049+
to the completion callback. The `type` argument can be set to `'dir'`,
1050+
`'file'`, or `'junction'` (default is `'file'`) and is only available on
1051+
Windows (ignored on other platforms). Note that Windows junction points require
1052+
the destination path to be absolute. When using `'junction'`, the `target`
1053+
argument will automatically be normalized to absolute path.
10461054

10471055
Here is an example below:
10481056

@@ -1255,9 +1263,9 @@ _Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will
12551263
of zero. If the file is created later on, the listener will be called again,
12561264
with the latest stat objects. This is a change in functionality since v0.10._
12571265

1258-
_Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and `fs.unwatchFile`.
1259-
`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`
1260-
when possible._
1266+
_Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and
1267+
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
1268+
`fs.unwatchFile` when possible._
12611269

12621270
## fs.write(fd, buffer, offset, length[, position], callback)
12631271

@@ -1387,6 +1395,226 @@ The synchronous version of [`fs.writeFile()`][]. Returns `undefined`.
13871395

13881396
Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.
13891397

1398+
## FS Constants
1399+
1400+
The following constants are exported by `fs.constants`. **Note:** Not every
1401+
constant will be available on every operating system.
1402+
1403+
### File Access Constants
1404+
1405+
The following constants are meant for use with [`fs.access()`][].
1406+
1407+
<table>
1408+
<tr>
1409+
<th>Constant</th>
1410+
<th>Description</th>
1411+
</tr>
1412+
<tr>
1413+
<td><code>F_OK</code></td>
1414+
<td>Flag indicating that the file is visible to the calling process.</td>
1415+
</tr>
1416+
<tr>
1417+
<td><code>R_OK</code></td>
1418+
<td>Flag indicating that the file can be read by the calling process.</td>
1419+
</tr>
1420+
<tr>
1421+
<td><code>W_OK</code></td>
1422+
<td>Flag indicating that the file can be written by the calling
1423+
process.</td>
1424+
</tr>
1425+
<tr>
1426+
<td><code>X_OK</code></td>
1427+
<td>Flag indicating that the file can be executed by the calling
1428+
process.</td>
1429+
</tr>
1430+
</table>
1431+
1432+
### File Open Constants
1433+
1434+
The following constants are meant for use with `fs.open()`.
1435+
1436+
<table>
1437+
<tr>
1438+
<th>Constant</th>
1439+
<th>Description</th>
1440+
</tr>
1441+
<tr>
1442+
<td><code>O_RDONLY</code></td>
1443+
<td>Flag indicating to open a file for read-only access.</td>
1444+
</tr>
1445+
<tr>
1446+
<td><code>O_WRONLY</code></td>
1447+
<td>Flag indicating to open a file for write-only access.</td>
1448+
</tr>
1449+
<tr>
1450+
<td><code>O_RDWR</code></td>
1451+
<td>Flag indicating to open a file for read-write access.</td>
1452+
</tr>
1453+
<tr>
1454+
<td><code>O_CREAT</code></td>
1455+
<td>Flag indicating to create the file if it does not already exist.</td>
1456+
</tr>
1457+
<tr>
1458+
<td><code>O_EXCL</code></td>
1459+
<td>Flag indicating that opening a file should fail if the
1460+
<code>O_CREAT</code> flag is set and the file already exists.</td>
1461+
</tr>
1462+
<tr>
1463+
<td><code>O_NOCTTY</code></td>
1464+
<td>Flag indicating that if path identifies a terminal device, opening the
1465+
path shall not cause that terminal to become the controlling terminal for
1466+
the process (if the process does not already have one).</td>
1467+
</tr>
1468+
<tr>
1469+
<td><code>O_TRUNC</code></td>
1470+
<td>Flag indicating that if the file exists and is a regular file, and the
1471+
file is opened successfully for write access, its length shall be truncated
1472+
to zero.</td>
1473+
</tr>
1474+
<tr>
1475+
<td><code>O_APPEND</code></td>
1476+
<td>Flag indicating that data will be appended to the end of the file.</td>
1477+
</tr>
1478+
<tr>
1479+
<td><code>O_DIRECTORY</code></td>
1480+
<td>Flag indicating that the open should fail if the path is not a
1481+
directory.</td>
1482+
</tr>
1483+
<tr>
1484+
<td><code>O_NOATIME</code></td>
1485+
<td>Flag indicating reading accesses to the file system will no longer
1486+
result in an update to the `atime` information associated with the file.
1487+
This flag is available on Linux operating systems only.</td>
1488+
</tr>
1489+
<tr>
1490+
<td><code>O_NOFOLLOW</code></td>
1491+
<td>Flag indicating that the open should fail if the path is a symbolic
1492+
link.</td>
1493+
</tr>
1494+
<tr>
1495+
<td><code>O_SYNC</code></td>
1496+
<td>Flag indicating that the file is opened for synchronous I/O.</td>
1497+
</tr>
1498+
<tr>
1499+
<td><code>O_SYMLINK</code></td>
1500+
<td>Flag indicating to open the symbolic link itself rather than the
1501+
resource it is pointing to.</td>
1502+
</tr>
1503+
<tr>
1504+
<td><code>O_DIRECT</code></td>
1505+
<td>When set, an attempt will be made to minimize caching effects of file
1506+
I/O.</td>
1507+
</tr>
1508+
<tr>
1509+
<td><code>O_NONBLOCK</code></td>
1510+
<td>Flag indicating to open the file in nonblocking mode when possible.</td>
1511+
</tr>
1512+
</table>
1513+
1514+
### File Type Constants
1515+
1516+
The following constants are meant for use with the [`fs.Stats`][] object's
1517+
`mode` property for determining a file's type.
1518+
1519+
<table>
1520+
<tr>
1521+
<th>Constant</th>
1522+
<th>Description</th>
1523+
</tr>
1524+
<tr>
1525+
<td><code>S_IFMT</code></td>
1526+
<td>Bit mask used to extract the file type code.</td>
1527+
</tr>
1528+
<tr>
1529+
<td><code>S_IFREG</code></td>
1530+
<td>File type constant for a regular file.</td>
1531+
</tr>
1532+
<tr>
1533+
<td><code>S_IFDIR</code></td>
1534+
<td>File type constant for a directory.</td>
1535+
</tr>
1536+
<tr>
1537+
<td><code>S_IFCHR</code></td>
1538+
<td>File type constant for a character-oriented device file.</td>
1539+
</tr>
1540+
<tr>
1541+
<td><code>S_IFBLK</code></td>
1542+
<td>File type constant for a block-oriented device file.</td>
1543+
</tr>
1544+
<tr>
1545+
<td><code>S_IFIFO</code></td>
1546+
<td>File type constant for a FIFO/pipe.</td>
1547+
</tr>
1548+
<tr>
1549+
<td><code>S_IFLNK</code></td>
1550+
<td>File type constant for a symbolic link.</td>
1551+
</tr>
1552+
<tr>
1553+
<td><code>S_IFSOCK</code></td>
1554+
<td>File type constant for a socket.</td>
1555+
</tr>
1556+
</table>
1557+
1558+
### File Mode Constants
1559+
1560+
The following constants are meant for use with the [`fs.Stats`][] object's
1561+
`mode` property for determining the access permissions for a file.
1562+
1563+
<table>
1564+
<tr>
1565+
<th>Constant</th>
1566+
<th>Description</th>
1567+
</tr>
1568+
<tr>
1569+
<td><code>S_IRWXU</code></td>
1570+
<td>File mode indicating readable, writable and executable by owner.</td>
1571+
</tr>
1572+
<tr>
1573+
<td><code>S_IRUSR</code></td>
1574+
<td>File mode indicating readable by owner.</td>
1575+
</tr>
1576+
<tr>
1577+
<td><code>S_IWUSR</code></td>
1578+
<td>File mode indicating writable by owner.</td>
1579+
</tr>
1580+
<tr>
1581+
<td><code>S_IXUSR</code></td>
1582+
<td>File mode indicating executable by owner.</td>
1583+
</tr>
1584+
<tr>
1585+
<td><code>S_IRWXG</code></td>
1586+
<td>File mode indicating readable, writable and executable by group.</td>
1587+
</tr>
1588+
<tr>
1589+
<td><code>S_IRGRP</code></td>
1590+
<td>File mode indicating readable by group.</td>
1591+
</tr>
1592+
<tr>
1593+
<td><code>S_IWGRP</code></td>
1594+
<td>File mode indicating writable by group.</td>
1595+
</tr>
1596+
<tr>
1597+
<td><code>S_IXGRP</code></td>
1598+
<td>File mode indicating executable by group.</td>
1599+
</tr>
1600+
<tr>
1601+
<td><code>S_IRWXO</code></td>
1602+
<td>File mode indicating readable, writable and executable by others.</td>
1603+
</tr>
1604+
<tr>
1605+
<td><code>S_IROTH</code></td>
1606+
<td>File mode indicating readable by others.</td>
1607+
</tr>
1608+
<tr>
1609+
<td><code>S_IWOTH</code></td>
1610+
<td>File mode indicating writable by others.</td>
1611+
</tr>
1612+
<tr>
1613+
<td><code>S_IXOTH</code></td>
1614+
<td>File mode indicating executable by others.</td>
1615+
</tr>
1616+
</table>
1617+
13901618
[`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
13911619
[`Buffer`]: buffer.html#buffer_buffer
13921620
[Caveats]: #fs_caveats
@@ -1418,3 +1646,4 @@ Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.
14181646
[Readable Stream]: stream.html#stream_class_stream_readable
14191647
[Writable Stream]: stream.html#stream_class_stream_writable
14201648
[inode]: http://www.linux.org/threads/intro-to-inodes.4130
1649+
[FS Constants]: #fs_fs_constants

0 commit comments

Comments
 (0)