net: add hostname warnings to all first(isIPv4) functions.

In general, these functions cannot behave correctly when given a
hostname, because a hostname may represent multiple IP addresses, and
first(isIPv4) chooses at most one.

Updates #9334

Change-Id: Icfb629f84af4d976476385a3071270253c0000b1
Reviewed-on: https://go-review.googlesource.com/31931
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/net/dial.go b/src/net/dial.go
index dc982bdb8788d992fa72d88f0675de9e3406a984..c77f0db030ac5d4b0d6ff2e80c014bd0fc9c57ed 100644 (file)
--- a/src/net/dial.go
+++ b/src/net/dial.go
@@ -533,6 +533,9 @@ func dialSingle(ctx context.Context, dp *dialParam, ra Addr) (c Conn, err error)
 // If host is omitted, as in ":8080", Listen listens on all available interfaces
 // instead of just the interface with the given host address.
 // See Dial for more details about address syntax.
+//
+// Listening on a hostname is not recommended because this creates a socket
+// for at most one of its IP addresses.
 func Listen(net, laddr string) (Listener, error) {
        addrs, err := DefaultResolver.resolveAddrList(context.Background(), "listen", net, laddr, nil)
        if err != nil {
@@ -560,6 +563,9 @@ func Listen(net, laddr string) (Listener, error) {
 // If host is omitted, as in ":8080", ListenPacket listens on all available interfaces
 // instead of just the interface with the given host address.
 // See Dial for the syntax of laddr.
+//
+// Listening on a hostname is not recommended because this creates a socket
+// for at most one of its IP addresses.
 func ListenPacket(net, laddr string) (PacketConn, error) {
        addrs, err := DefaultResolver.resolveAddrList(context.Background(), "listen", net, laddr, nil)
        if err != nil {

diff --git a/src/net/iprawsock.go b/src/net/iprawsock.go
index a7a4531fde6449e8521469a4b93a9bab9ebfd665..b3cc03e00d46f4478a4cddaea0dcc0b2181084b7 100644 (file)
--- a/src/net/iprawsock.go
+++ b/src/net/iprawsock.go
@@ -52,6 +52,9 @@ func (a *IPAddr) opAddr() Addr {
 // ResolveIPAddr parses addr as an IP address of the form "host" or
 // "ipv6-host%zone" and resolves the domain name on the network net,
 // which must be "ip", "ip4" or "ip6".
+//
+// Resolving a hostname is not recommended because this returns at most
+// one of its IP addresses.
 func ResolveIPAddr(net, addr string) (*IPAddr, error) {
        if net == "" { // a hint wildcard for Go 1.0 undocumented behavior
                net = "ip"

diff --git a/src/net/tcpsock.go b/src/net/tcpsock.go
index 1f7f59a3b6e3536ba4fb5bf657e732f901c992ff..69731ebc9143c4f7d869727bda19203a03546277 100644 (file)
--- a/src/net/tcpsock.go
+++ b/src/net/tcpsock.go
@@ -56,6 +56,9 @@ func (a *TCPAddr) opAddr() Addr {
 // "tcp6".  A literal address or host name for IPv6 must be enclosed
 // in square brackets, as in "[::1]:80", "[ipv6-host]:http" or
 // "[ipv6-host%zone]:80".
+//
+// Resolving a hostname is not recommended because this returns at most
+// one of its IP addresses.
 func ResolveTCPAddr(net, addr string) (*TCPAddr, error) {
        switch net {
        case "tcp", "tcp4", "tcp6":

diff --git a/src/net/udpsock.go b/src/net/udpsock.go
index e54eee837aab578c58ea77815645802455039ba7..246d644336b4291f6abdb341451a41a0dfddff2a 100644 (file)
--- a/src/net/udpsock.go
+++ b/src/net/udpsock.go
@@ -59,6 +59,9 @@ func (a *UDPAddr) opAddr() Addr {
 // "udp6".  A literal address or host name for IPv6 must be enclosed
 // in square brackets, as in "[::1]:80", "[ipv6-host]:http" or
 // "[ipv6-host%zone]:80".
+//
+// Resolving a hostname is not recommended because this returns at most
+// one of its IP addresses.
 func ResolveUDPAddr(net, addr string) (*UDPAddr, error) {
        switch net {
        case "udp", "udp4", "udp6":