net: change ListenUnixgram signature to return UnixConn instead of UDPConn

This CL breaks Go 1 API compatibility but it doesn't matter because
previous ListenUnixgram doesn't work in any use cases, oops.

The public API change is:
-pkg net, func ListenUnixgram(string, *UnixAddr) (*UDPConn, error)
+pkg net, func ListenUnixgram(string, *UnixAddr) (*UnixConn, error)

Fixes #3875.

R=rsc, golang-dev, dave
CC=golang-dev
https://golang.org/cl/6937059

api/except.txt

+pkg net, func ListenUnixgram(string, *UnixAddr) (*UDPConn, error)
 pkg text/template/parse, type DotNode bool
 pkg text/template/parse, type Node interface { Copy, String, Type }

doc/go1.1.html

@@ -84,6 +84,13 @@ The same is true of the other protocol-specific resolvers <code>ResolveIPAddr</c
 <code>ResolveUnixAddr</code>.
 </p>
 
+<p>
+The previous <code>ListenUnixgram</code> returned <code>UDPConn</code> as
+arepresentation of the connection endpoint. The Go 1.1 implementation
+returns <code>UnixConn</code> to allow reading and writing
+with <code>ReadFrom</code> and <code>WriteTo</code> methods on
+the <code>UnixConn</code>.
+</p>
 
 <h3 id="time">time</h3>
 <p>

src/pkg/net/dial.go

@@ -238,7 +238,7 @@ func ListenPacket(net, laddr string) (PacketConn, error) {
 		if a != nil {
 			la = a.(*UnixAddr)
 		}
-		return DialUnix(net, la, nil)
+		return ListenUnixgram(net, la)
 	}
 	return nil, UnknownNetworkError(net)
 }

src/pkg/net/protoconn_test.go

@@ -263,9 +263,10 @@ func TestUnixConnSpecificMethods(t *testing.T) {
 		return
 	}
 
-	p1, p2 := "/tmp/gotest.net1", "/tmp/gotest.net2"
+	p1, p2, p3 := "/tmp/gotest.net1", "/tmp/gotest.net2", "/tmp/gotest.net3"
 	os.Remove(p1)
 	os.Remove(p2)
+	os.Remove(p3)
 
 	a1, err := net.ResolveUnixAddr("unixgram", p1)
 	if err != nil {
@@ -305,9 +306,30 @@ func TestUnixConnSpecificMethods(t *testing.T) {
 	defer c2.Close()
 	defer os.Remove(p2)
 
+	a3, err := net.ResolveUnixAddr("unixgram", p3)
+	if err != nil {
+		t.Errorf("net.ResolveUnixAddr failed: %v", err)
+		return
+	}
+	c3, err := net.ListenUnixgram("unixgram", a3)
+	if err != nil {
+		t.Errorf("net.ListenUnixgram failed: %v", err)
+		return
+	}
+	c3.LocalAddr()
+	c3.RemoteAddr()
+	c3.SetDeadline(time.Now().Add(100 * time.Millisecond))
+	c3.SetReadDeadline(time.Now().Add(100 * time.Millisecond))
+	c3.SetWriteDeadline(time.Now().Add(100 * time.Millisecond))
+	c3.SetReadBuffer(2048)
+	c3.SetWriteBuffer(2048)
+	defer c3.Close()
+	defer os.Remove(p3)
+
 	wb := []byte("UNIXCONN TEST")
 	rb1 := make([]byte, 128)
 	rb2 := make([]byte, 128)
+	rb3 := make([]byte, 128)
 	if _, _, err := c1.WriteMsgUnix(wb, nil, a2); err != nil {
 		t.Errorf("net.UnixConn.WriteMsgUnix failed: %v", err)
 		return
@@ -324,9 +346,22 @@ func TestUnixConnSpecificMethods(t *testing.T) {
 		t.Errorf("net.UnixConn.ReadFromUnix failed: %v", err)
 		return
 	}
-
-	// TODO: http://golang.org/issue/3875
-	net.ListenUnixgram("unixgram", nil)
+	if _, err := c3.WriteToUnix(wb, a1); err != nil {
+		t.Errorf("net.UnixConn.WriteToUnix failed: %v", err)
+		return
+	}
+	if _, _, err := c1.ReadFromUnix(rb1); err != nil {
+		t.Errorf("net.UnixConn.ReadFromUnix failed: %v", err)
+		return
+	}
+	if _, err := c2.WriteToUnix(wb, a3); err != nil {
+		t.Errorf("net.UnixConn.WriteToUnix failed: %v", err)
+		return
+	}
+	if _, _, err := c3.ReadFromUnix(rb3); err != nil {
+		t.Errorf("net.UnixConn.ReadFromUnix failed: %v", err)
+		return
+	}
 
 	if f, err := c1.File(); err != nil {
 		t.Errorf("net.UnixConn.File failed: %v", err)

src/pkg/net/unixsock_plan9.go

@@ -64,21 +64,21 @@ func (c *UnixConn) WriteMsgUnix(b, oob []byte, addr *UnixAddr) (n, oobn int, err
 	return 0, 0, syscall.EPLAN9
 }
 
-// CloseRead shuts down the reading side of the Unix domain
-// connection.  Most callers should just use Close.
+// CloseRead shuts down the reading side of the Unix domain connection.
+// Most callers should just use Close.
 func (c *UnixConn) CloseRead() error {
 	return syscall.EPLAN9
 }
 
-// CloseWrite shuts down the writing side of the Unix domain
-// connection.  Most callers should just use Close.
+// CloseWrite shuts down the writing side of the Unix domain connection.
+// Most callers should just use Close.
 func (c *UnixConn) CloseWrite() error {
 	return syscall.EPLAN9
 }
 
 // DialUnix connects to the remote address raddr on the network net,
-// which must be "unix" or "unixgram".  If laddr is not nil, it is
-// used as the local address for the connection.
+// which must be "unix", "unixgram" or "unixpacket".  If laddr is not
+// nil, it is used as the local address for the connection.
 func DialUnix(net string, laddr, raddr *UnixAddr) (*UnixConn, error) {
 	return dialUnix(net, laddr, raddr, noDeadline)
 }
@@ -93,7 +93,8 @@ func dialUnix(net string, laddr, raddr *UnixAddr, deadline time.Time) (*UnixConn
 type UnixListener struct{}
 
 // ListenUnix announces on the Unix domain socket laddr and returns a
-// Unix listener.  Net must be "unix" (stream sockets).
+// Unix listener.  The network net must be "unix", "unixgram" or
+// "unixpacket".
 func ListenUnix(net string, laddr *UnixAddr) (*UnixListener, error) {
 	return nil, syscall.EPLAN9
 }
@@ -134,8 +135,8 @@ func (l *UnixListener) File() (*os.File, error) {
 
 // ListenUnixgram listens for incoming Unix datagram packets addressed
 // to the local address laddr.  The returned connection c's ReadFrom
-// and WriteTo methods can be used to receive and send UDP packets
-// with per-packet addressing.  The network net must be "unixgram".
-func ListenUnixgram(net string, laddr *UnixAddr) (*UDPConn, error) {
+// and WriteTo methods can be used to receive and send packets with
+// per-packet addressing.  The network net must be "unixgram".
+func ListenUnixgram(net string, laddr *UnixAddr) (*UnixConn, error) {
 	return nil, syscall.EPLAN9
 }

src/pkg/net/unixsock_posix.go

@@ -9,29 +9,27 @@
 package net
 
 import (
+	"errors"
 	"os"
 	"syscall"
 	"time"
 )
 
-func unixSocket(net string, laddr, raddr *UnixAddr, mode string, deadline time.Time) (fd *netFD, err error) {
+func unixSocket(net string, laddr, raddr *UnixAddr, mode string, deadline time.Time) (*netFD, error) {
 	var sotype int
 	switch net {
-	default:
-		return nil, UnknownNetworkError(net)
 	case "unix":
 		sotype = syscall.SOCK_STREAM
 	case "unixgram":
 		sotype = syscall.SOCK_DGRAM
 	case "unixpacket":
 		sotype = syscall.SOCK_SEQPACKET
+	default:
+		return nil, UnknownNetworkError(net)
 	}
 
 	var la, ra syscall.Sockaddr
 	switch mode {
-	default:
-		panic("unixSocket mode " + mode)
-
 	case "dial":
 		if laddr != nil {
 			la = &syscall.SockaddrUnix{Name: laddr.Name}
@@ -41,15 +39,10 @@ func unixSocket(net string, laddr, raddr *UnixAddr, mode string, deadline time.T
 		} else if sotype != syscall.SOCK_DGRAM || laddr == nil {
 			return nil, &OpError{Op: mode, Net: net, Err: errMissingAddress}
 		}
-
 	case "listen":
-		if laddr == nil {
-			return nil, &OpError{mode, net, nil, errMissingAddress}
-		}
 		la = &syscall.SockaddrUnix{Name: laddr.Name}
-		if raddr != nil {
-			return nil, &OpError{Op: mode, Net: net, Addr: raddr, Err: &AddrError{Err: "unexpected remote address", Addr: raddr.String()}}
-		}
+	default:
+		return nil, errors.New("unknown mode: " + mode)
 	}
 
 	f := sockaddrToUnix
@@ -59,15 +52,16 @@ func unixSocket(net string, laddr, raddr *UnixAddr, mode string, deadline time.T
 		f = sockaddrToUnixpacket
 	}
 
-	fd, err = socket(net, syscall.AF_UNIX, sotype, 0, false, la, ra, deadline, f)
+	fd, err := socket(net, syscall.AF_UNIX, sotype, 0, false, la, ra, deadline, f)
 	if err != nil {
-		goto Error
+		goto error
 	}
 	return fd, nil
 
-Error:
+error:
 	addr := raddr
-	if mode == "listen" {
+	switch mode {
+	case "listen":
 		addr = laddr
 	}
 	return nil, &OpError{Op: mode, Net: net, Addr: addr, Err: err}
@@ -108,21 +102,21 @@ func sotypeToNet(sotype int) string {
 	return ""
 }
 
-// UnixConn is an implementation of the Conn interface
-// for connections to Unix domain sockets.
+// UnixConn is an implementation of the Conn interface for connections
+// to Unix domain sockets.
 type UnixConn struct {
 	conn
 }
 
 func newUnixConn(fd *netFD) *UnixConn { return &UnixConn{conn{fd}} }
 
-// ReadFromUnix reads a packet from c, copying the payload into b.
-// It returns the number of bytes copied into b and the source address
-// of the packet.
+// ReadFromUnix reads a packet from c, copying the payload into b.  It
+// returns the number of bytes copied into b and the source address of
+// the packet.
 //
-// ReadFromUnix can be made to time out and return
-// an error with Timeout() == true after a fixed time limit;
-// see SetDeadline and SetReadDeadline.
+// ReadFromUnix can be made to time out and return an error with
+// Timeout() == true after a fixed time limit; see SetDeadline and
+// SetReadDeadline.
 func (c *UnixConn) ReadFromUnix(b []byte) (n int, addr *UnixAddr, err error) {
 	if !c.ok() {
 		return 0, nil, syscall.EINVAL
@@ -144,12 +138,28 @@ func (c *UnixConn) ReadFrom(b []byte) (n int, addr Addr, err error) {
 	return n, uaddr.toAddr(), err
 }
 
+// ReadMsgUnix reads a packet from c, copying the payload into b and
+// the associated out-of-band data into oob.  It returns the number of
+// bytes copied into b, the number of bytes copied into oob, the flags
+// that were set on the packet, and the source address of the packet.
+func (c *UnixConn) ReadMsgUnix(b, oob []byte) (n, oobn, flags int, addr *UnixAddr, err error) {
+	if !c.ok() {
+		return 0, 0, 0, nil, syscall.EINVAL
+	}
+	n, oobn, flags, sa, err := c.fd.ReadMsg(b, oob)
+	switch sa := sa.(type) {
+	case *syscall.SockaddrUnix:
+		addr = &UnixAddr{sa.Name, sotypeToNet(c.fd.sotype)}
+	}
+	return
+}
+
 // WriteToUnix writes a packet to addr via c, copying the payload from b.
 //
-// WriteToUnix can be made to time out and return
-// an error with Timeout() == true after a fixed time limit;
-// see SetDeadline and SetWriteDeadline.
-// On packet-oriented connections, write timeouts are rare.
+// WriteToUnix can be made to time out and return an error with
+// Timeout() == true after a fixed time limit; see SetDeadline and
+// SetWriteDeadline.  On packet-oriented connections, write timeouts
+// are rare.
 func (c *UnixConn) WriteToUnix(b []byte, addr *UnixAddr) (n int, err error) {
 	if !c.ok() {
 		return 0, syscall.EINVAL
@@ -173,26 +183,9 @@ func (c *UnixConn) WriteTo(b []byte, addr Addr) (n int, err error) {
 	return c.WriteToUnix(b, a)
 }
 
-// ReadMsgUnix reads a packet from c, copying the payload into b
-// and the associated out-of-band data into oob.
-// It returns the number of bytes copied into b, the number of
-// bytes copied into oob, the flags that were set on the packet,
-// and the source address of the packet.
-func (c *UnixConn) ReadMsgUnix(b, oob []byte) (n, oobn, flags int, addr *UnixAddr, err error) {
-	if !c.ok() {
-		return 0, 0, 0, nil, syscall.EINVAL
-	}
-	n, oobn, flags, sa, err := c.fd.ReadMsg(b, oob)
-	switch sa := sa.(type) {
-	case *syscall.SockaddrUnix:
-		addr = &UnixAddr{sa.Name, sotypeToNet(c.fd.sotype)}
-	}
-	return
-}
-
-// WriteMsgUnix writes a packet to addr via c, copying the payload from b
-// and the associated out-of-band data from oob.  It returns the number
-// of payload and out-of-band bytes written.
+// WriteMsgUnix writes a packet to addr via c, copying the payload
+// from b and the associated out-of-band data from oob.  It returns
+// the number of payload and out-of-band bytes written.
 func (c *UnixConn) WriteMsgUnix(b, oob []byte, addr *UnixAddr) (n, oobn int, err error) {
 	if !c.ok() {
 		return 0, 0, syscall.EINVAL
@@ -226,13 +219,18 @@ func (c *UnixConn) CloseWrite() error {
 }
 
 // DialUnix connects to the remote address raddr on the network net,
-// which must be "unix" or "unixgram".  If laddr is not nil, it is used
-// as the local address for the connection.
+// which must be "unix", "unixgram" or "unixpacket".  If laddr is not
+// nil, it is used as the local address for the connection.
 func DialUnix(net string, laddr, raddr *UnixAddr) (*UnixConn, error) {
 	return dialUnix(net, laddr, raddr, noDeadline)
 }
 
 func dialUnix(net string, laddr, raddr *UnixAddr, deadline time.Time) (*UnixConn, error) {
+	switch net {
+	case "unix", "unixgram", "unixpacket":
+	default:
+		return nil, UnknownNetworkError(net)
+	}
 	fd, err := unixSocket(net, laddr, raddr, "dial", deadline)
 	if err != nil {
 		return nil, err
@@ -240,22 +238,25 @@ func dialUnix(net string, laddr, raddr *UnixAddr, deadline time.Time) (*UnixConn
 	return newUnixConn(fd), nil
 }
 
-// UnixListener is a Unix domain socket listener.
-// Clients should typically use variables of type Listener
-// instead of assuming Unix domain sockets.
+// UnixListener is a Unix domain socket listener.  Clients should
+// typically use variables of type Listener instead of assuming Unix
+// domain sockets.
 type UnixListener struct {
 	fd   *netFD
 	path string
 }
 
-// ListenUnix announces on the Unix domain socket laddr and returns a Unix listener.
-// Net must be "unix" (stream sockets).
+// ListenUnix announces on the Unix domain socket laddr and returns a
+// Unix listener.  The network net must be "unix", "unixgram" or
+// "unixpacket".
 func ListenUnix(net string, laddr *UnixAddr) (*UnixListener, error) {
-	if net != "unix" && net != "unixgram" && net != "unixpacket" {
+	switch net {
+	case "unix", "unixgram", "unixpacket":
+	default:
 		return nil, UnknownNetworkError(net)
 	}
-	if laddr != nil {
-		laddr = &UnixAddr{laddr.Name, net} // make our own copy
+	if laddr == nil {
+		return nil, &OpError{"listen", net, nil, errMissingAddress}
 	}
 	fd, err := unixSocket(net, laddr, nil, "listen", noDeadline)
 	if err != nil {
@@ -269,8 +270,8 @@ func ListenUnix(net string, laddr *UnixAddr) (*UnixListener, error) {
 	return &UnixListener{fd, laddr.Name}, nil
 }
 
-// AcceptUnix accepts the next incoming call and returns the new connection
-// and the remote address.
+// AcceptUnix accepts the next incoming call and returns the new
+// connection and the remote address.
 func (l *UnixListener) AcceptUnix() (*UnixConn, error) {
 	if l == nil || l.fd == nil {
 		return nil, syscall.EINVAL
@@ -283,8 +284,8 @@ func (l *UnixListener) AcceptUnix() (*UnixConn, error) {
 	return c, nil
 }
 
-// Accept implements the Accept method in the Listener interface;
-// it waits for the next call and returns a generic Conn.
+// Accept implements the Accept method in the Listener interface; it
+// waits for the next call and returns a generic Conn.
 func (l *UnixListener) Accept() (c Conn, err error) {
 	c1, err := l.AcceptUnix()
 	if err != nil {
@@ -293,8 +294,8 @@ func (l *UnixListener) Accept() (c Conn, err error) {
 	return c1, nil
 }
 
-// Close stops listening on the Unix address.
-// Already accepted connections are not closed.
+// Close stops listening on the Unix address.  Already accepted
+// connections are not closed.
 func (l *UnixListener) Close() error {
 	if l == nil || l.fd == nil {
 		return syscall.EINVAL
@@ -328,16 +329,16 @@ func (l *UnixListener) SetDeadline(t time.Time) (err error) {
 	return setDeadline(l.fd, t)
 }
 
-// File returns a copy of the underlying os.File, set to blocking mode.
-// It is the caller's responsibility to close f when finished.
+// File returns a copy of the underlying os.File, set to blocking
+// mode.  It is the caller's responsibility to close f when finished.
 // Closing l does not affect f, and closing f does not affect l.
 func (l *UnixListener) File() (f *os.File, err error) { return l.fd.dup() }
 
-// ListenUnixgram listens for incoming Unix datagram packets addressed to the
-// local address laddr.  The returned connection c's ReadFrom
-// and WriteTo methods can be used to receive and send UDP
-// packets with per-packet addressing.  The network net must be "unixgram".
-func ListenUnixgram(net string, laddr *UnixAddr) (*UDPConn, error) {
+// ListenUnixgram listens for incoming Unix datagram packets addressed
+// to the local address laddr.  The returned connection c's ReadFrom
+// and WriteTo methods can be used to receive and send packets with
+// per-packet addressing.  The network net must be "unixgram".
+func ListenUnixgram(net string, laddr *UnixAddr) (*UnixConn, error) {
 	switch net {
 	case "unixgram":
 	default:
@@ -350,5 +351,5 @@ func ListenUnixgram(net string, laddr *UnixAddr) (*UDPConn, error) {
 	if err != nil {
 		return nil, err
 	}
-	return newUDPConn(fd), nil
+	return newUnixConn(fd), nil
 }