Skip to content

Commit 73a8a0e

Browse files
LiviaMedeirosLiviaMedeiros
authored
doc: clarify some default values in fs.md
PR-URL: nodejs#42892 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Akhil Marsonya <akhil.marsonya27@gmail.com>
1 parent 0fc455a commit 73a8a0e

File tree

2 files changed

+43
-43
lines changed

2 files changed

+43
-43
lines changed

‎doc/api/fs.md

+33-33
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,7 @@ added: v10.0.0
374374
file data read.
375375
* `offset` {integer} The location in the buffer at which to start filling.
376376
* `length` {integer} The number of bytes to read.
377-
* `position` {integer} The location where to begin reading data from the
377+
* `position` {integer|null} The location where to begin reading data from the
378378
file. If `null`, data will be read from the current file position, and
379379
the position will be updated. If `position` is an integer, the current
380380
file position will remain unchanged.
@@ -403,7 +403,7 @@ added:
403403
**Default:** `0`
404404
* `length` {integer} The number of bytes to read. **Default:**
405405
`buffer.byteLength - offset`
406-
* `position` {integer} The location where to begin reading data from the
406+
* `position` {integer|null} The location where to begin reading data from the
407407
file. If `null`, data will be read from the current file position, and
408408
the position will be updated. If `position` is an integer, the current
409409
file position will remain unchanged. **Default:**: `null`
@@ -497,9 +497,9 @@ added:
497497
-->
498498
499499
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
500-
* `position` {integer} The offset from the beginning of the file where the data
501-
should be read from. If `position` is not a `number`, the data will be read
502-
from the current position.
500+
* `position` {integer|null} The offset from the beginning of the file where
501+
the data should be read from. If `position` is not a `number`, the data will
502+
be read from the current position. **Default:** `null`
503503
* Returns: {Promise} Fulfills upon success an object containing two properties:
504504
* `bytesRead` {integer} the number of bytes read
505505
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} property containing
@@ -597,10 +597,10 @@ changes:
597597
to write begins. **Default:** `0`
598598
* `length` {integer} The number of bytes from `buffer` to write. **Default:**
599599
`buffer.byteLength - offset`
600-
* `position` {integer} The offset from the beginning of the file where the
600+
* `position` {integer|null} The offset from the beginning of the file where the
601601
data from `buffer` should be written. If `position` is not a `number`,
602602
the data will be written at the current position. See the POSIX pwrite(2)
603-
documentation for more detail.
603+
documentation for more detail. **Default:** `null`
604604
* Returns: {Promise}
605605
606606
Write `buffer` to the file.
@@ -631,10 +631,10 @@ changes:
631631
-->
632632
633633
* `string` {string}
634-
* `position` {integer} The offset from the beginning of the file where the
634+
* `position` {integer|null} The offset from the beginning of the file where the
635635
data from `string` should be written. If `position` is not a `number` the
636636
data will be written at the current position. See the POSIX pwrite(2)
637-
documentation for more detail.
637+
documentation for more detail. **Default:** `null`
638638
* `encoding` {string} The expected string encoding. **Default:** `'utf8'`
639639
* Returns: {Promise}
640640
@@ -699,9 +699,9 @@ added: v12.9.0
699699
-->
700700
701701
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
702-
* `position` {integer} The offset from the beginning of the file where the
702+
* `position` {integer|null} The offset from the beginning of the file where the
703703
data from `buffers` should be written. If `position` is not a `number`,
704-
the data will be written at the current position.
704+
the data will be written at the current position. **Default:** `null`
705705
* Returns: {Promise}
706706
707707
Write an array of {ArrayBufferView}s to the file.
@@ -3198,7 +3198,7 @@ changes:
31983198
written to.
31993199
* `offset` {integer} The position in `buffer` to write the data to.
32003200
* `length` {integer} The number of bytes to read.
3201-
* `position` {integer|bigint} Specifies where to begin reading from in the
3201+
* `position` {integer|bigint|null} Specifies where to begin reading from in the
32023202
file. If `position` is `null` or `-1 `, data will be read from the current
32033203
file position, and the file position will be updated. If `position` is an
32043204
integer, the file position will be unchanged.
@@ -3237,7 +3237,7 @@ changes:
32373237
* `buffer` {Buffer|TypedArray|DataView} **Default:** `Buffer.alloc(16384)`
32383238
* `offset` {integer} **Default:** `0`
32393239
* `length` {integer} **Default:** `buffer.byteLength - offset`
3240-
* `position` {integer|bigint} **Default:** `null`
3240+
* `position` {integer|bigint|null} **Default:** `null`
32413241
* `callback` {Function}
32423242
* `err` {Error}
32433243
* `bytesRead` {integer}
@@ -3502,7 +3502,7 @@ changes:
35023502

35033503
* `fd` {integer}
35043504
* `buffers` {ArrayBufferView\[]}
3505-
* `position` {integer}
3505+
* `position` {integer|null} **Default:** `null`
35063506
* `callback` {Function}
35073507
* `err` {Error}
35083508
* `bytesRead` {integer}
@@ -3924,7 +3924,7 @@ changes:
39243924

39253925
* `target` {string|Buffer|URL}
39263926
* `path` {string|Buffer|URL}
3927-
* `type` {string}
3927+
* `type` {string|null} **Default:** `null`
39283928
* `callback` {Function}
39293929
* `err` {Error}
39303930

@@ -3935,8 +3935,8 @@ See the POSIX symlink(2) documentation for more details.
39353935

39363936
The `type` argument is only available on Windows and ignored on other platforms.
39373937
It can be set to `'dir'`, `'file'`, or `'junction'`. If the `type` argument is
3938-
not set, Node.js will autodetect `target` type and use `'file'` or `'dir'`. If
3939-
the `target` does not exist, `'file'` will be used. Windows junction points
3938+
not a string, Node.js will autodetect `target` type and use `'file'` or `'dir'`.
3939+
If the `target` does not exist, `'file'` will be used. Windows junction points
39403940
require the destination path to be absolute. When using `'junction'`, the
39413941
`target` argument will automatically be normalized to absolute path.
39423942

@@ -4363,9 +4363,9 @@ changes:
43634363
43644364
* `fd` {integer}
43654365
* `buffer` {Buffer|TypedArray|DataView}
4366-
* `offset` {integer}
4367-
* `length` {integer}
4368-
* `position` {integer}
4366+
* `offset` {integer} **Default:** `0`
4367+
* `length` {integer} **Default:** `buffer.byteLength - offset`
4368+
* `position` {integer|null} **Default:** `null`
43694369
* `callback` {Function}
43704370
* `err` {Error}
43714371
* `bytesWritten` {integer}
@@ -4426,7 +4426,7 @@ changes:
44264426
44274427
* `fd` {integer}
44284428
* `string` {string|Object}
4429-
* `position` {integer}
4429+
* `position` {integer|null} **Default:** `null`
44304430
* `encoding` {string} **Default:** `'utf8'`
44314431
* `callback` {Function}
44324432
* `err` {Error}
@@ -4627,7 +4627,7 @@ changes:
46274627
46284628
* `fd` {integer}
46294629
* `buffers` {ArrayBufferView\[]}
4630-
* `position` {integer}
4630+
* `position` {integer|null} **Default:** `null`
46314631
* `callback` {Function}
46324632
* `err` {Error}
46334633
* `bytesWritten` {integer}
@@ -5344,7 +5344,7 @@ object with an `encoding` property specifying the character encoding to use for
53445344
the link path returned. If the `encoding` is set to `'buffer'`,
53455345
the link path returned will be passed as a {Buffer} object.
53465346
5347-
### `fs.readSync(fd, buffer, offset, length, position)`
5347+
### `fs.readSync(fd, buffer, offset, length[, position])`
53485348
53495349
<!-- YAML
53505350
added: v0.1.21
@@ -5362,7 +5362,7 @@ changes:
53625362
* `buffer` {Buffer|TypedArray|DataView}
53635363
* `offset` {integer}
53645364
* `length` {integer}
5365-
* `position` {integer|bigint}
5365+
* `position` {integer|bigint|null} **Default:** `null`
53665366
* Returns: {number}
53675367
53685368
Returns the number of `bytesRead`.
@@ -5390,7 +5390,7 @@ changes:
53905390
* `options` {Object}
53915391
* `offset` {integer} **Default:** `0`
53925392
* `length` {integer} **Default:** `buffer.byteLength - offset`
5393-
* `position` {integer|bigint} **Default:** `null`
5393+
* `position` {integer|bigint|null} **Default:** `null`
53945394
* Returns: {number}
53955395
53965396
Returns the number of `bytesRead`.
@@ -5411,7 +5411,7 @@ added:
54115411
54125412
* `fd` {integer}
54135413
* `buffers` {ArrayBufferView\[]}
5414-
* `position` {integer}
5414+
* `position` {integer|null} **Default:** `null`
54155415
* Returns: {number} The number of bytes read.
54165416
54175417
For detailed information, see the documentation of the asynchronous version of
@@ -5635,7 +5635,7 @@ changes:
56355635
56365636
* `target` {string|Buffer|URL}
56375637
* `path` {string|Buffer|URL}
5638-
* `type` {string}
5638+
* `type` {string|null} **Default:** `null`
56395639
56405640
Returns `undefined`.
56415641
@@ -5767,9 +5767,9 @@ changes:
57675767
57685768
* `fd` {integer}
57695769
* `buffer` {Buffer|TypedArray|DataView}
5770-
* `offset` {integer}
5771-
* `length` {integer}
5772-
* `position` {integer}
5770+
* `offset` {integer} **Default:** `0`
5771+
* `length` {integer} **Default:** `buffer.byteLength - offset`
5772+
* `position` {integer|null} **Default:** `null`
57735773
* Returns: {number} The number of bytes written.
57745774
57755775
For detailed information, see the documentation of the asynchronous version of
@@ -5791,8 +5791,8 @@ changes:
57915791
57925792
* `fd` {integer}
57935793
* `string` {string}
5794-
* `position` {integer}
5795-
* `encoding` {string}
5794+
* `position` {integer|null} **Default:** `null`
5795+
* `encoding` {string} **Default:** `'utf8'`
57965796
* Returns: {number} The number of bytes written.
57975797
57985798
For detailed information, see the documentation of the asynchronous version of
@@ -5806,7 +5806,7 @@ added: v12.9.0
58065806
58075807
* `fd` {integer}
58085808
* `buffers` {ArrayBufferView\[]}
5809-
* `position` {integer}
5809+
* `position` {integer|null} **Default:** `null`
58105810
* Returns: {number} The number of bytes written.
58115811
58125812
For detailed information, see the documentation of the asynchronous version of

‎lib/fs.js

+10-10
Original file line numberDiff line numberDiff line change
@@ -597,7 +597,7 @@ function openSync(path, flags, mode) {
597597
* @param {Buffer | TypedArray | DataView} buffer
598598
* @param {number} offset
599599
* @param {number} length
600-
* @param {number | bigint} position
600+
* @param {number | bigint | null} position
601601
* @param {(
602602
* err?: Error,
603603
* bytesRead?: number,
@@ -682,7 +682,7 @@ ObjectDefineProperty(read, internalUtil.customPromisifyArgs,
682682
* @param {{
683683
* offset?: number;
684684
* length?: number;
685-
* position?: number | bigint;
685+
* position?: number | bigint | null;
686686
* }} [offset]
687687
* @returns {number}
688688
*/
@@ -738,7 +738,7 @@ function readSync(fd, buffer, offset, length, position) {
738738
* and writes to an array of `ArrayBufferView`s.
739739
* @param {number} fd
740740
* @param {ArrayBufferView[]} buffers
741-
* @param {number} [position]
741+
* @param {number | null} [position]
742742
* @param {(
743743
* err?: Error,
744744
* bytesRead?: number,
@@ -773,7 +773,7 @@ ObjectDefineProperty(readv, internalUtil.customPromisifyArgs,
773773
* of `ArrayBufferView`s.
774774
* @param {number} fd
775775
* @param {ArrayBufferView[]} buffers
776-
* @param {number} [position]
776+
* @param {number | null} [position]
777777
* @returns {number}
778778
*/
779779
function readvSync(fd, buffers, position) {
@@ -796,7 +796,7 @@ function readvSync(fd, buffers, position) {
796796
* @param {Buffer | TypedArray | DataView | string | object} buffer
797797
* @param {number} [offset]
798798
* @param {number} [length]
799-
* @param {number} [position]
799+
* @param {number | null} [position]
800800
* @param {(
801801
* err?: Error,
802802
* bytesWritten?: number;
@@ -864,7 +864,7 @@ ObjectDefineProperty(write, internalUtil.customPromisifyArgs,
864864
* @param {Buffer | TypedArray | DataView | string} buffer
865865
* @param {number} [offset]
866866
* @param {number} [length]
867-
* @param {number} [position]
867+
* @param {number | null} [position]
868868
* @returns {number}
869869
*/
870870
function writeSync(fd, buffer, offset, length, position) {
@@ -902,7 +902,7 @@ function writeSync(fd, buffer, offset, length, position) {
902902
* specified `fd` (file descriptor).
903903
* @param {number} fd
904904
* @param {ArrayBufferView[]} buffers
905-
* @param {number} [position]
905+
* @param {number | null} [position]
906906
* @param {(
907907
* err?: Error,
908908
* bytesWritten?: number,
@@ -943,7 +943,7 @@ ObjectDefineProperty(writev, internalUtil.customPromisifyArgs, {
943943
* to the specified `fd` (file descriptor).
944944
* @param {number} fd
945945
* @param {ArrayBufferView[]} buffers
946-
* @param {number} [position]
946+
* @param {number | null} [position]
947947
* @returns {number}
948948
*/
949949
function writevSync(fd, buffers, position) {
@@ -1601,7 +1601,7 @@ function readlinkSync(path, options) {
16011601
* Creates the link called `path` pointing to `target`.
16021602
* @param {string | Buffer | URL} target
16031603
* @param {string | Buffer | URL} path
1604-
* @param {string} [type_]
1604+
* @param {string | null} [type_]
16051605
* @param {(err?: Error) => any} callback_
16061606
* @returns {void}
16071607
*/
@@ -1654,7 +1654,7 @@ function symlink(target, path, type_, callback_) {
16541654
* pointing to `target`.
16551655
* @param {string | Buffer | URL} target
16561656
* @param {string | Buffer | URL} path
1657-
* @param {string} [type]
1657+
* @param {string | null} [type]
16581658
* @returns {void}
16591659
*/
16601660
function symlinkSync(target, path, type) {

0 commit comments

Comments
 (0)