Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: clarify lifecycle of domain sockets #19471

Merged
merged 1 commit into from
Apr 6, 2018
Merged

doc: clarify lifecycle of domain sockets #19471

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions doc/api/net.md
View file
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this is clear to be honest, I think an example would help more.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@benjamingr - Can you please clarify what is not clear? and example for what?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @benjamingr to see what can be done.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gireeshpunathil I'm not blocking - I'm just not sure the description here is less confusing than before. I don't have any ideas as to what I'd write differently - sorry!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@benjamingr - thanks, sure. I have asked the OP ( @boneskull ) to have a look too to see if any improvements can be made. Else I will move towards landing, thanks!

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