From 492e2a4d117aed60b5118f9e9b09c40dbb99884c Mon Sep 17 00:00:00 2001
From: Dara Hayes <dara.hayes@redhat.com>
Date: Tue, 13 Nov 2018 16:28:07 +0000
Subject: [PATCH] doc: add filehandle.write(string[, position[, encoding]])

Add missing docs for filehandle.write(string[, position[, encoding]])
In the fs.promises API.

Fixes: https://github.com/nodejs/node/issues/20406
PR-URL: https://github.com/nodejs/node/pull/23224
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
---
 doc/api/fs.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 16cede54dba598..1978fcb61cbfab 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -3941,6 +3941,37 @@ On Linux, positional writes do not work when the file is opened in append mode.
 The kernel ignores the position argument and always appends the data to
 the end of the file.
 
+#### filehandle.write(string[, position[, encoding]])
+<!-- YAML
+added: v10.0.0
+-->
+
+* `string` {string}
+* `position` {integer}
+* `encoding` {string} **Default:** `'utf8'`
+* Returns: {Promise}
+
+Write `string` to the file. If `string` is not a string, then
+the value will be coerced to one.
+
+The `Promise` is resolved with an object containing a `bytesWritten` property
+identifying the number of bytes written, and a `buffer` property containing
+a reference to the `string` written.
+
+`position` refers to the offset from the beginning of the file where this data
+should be written. If the type of `position` is not a `number` the data
+will be written at the current position. See pwrite(2).
+
+`encoding` is the expected string encoding.
+
+It is unsafe to use `filehandle.write()` multiple times on the same file
+without waiting for the `Promise` to be resolved (or rejected). For this
+scenario, [`fs.createWriteStream()`][] is strongly recommended.
+
+On Linux, positional writes do not work when the file is opened in append mode.
+The kernel ignores the position argument and always appends the data to
+the end of the file.
+
 #### filehandle.writeFile(data, options)
 <!-- YAML
 added: v10.0.0