Browse Source

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
v0.11.10-release
Sam Roberts 11 years ago
committed by Bert Belder
parent
commit
a15c44b175
  1. 28
      doc/api/net.markdown

28
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.

Loading…
Cancel
Save