From 8ca426cda70e98665c144cc5de3baa45dc31a911 Mon Sep 17 00:00:00 2001 From: Gireesh Punathil Date: Tue, 20 Mar 2018 13:41:37 +0530 Subject: [PATCH] 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: https://github.com/nodejs/help/issues/1080 --- doc/api/net.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index 489659001ce9b9..738ccfa4997c78 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -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(