doc: resolving merge conflicts

Finally able to resolve the merge conflicts
indranil · Apr 15, 2018 · Apr 15, 2018 · Apr 15, 2018 · Apr 15, 2018 · Apr 16, 2018
commit a7af43c309b228b9df2f83c145b980cb2ccb6f84
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -2118,13 +2118,86 @@ changes:
   * `err` {Error}
   * `fd` {integer}
 
-Asynchronous file open. See open(2).
+Asynchronous file open. See open(2). `flags` can be:
+
+* `'r'` - Open file for reading.
+An exception occurs if the file does not exist.
+
+* `'r+'` - Open file for reading and writing.
+An exception occurs if the file does not exist.
+
+* `'rs+'` - Open file for reading and writing in synchronous mode. Instructs
+  the operating system to bypass the local file system cache.
+
+  This is primarily useful for opening files on NFS mounts as it allows skipping
+  the potentially stale local cache. It has a very real impact on I/O
+  performance so using this flag is not recommended unless it is needed.
+
+  Note that this doesn't turn `fs.open()` into a synchronous blocking call.
+  If synchronous operation is desired `fs.openSync()` should be used.
+
+* `'w'` - Open file for writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'wx'` - Like `'w'` but fails if `path` exists.
+
+* `'w+'` - Open file for reading and writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'wx+'` - Like `'w+'` but fails if `path` exists.
+
+* `'a'` - Open file for appending.
+The file is created if it does not exist.
+
+* `'ax'` - Like `'a'` but fails if `path` exists.
+
+* `'as'` - Open file for appending in synchronous mode.
+The file is created if it does not exist.
+
+* `'a+'` - Open file for reading and appending.
+The file is created if it does not exist.
+
+* `'ax+'` - Like `'a+'` but fails if `path` exists.
+
+* `'as+'` - Open file for reading and appending in synchronous mode.
+The file is created if it does not exist.
 
 `mode` sets the file mode (permission and sticky bits), but only if the file was
 created.
 
 The callback gets two arguments `(err, fd)`.
 
+The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly
+created. On POSIX systems, `path` is considered to exist even if it is a symlink
+to a non-existent file. The exclusive flag may or may not work with network file
+systems.
+
+`flags` can also be a number as documented by open(2); commonly used constants
+are available from `fs.constants`. On Windows, flags are translated to
+their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
+or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW.
+
+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.
+
+The behavior of `fs.open()` is platform-specific for some flags. As such,
+opening a directory on macOS and Linux with the `'a+'` flag - see example
+below - will return an error. In contrast, on Windows and FreeBSD, a file
+descriptor will be returned.
+
+```js
+// macOS 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>
+});
+```
+
 Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
 by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
 a colon, Node.js will open a file system stream, as described by
@@ -2133,6 +2206,11 @@ a colon, Node.js will open a file system stream, as described by
 Functions based on `fs.open()` exhibit this behavior as well. eg.
 `fs.writeFile()`, `fs.readFile()`, etc.
 
+*Note:* On Windows, opening an existing hidden file using the `w` flag (either
+through `fs.open()` or `fs.writeFile()`) will fail with `EPERM`. Existing hidden
+files can be opened for writing with the `r+` flag. A call to `fs.ftruncate()`
+can be used to reset the file contents.
+
 ## fs.openSync(path, flags[, mode])
 <!-- YAML
 added: v0.1.21
@@ -4017,14 +4095,82 @@ added: REPLACEME
 Asynchronous file open that returns a `Promise` that, when resolved, yields a
 `FileHandle` object. See open(2).
 
+The `flags` argument can be:
+
+* `'r'` - Open file for reading.
+An exception occurs if the file does not exist.
+
+* `'r+'` - Open file for reading and writing.
+An exception occurs if the file does not exist.
+
+* `'rs+'` - Open file for reading and writing in synchronous mode. Instructs
+  the operating system to bypass the local file system cache.
+
+  This is primarily useful for opening files on NFS mounts as it allows skipping
+  the potentially stale local cache. It has a very real impact on I/O
+  performance so using this flag is not recommended unless it is needed.
+
+  Note that this does not turn `fsPromises.open()` into a synchronous blocking
+  call.
+
+* `'w'` - Open file for writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'wx'` - Like `'w'` but fails if `path` exists.
+
+* `'w+'` - Open file for reading and writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'wx+'` - Like `'w+'` but fails if `path` exists.
+
+* `'a'` - Open file for appending.
+The file is created if it does not exist.
+
+* `'ax'` - Like `'a'` but fails if `path` exists.
+
+* `'as'` - Open file for appending in synchronous mode.
+The file is created if it does not exist.
+
+* `'a+'` - Open file for reading and appending.
+The file is created if it does not exist.
+
+* `'ax+'` - Like `'a+'` but fails if `path` exists.
+
+* `'as+'` - Open file for reading and appending in synchronous mode.
+The file is created if it does not exist.
+
 `mode` sets the file mode (permission and sticky bits), but only if the file was
 created.
 
+The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly
+created. On POSIX systems, `path` is considered to exist even if it is a symlink
+to a non-existent file. The exclusive flag may or may not work with network file
+systems.
+
+`flags` can also be a number as documented by open(2); commonly used constants
+are available from `fs.constants`. On Windows, flags are translated to
+their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
+or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW.
+
+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.
+
+The behavior of `fsPromises.open()` is platform-specific for some
+flags. As such, opening a directory on macOS and Linux with the `'a+'` flag will
+return an error. In contrast, on Windows and FreeBSD, a `FileHandle` will be
+returned.
+
 Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
 by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
 a colon, Node.js will open a file system stream, as described by
 [this MSDN page][MSDN-Using-Streams].
 
+*Note:* On Windows, opening an existing hidden file using the `w` flag (e.g.
+using `fsPromises.open()`) will fail with `EPERM`. Existing hidden
+files can be opened for writing with the `r+` flag. A call to
+`fsPromises.ftruncate()` can be used to reset the file contents.
+
 ### fsPromises.read(filehandle, buffer, offset, length, position)
 <!-- YAML
 added: REPLACEME
@@ -4553,27 +4699,11 @@ The following constants are meant for use with the [`fs.Stats`][] object's
   </tr>
 </table>
 
-## File System Flags
+### File System Flags
 
 The following flags are available wherever the `flag` option takes a
 string:
 
-* `'a'` - Open file for appending.
-The file is created if it does not exist.
-
-* `'ax'` - Like `'a'` but fails if `path` exists.
-
-* `'a+'` - Open file for reading and appending.
-The file is created if it does not exist.
-
-* `'ax+'` - Like `'a+'` but fails if `path` exists.
-
-* `'as'` - Open file for appending in synchronous mode.
-The file is created if it does not exist.
-
-* `'as+'` - Open file for reading and appending in synchronous mode.
-The file is created if it does not exist.
-
 * `'r'` - Open file for reading.
 An exception occurs if the file does not exist.
 
@@ -4583,14 +4713,6 @@ An exception occurs if the file does not exist.
 * `'rs+'` - Open file for reading and writing in synchronous mode. Instructs
   the operating system to bypass the local file system cache.
 
-  This is primarily useful for opening files on NFS mounts as it allows
-  skipping the potentially stale local cache. It has a very real impact on
-  I/O performance so using this flag is not recommended unless it is needed.
-
-  Note that this doesn't turn `fs.open()` or `fsPromises.open()` into a
-  synchronous blocking call. If synchronous operation is desired, something
-  like `fs.openSync()` should be used.
-
 * `'w'` - Open file for writing.
 The file is created (if it does not exist) or truncated (if it exists).
 
@@ -4601,6 +4723,22 @@ The file is created (if it does not exist) or truncated (if it exists).
 
 * `'wx+'` - Like `'w+'` but fails if `path` exists.
 
+* `'a'` - Open file for appending.
+The file is created if it does not exist.
+
+* `'ax'` - Like `'a'` but fails if `path` exists.
+
+* `'as'` - Open file for appending in synchronous mode.
+The file is created if it does not exist.
+
+* `'a+'` - Open file for reading and appending.
+The file is created if it does not exist.
+
+* `'ax+'` - Like `'a+'` but fails if `path` exists.
+
+* `'as+'` - Open file for reading and appending in synchronous mode.
+The file is created if it does not exist.
+
 `flag` can also be a number as documented by open(2); commonly used constants
 are available from `fs.constants`. On Windows, flags are translated to
 their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
@@ -4618,27 +4756,12 @@ the end of the file.
 Modifying a file rather than replacing it may require a flags mode of `'r+'`
 rather than the default mode `'w'`.
 
-The behavior of some flags are platform-specific. As such, opening a directory
-on macOS and Linux with the `'a+'` flag - see example below - will return an
-error. In contrast, on Windows and FreeBSD, a file descriptor will be returned.
-
-```js
-// macOS 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>
-});
-```
-
 On Windows, opening an existing hidden file using the `'w'` flag (either
 through `fs.open` or `fs.writeFile` or `fsPromises.open()`) will fail with
 `EPERM`. Existing hidden files can be opened for writing with the `'r+'` flag.
-A call to `fs.ftruncate()` or `fsPromises.ftruncate()` can be used to reset
-the file contents.
+
+
+
 
 [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
 [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding