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>

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

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.

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.

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.

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.