From e8c01739cd622e808c4a4d11f6d323981296414d Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Mon, 8 Apr 2013 00:41:33 +0200 Subject: [PATCH] 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. --- doc/api/fs.markdown | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 6730b7c9fc..bcf5b24513 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.