net: update documentation on Listen and ListenPacket

This change clarifies the documentation on Listen and ListenPacket to
avoid unnecessary confusion about how the arguments for the connection
setup functions are used to make connections.

Also replaces "name" or "hostname" with "host name" when the term
implies the use of DNS.

Updates #17613.
Updates #17614.
Updates #17615.
Fixes #17616.
Updates #17738.
Updates #17956.

Change-Id: I0bad2e143207666f2358d397fc076548ee6c3ae9
Reviewed-on: https://go-review.googlesource.com/34876
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/net/dial.go b/src/net/dial.go
index 926fc266709a72f6bed84688ce401f99af1f92c6..f8b4aa227420ca79702e7aee60b95733f662a6ff 100644 (file)
--- a/src/net/dial.go
+++ b/src/net/dial.go
@@ -563,35 +563,37 @@ func dialSingle(ctx context.Context, dp *dialParam, ra Addr) (c Conn, err error)
        return c, nil
 }
 
-// Listen announces on the local network address laddr.
+// Listen announces on the local network address.
 //
-// The network net must be a stream-oriented network: "tcp", "tcp4",
-// "tcp6", "unix" or "unixpacket".
+// The network must be "tcp", "tcp4", "tcp6", "unix" or "unixpacket".
 //
-// For TCP, the syntax of laddr is "host:port", like "127.0.0.1:8080".
-// If host is omitted, as in ":8080", Listen listens on all available interfaces
-// instead of just the interface with the given host address.
-// Listening on network "tcp" with host "0.0.0.0" or "[::]" may listen on both
-// IPv4 and IPv6. To only use IPv4, use network "tcp4". To explicitly use both,
-// listen on ":port" without a host.
+// For TCP networks, if the host in the address parameter is empty or
+// a literal unspecified IP address, Listen listens on all available
+// unicast and anycast IP addresses of the local system.
+// To only use IPv4, use network "tcp4".
+// The address can use a host name, but this is not recommended,
+// because it will create a listener for at most one of the host's IP
+// addresses.
+// If the port in the address parameter is empty or "0", as in
+// "127.0.0.1:" or "[::1]:0", a port number is automatically chosen.
+// The Addr method of Listener can be used to discover the chosen
+// port.
 //
-// See Dial for more details about the 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)
+// See func Dial for a description of the network and address
+// parameters.
+func Listen(network, address string) (Listener, error) {
+       addrs, err := DefaultResolver.resolveAddrList(context.Background(), "listen", network, address, nil)
        if err != nil {
-               return nil, &OpError{Op: "listen", Net: net, Source: nil, Addr: nil, Err: err}
+               return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: nil, Err: err}
        }
        var l Listener
        switch la := addrs.first(isIPv4).(type) {
        case *TCPAddr:
-               l, err = ListenTCP(net, la)
+               l, err = ListenTCP(network, la)
        case *UnixAddr:
-               l, err = ListenUnix(net, la)
+               l, err = ListenUnix(network, la)
        default:
-               return nil, &OpError{Op: "listen", Net: net, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: laddr}}
+               return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: address}}
        }
        if err != nil {
                return nil, err // l is non-nil interface containing nil pointer
@@ -599,37 +601,43 @@ func Listen(net, laddr string) (Listener, error) {
        return l, nil
 }
 
-// ListenPacket announces on the local network address laddr.
+// ListenPacket announces on the local network address.
 //
-// The network net must be a packet-oriented network: "udp", "udp4",
-// "udp6", "ip", "ip4", "ip6" or "unixgram".
+// The network must be "udp", "udp4", "udp6", "unixgram", or an IP
+// transport. The IP transports are "ip", "ip4", or "ip6" followed by
+// a colon and a literal protocol number or a protocol name, as in
+// "ip:1" or "ip:icmp".
 //
-// For UDP, the syntax of laddr is "host:port", like "127.0.0.1:8080".
-// If host is omitted, as in ":8080", ListenPacket listens on all available
-// interfaces instead of just the interface with the given host address.
-// Listening on network "udp" with host "0.0.0.0" or "[::]" may listen on both
-// IPv4 and IPv6. To only use IPv4, use network "udp4". To explicitly use both,
-// listen on ":port" without a host.
+// For UDP and IP networks, if the host in the address parameter is
+// empty or a literal unspecified IP address, ListenPacket listens on
+// all available IP addresses of the local system except multicast IP
+// addresses.
+// To only use IPv4, use network "udp4" or "ip4:proto".
+// The address can use a host name, but this is not recommended,
+// because it will create a listener for at most one of the host's IP
+// addresses.
+// If the port in the address parameter is empty or "0", as in
+// "127.0.0.1:" or "[::1]:0", a port number is automatically chosen.
+// The LocalAddr method of PacketConn can be used to discover the
+// chosen port.
 //
-// See Dial for more details about the address syntax.
-//
-// 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)
+// See func Dial for a description of the network and address
+// parameters.
+func ListenPacket(network, address string) (PacketConn, error) {
+       addrs, err := DefaultResolver.resolveAddrList(context.Background(), "listen", network, address, nil)
        if err != nil {
-               return nil, &OpError{Op: "listen", Net: net, Source: nil, Addr: nil, Err: err}
+               return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: nil, Err: err}
        }
        var l PacketConn
        switch la := addrs.first(isIPv4).(type) {
        case *UDPAddr:
-               l, err = ListenUDP(net, la)
+               l, err = ListenUDP(network, la)
        case *IPAddr:
-               l, err = ListenIP(net, la)
+               l, err = ListenIP(network, la)
        case *UnixAddr:
-               l, err = ListenUnixgram(net, la)
+               l, err = ListenUnixgram(network, la)
        default:
-               return nil, &OpError{Op: "listen", Net: net, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: laddr}}
+               return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: address}}
        }
        if err != nil {
                return nil, err // l is non-nil interface containing nil pointer

diff --git a/src/net/example_test.go b/src/net/example_test.go
index f8f10e3509c447fca4f77c4870dc8b7e459ad5da..289d84f7c7155f7d583ae42362da78cef64b7b33 100644 (file)
--- a/src/net/example_test.go
+++ b/src/net/example_test.go
@@ -12,7 +12,8 @@ import (
 )
 
 func ExampleListener() {
-       // Listen on TCP port 2000 on all interfaces.
+       // Listen on TCP port 2000 on all available unicast and
+       // anycast IP addresses of the local system.
        l, err := net.Listen("tcp", ":2000")
        if err != nil {
                log.Fatal(err)