Skip to content

Commit 53aaa55

Browse files
gireeshpunathilTrott
authored andcommitted
doc: clarify lifecycle of domain sockets
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>
1 parent 3dc5404 commit 53aaa55

File tree

1 file changed

+16
-7
lines changed

1 file changed

+16
-7
lines changed

doc/api/net.md

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,29 @@ sockets on other operating systems.
2626
[`socket.connect()`][] take a `path` parameter to identify IPC endpoints.
2727

2828
On UNIX, the local domain is also known as the UNIX domain. The path is a
29-
filesystem path name. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`,
29+
filesystem pathname. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`,
3030
which varies on different operating system between 91 and 107 bytes.
3131
The typical values are 107 on Linux and 103 on macOS. The path is
3232
subject to the same naming conventions and permissions checks as would be done
33-
on file creation. It will be visible in the filesystem, and will *persist until
34-
unlinked*.
33+
on file creation. If the UNIX domain socket (that is visible as a file system
34+
path) is created and used in conjunction with one of Node.js' API abstractions
35+
such as [`net.createServer()`][], it will be unlinked as part of
36+
[`server.close()`][]. On the other hand, if it is created and used outside of
37+
these abstractions, the user will need to manually remove it. The same applies
38+
when the path was created by a Node.js API but the program crashes abruptly.
39+
In short, a UNIX domain socket once successfully created will be visible in the
40+
filesystem, and will persist until unlinked.
3541

3642
On Windows, the local domain is implemented using a named pipe. The path *must*
3743
refer to an entry in `\\?\pipe\` or `\\.\pipe\`. Any characters are permitted,
3844
but the latter may do some processing of pipe names, such as resolving `..`
39-
sequences. Despite appearances, the pipe name space is flat. Pipes will *not
40-
persist*, they are removed when the last reference to them is closed. Do not
41-
forget JavaScript string escaping requires paths to be specified with
42-
double-backslashes, such as:
45+
sequences. Despite how it might look, the pipe namespace is flat. Pipes will
46+
*not persist*. They are removed when the last reference to them is closed.
47+
Unlike UNIX domain sockets, Windows will close and remove the pipe when the
48+
owning process exits.
49+
50+
JavaScript string escaping requires paths to be specified with extra backslash
51+
escaping such as:
4352

4453
```js
4554
net.createServer().listen(

0 commit comments

Comments
 (0)