doc: add comment for net.Server.listen IPv6 '::'

Fixes: #9390 PR-URL: #11134 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]>
nodejs · Feb 22, 2017 · 12cf359 · 12cf359
1 parent d1549bf
commit 12cf359
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 4 deletions.
diff --git a/doc/api/http.md b/doc/api/http.md
@@ -745,8 +745,14 @@ added: v0.1.90
 * `callback` {Function}
 
 Begin accepting connections on the specified `port` and `hostname`. If the
-`hostname` is omitted, the server will accept connections on any IPv6 address
-(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise.
+`hostname` is omitted, the server will accept connections on the
+[unspecified IPv6 address][] (`::`) when IPv6 is available, or the
+[unspecified IPv4 address][] (`0.0.0.0`) otherwise.
+
+*Note*: in most operating systems, listening to the
+[unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
+the [unspecified IPv4 address][] (`0.0.0.0`).
+
 Omit the port argument, or use a port value of `0`, to have the operating system
 assign a random port, which can be retrieved by using `server.address().port`
 after the `'listening'` event has been emitted.
@@ -1659,3 +1665,5 @@ There are a few special headers that should be noted.
 [Readable Stream]: stream.html#stream_class_stream_readable
 [Writable Stream]: stream.html#stream_class_stream_writable
 [socket.unref()]: net.html#net_socket_unref
+[unspecified IPv6 address]: https://en.wikipedia.org/wiki/IPv6_address#Unspecified_address
+[unspecified IPv4 address]: https://en.wikipedia.org/wiki/0.0.0.0
diff --git a/doc/api/net.md b/doc/api/net.md
@@ -224,8 +224,14 @@ added: v0.1.90
 -->
 
 Begin accepting connections on the specified `port` and `hostname`. If the
-`hostname` is omitted, the server will accept connections on any IPv6 address
-(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise.
+`hostname` is omitted, the server will accept connections on the
+[unspecified IPv6 address][] (`::`) when IPv6 is available, or the
+[unspecified IPv4 address][] (`0.0.0.0`) otherwise.
+
+*Note*: in most operating systems, listening to the
+[unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
+the [unspecified IPv4 address][] (`0.0.0.0`).
+
 Omit the port argument, or use a port value of `0`, to have the operating system
 assign a random port, which can be retrieved by using `server.address().port`
 after the `'listening'` event has been emitted.
@@ -941,3 +947,5 @@ Returns true if input is a version 6 IP address, otherwise returns false.
 [`socket.setTimeout()`]: #net_socket_settimeout_timeout_callback
 [`stream.setEncoding()`]: stream.html#stream_readable_setencoding_encoding
 [Readable Stream]: stream.html#stream_class_stream_readable
+[unspecified IPv6 address]: https://en.wikipedia.org/wiki/IPv6_address#Unspecified_address
+[unspecified IPv4 address]: https://en.wikipedia.org/wiki/0.0.0.0