From 11d71da558331be001288eef2d480b289fa4f8ef Mon Sep 17 00:00:00 2001
From: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Date: Thu, 21 Apr 2016 09:49:59 +0200
Subject: [PATCH] doc: add note for platform specific flags `fs.open()`

Note describing platform specific differences in fs.open

E.g. fs.open('<directory>', 'a+', console.log)

Fixes: https://github.com/nodejs/node/issues/3643
PR-URL: https://github.com/nodejs/node/pull/6136
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/fs.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 4364b1cc5cc674..1d64f736337224 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -795,6 +795,23 @@ 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.
 
+_Note: The behavior of `fs.open()` is platform specific for some flags. As such,
+opening a directory on OS X and Linux with the `'a+'` flag - see example below -
+will return an error. Whereas on Windows and FreeBSD a file descriptor will be
+returned._
+
+```js
+// OS X and Linux
+fs.open('<directory>', 'a+', (err, fd) => {
+  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
+})
+
+// Windows and FreeBSD
+fs.open('<directory>', 'a+', (err, fd) => {
+  // => null, <fd>
+})
+```
+
 ## fs.openSync(path, flags[, mode])
 
 * `path` {String | Buffer}