doc: document linux pwrite() bug

On Linux, positional writes don't 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.

To quote the man page:

  POSIX requires that opening a file with the O_APPEND flag should have
  no affect on the location at which pwrite() writes data.  However, on
  Linux, if a file is opened with O_APPEND, pwrite() appends data to the
  end of the file, regardless of the value of offset.

1 files changed, 8 insertions, 0 deletions

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index 6730b7c9fc0..bcf5b24513a 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -330,6 +330,10 @@ Exclusive mode (`O_EXCL`) ensures that `path` is newly created. `fs.open()`
 fails if a file by that name already exists. On POSIX systems, symlinks are
 not followed. Exclusive mode may or may not work with network file systems.
 
+On Linux, positional writes don't 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.
+
 ## fs.openSync(path, flags, [mode])
 
 Synchronous open(2).
@@ -372,6 +376,10 @@ Note that it is unsafe to use `fs.write` multiple times on the same file
 without waiting for the callback. For this scenario,
 `fs.createWriteStream` is strongly recommended.
 
+On Linux, positional writes don't 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.
+
 ## fs.writeSync(fd, buffer, offset, length, position)
 
 Synchronous version of `fs.write()`. Returns the number of bytes written.