net: document that user shouldn't modify returned Addr

Ideally, those methods should return a copy of the Addr, but
due to the Go 1 API guarantee, we cannot make that change now:
there might exist client code that uses the returned Addr as
map index and thus relies on the fact that different invocation
of the method returns the same pointer. Changing this behavior
will lead to hidden behaviour change in those programs.

Update #9654.

Change-Id: Iad4235f2ed7789b3a3c8e0993b9718cf0534ea2b
Reviewed-on: https://go-review.googlesource.com/3851
Reviewed-by: Mikio Hara <mikioh.mikioh@gmail.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/net/net.go b/src/net/net.go
index c850d2b1fdb26159fe977536c79b9e7da1735933..339c972906a6aa6e9b2faad1154db9be6f0642ff 100644 (file)
--- a/src/net/net.go
+++ b/src/net/net.go
@@ -135,6 +135,8 @@ func (c *conn) Close() error {
 }
 
 // LocalAddr returns the local network address.
+// The Addr returned is shared by all invocations of LocalAddr, so
+// do not modify it.
 func (c *conn) LocalAddr() Addr {
        if !c.ok() {
                return nil
@@ -143,6 +145,8 @@ func (c *conn) LocalAddr() Addr {
 }
 
 // RemoteAddr returns the remote network address.
+// The Addr returned is shared by all invocations of RemoteAddr, so
+// do not modify it.
 func (c *conn) RemoteAddr() Addr {
        if !c.ok() {
                return nil

diff --git a/src/net/tcpsock_plan9.go b/src/net/tcpsock_plan9.go
index 52019d7b4eb28e0522dac1f686742eb553ba70a6..ae2194277dfd38745ae2a38d61095a811fa726a4 100644 (file)
--- a/src/net/tcpsock_plan9.go
+++ b/src/net/tcpsock_plan9.go
@@ -157,6 +157,8 @@ func (l *TCPListener) Close() error {
 }
 
 // Addr returns the listener's network address, a *TCPAddr.
+// The Addr returned is shared by all invocations of Addr, so
+// do not modify it.
 func (l *TCPListener) Addr() Addr { return l.fd.laddr }
 
 // SetDeadline sets the deadline associated with the listener.

diff --git a/src/net/tcpsock_posix.go b/src/net/tcpsock_posix.go
index dd78aefa77317882a91cc4e80bee0cec8e962d59..aaff0acaa682c7749ad30f6fb4618911a41d7276 100644 (file)
--- a/src/net/tcpsock_posix.go
+++ b/src/net/tcpsock_posix.go
@@ -258,6 +258,8 @@ func (l *TCPListener) Close() error {
 }
 
 // Addr returns the listener's network address, a *TCPAddr.
+// The Addr returned is shared by all invocations of Addr, so
+// do not modify it.
 func (l *TCPListener) Addr() Addr { return l.fd.laddr }
 
 // SetDeadline sets the deadline associated with the listener.

diff --git a/src/net/unixsock_plan9.go b/src/net/unixsock_plan9.go
index c60c1d83bb31d7e1f50c99d142f63210f3aca6b3..64a511d6488b3c3d523d646b4fbe3f3d806b248b 100644 (file)
--- a/src/net/unixsock_plan9.go
+++ b/src/net/unixsock_plan9.go
@@ -115,6 +115,8 @@ func (l *UnixListener) Close() error {
 }
 
 // Addr returns the listener's network address.
+// The Addr returned is shared by all invocations of Addr, so
+// do not modify it.
 func (l *UnixListener) Addr() Addr { return nil }
 
 // SetDeadline sets the deadline associated with the listener.

diff --git a/src/net/unixsock_posix.go b/src/net/unixsock_posix.go
index 3c2e78bdca32502293f8f8f49886842b0044d1eb..d7127d9c690d14d51972c02b671ac431da762f91 100644 (file)
--- a/src/net/unixsock_posix.go
+++ b/src/net/unixsock_posix.go
@@ -321,6 +321,8 @@ func (l *UnixListener) Close() error {
 }
 
 // Addr returns the listener's network address.
+// The Addr returned is shared by all invocations of Addr, so
+// do not modify it.
 func (l *UnixListener) Addr() Addr { return l.fd.laddr }
 
 // SetDeadline sets the deadline associated with the listener.