Skip to content

Commit

Permalink
doc: clarify lifecycle of domain sockets
Browse files Browse the repository at this point in the history
In UNIX, the domain sockets once created persists until unlinked.
Clarify which ones are persisted and which ones are cleared manually.

In Windows, named pipes are cleared based on reference count,
implemented by the underlying system. Disambiguate this from
Garbage collection of the Node.js runtime.

Refs: nodejs/help#1080

PR-URL: #19471
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
  • Loading branch information
gireeshpunathil authored and Trott committed Apr 6, 2018
1 parent 3dc5404 commit 53aaa55
Showing 1 changed file with 16 additions and 7 deletions.
23 changes: 16 additions & 7 deletions doc/api/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,29 @@ sockets on other operating systems.
[`socket.connect()`][] take a `path` parameter to identify IPC endpoints.

On UNIX, the local domain is also known as the UNIX domain. The path is a
filesystem path name. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`,
filesystem pathname. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`,
which varies on different operating system between 91 and 107 bytes.
The typical values are 107 on Linux and 103 on macOS. The path is
subject to the same naming conventions and permissions checks as would be done
on file creation. It will be visible in the filesystem, and will *persist until
unlinked*.
on file creation. If the UNIX domain socket (that is visible as a file system
path) is created and used in conjunction with one of Node.js' API abstractions
such as [`net.createServer()`][], it will be unlinked as part of
[`server.close()`][]. On the other hand, if it is created and used outside of
these abstractions, the user will need to manually remove it. The same applies
when the path was created by a Node.js API but the program crashes abruptly.
In short, a UNIX domain socket once successfully created 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:
sequences. Despite how it might look, the pipe namespace is flat. Pipes will
*not persist*. They are removed when the last reference to them is closed.
Unlike UNIX domain sockets, Windows will close and remove the pipe when the
owning process exits.

JavaScript string escaping requires paths to be specified with extra backslash
escaping such as:

```js
net.createServer().listen(
Expand Down

0 comments on commit 53aaa55

Please sign in to comment.