From a15c44b1756f05c4445151268378ea990a1f5dad Mon Sep 17 00:00:00 2001
From: Sam Roberts <sam@strongloop.com>
Date: Thu, 19 Dec 2013 14:57:30 -0800
Subject: [PATCH] doc: describe the local domain path on Windows

The UNIX domain is also known as the LOCAL domain (AF_LOCAL), and
node/libuv implements it on Windows using named pipes. The API
documentation did not describe the naming rules for named pipes, and
also repeatedly described `listen(path)` as being UNIX, which it is not
on Windows.

Closes #6743
---
 doc/api/net.markdown | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 38aad16ac2..d942013118 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -66,7 +66,8 @@ For TCP sockets, `options` argument should be an object which specifies:
 
   - `family` : Version of IP stack. Defaults to `4`.
 
-For UNIX domain sockets, `options` argument should be an object which specifies:
+For local domain sockets, `options` argument should be an object which
+specifies:
 
   - `path`: Path the client should connect to (Required).
 
@@ -117,7 +118,7 @@ The `connectListener` parameter will be added as an listener for the
 
 ## Class: net.Server
 
-This class is used to create a TCP or UNIX server.
+This class is used to create a TCP or local server.
 
 ### server.listen(port, [host], [backlog], [callback])
 
@@ -153,12 +154,31 @@ would be to wait a second and then try again. This can be done with
 
 ### server.listen(path, [callback])
 
-Start a UNIX socket server listening for connections on the given `path`.
+* `path` {String}
+* `callback` {Function}
+
+Start a local socket server listening for connections on the given `path`.
 
 This function is asynchronous.  When the server has been bound,
 ['listening'][] event will be emitted.  The last parameter `callback`
 will be added as an listener for the ['listening'][] event.
 
+On UNIX, the local domain is usually known as the UNIX domain. The path is a
+filesystem path name. It is subject to the same naming conventions and
+permissions checks as would be done on file creation, will be visible in the
+filesystem, and will *persist until unlinked*.
+
+On Windows, the local domain is implemented using a named pipe. The path *must*
+refer to an entry in `\\?\pipe\` or `\\.\pipe\`. Any characters are permitted,
+but the latter may do some processing of pipe names, such as resolving `..`
+sequences. Despite appearances, the pipe name space is flat.  Pipes will *not
+persist*, they are removed when the last reference to them is closed. Do not
+forget javascript string escaping requires paths to be specified with
+double-backslashes, such as:
+
+    net.createServer().listen(
+        path.join('\\\\?\\pipe', process.cwd(), 'myctl'))
+
 ### server.listen(handle, [callback])
 
 * `handle` {Object}
@@ -271,7 +291,7 @@ following this event.  See example in discussion of `server.listen`.
 
 ## Class: net.Socket
 
-This object is an abstraction of a TCP or UNIX socket.  `net.Socket`
+This object is an abstraction of a TCP or local socket.  `net.Socket`
 instances implement a duplex Stream interface.  They can be created by the
 user and used as a client (with `connect()`) or they can be created by Node
 and passed to the user through the `'connection'` event of a server.