From 390db428537a5017aae2d5bf3b821bb9e622c708 Mon Sep 17 00:00:00 2001
From: "Sakthipriyan Vairamani (thefourtheye)" <thechargingvolcano@gmail.com>
Date: Wed, 17 Oct 2018 12:56:13 +0530
Subject: [PATCH] doc: clarify fd behaviour with {read,write}File
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/23706
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
---
 doc/api/fs.md | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index ddb5b72b19e361..21f1b91db6e15e 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2547,14 +2547,18 @@ fs.readFile('<directory>', (err, data) => {
 });
 ```
 
-Any specified file descriptor has to support reading.
-
-If a file descriptor is specified as the `path`, it will not be closed
-automatically.
-
 The `fs.readFile()` function buffers the entire file. To minimize memory costs,
 when possible prefer streaming via `fs.createReadStream()`.
 
+### File Descriptors
+1. Any specified file descriptor has to support reading.
+2. If a file descriptor is specified as the `path`, it will not be closed
+automatically.
+3. The reading will begin at the current position. For example, if the file
+already had `'Hello World`' and six bytes are read with the file descriptor,
+the call to `fs.readFile()` with the same file descriptor, would give
+`'World'`, rather than `'Hello World'`.
+
 ## fs.readFileSync(path[, options])
 <!-- YAML
 added: v0.1.8
@@ -3540,14 +3544,19 @@ If `options` is a string, then it specifies the encoding:
 fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
 ```
 
-Any specified file descriptor has to support writing.
-
 It is unsafe to use `fs.writeFile()` multiple times on the same file without
 waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is
 recommended.
 
-If a file descriptor is specified as the `file`, it will not be closed
+### File Descriptors
+1. Any specified file descriptor has to support writing.
+2. If a file descriptor is specified as the `file`, it will not be closed
 automatically.
+3. The writing will begin at the beginning of the file. For example, if the
+file already had `'Hello World'` and the newly written content is `'Aloha'`,
+then the contents of the file would be `'Aloha World'`, rather than just
+`'Aloha'`.
+
 
 ## fs.writeFileSync(file, data[, options])
 <!-- YAML
@@ -3780,6 +3789,11 @@ returned.
 
 The `FileHandle` has to support reading.
 
+If one or more `filehandle.read()` calls are made on a file handle and then a
+`filehandle.readFile()` call is made, the data will be read from the current
+position till the end of the file. It doesn't always read from the beginning
+of the file.
+
 #### filehandle.stat([options])
 <!-- YAML
 added: v10.0.0
@@ -3942,6 +3956,11 @@ The `FileHandle` has to support writing.
 It is unsafe to use `filehandle.writeFile()` multiple times on the same file
 without waiting for the `Promise` to be resolved (or rejected).
 
+If one or more `filehandle.write()` calls are made on a file handle and then a
+`filehandle.writeFile()` call is made, the data will be written from the
+current position till the end of the file. It doesn't always write from the
+beginning of the file.
+
 ### fsPromises.access(path[, mode])
 <!-- YAML
 added: v10.0.0