Rollup merge of #83524 - faern:document-socketaddr-mem-layout, r=sfackler

Document that the SocketAddr memory representation is not stable

Intended to help out with #78802. Work has been put into finding and fixing code that assumes the memory layout of `SocketAddrV4` and `SocketAddrV6`. But it turns out there are cases where new code continues to make the same assumption ([example](https://github.com/spacejam/seaslug/commit/96927dc2b7b918860a79c4eb6336051e52c6137a#diff-917db3d8ca6f862ebf42726b23c72a12b35e584e497ebdb24e474348d7c6ffb6R610-R621)).

The memory layout of a type in `std` is never part of the public API. Unless explicitly stated I guess. But since that is invalidly relied upon by a considerable amount of code for these particular types, it might make sense to explicitly document this. This can be temporary. Once #78802 lands it does not make sense to rely on the layout any longer, and this documentation can also be removed.

1 files changed, 8 insertions, 2 deletions

diff --git a/library/std/src/net/addr.rs b/library/std/src/net/addr.rs
index 63de8712834..55546a5b037 100644
--- a/library/std/src/net/addr.rs
+++ b/library/std/src/net/addr.rs
@@ -57,7 +57,8 @@ pub enum SocketAddr {
 /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
 ///
 /// The size of a `SocketAddrV4` struct may vary depending on the target operating
-/// system.
+/// system. Do not assume that this type has the same memory layout as the underlying
+/// system representation.
 ///
 /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
 /// [`IPv4` address]: Ipv4Addr
@@ -76,6 +77,8 @@ pub enum SocketAddr {
 #[derive(Copy)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct SocketAddrV4 {
+    // Do not assume that this struct is implemented as the underlying system representation.
+    // The memory layout is not part of the stable interface that std exposes.
     inner: c::sockaddr_in,
 }
 
@@ -88,7 +91,8 @@ pub struct SocketAddrV4 {
 /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
 ///
 /// The size of a `SocketAddrV6` struct may vary depending on the target operating
-/// system.
+/// system. Do not assume that this type has the same memory layout as the underlying
+/// system representation.
 ///
 /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
 /// [`IPv6` address]: Ipv6Addr
@@ -107,6 +111,8 @@ pub struct SocketAddrV4 {
 #[derive(Copy)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct SocketAddrV6 {
+    // Do not assume that this struct is implemented as the underlying system representation.
+    // The memory layout is not part of the stable interface that std exposes.
     inner: c::sockaddr_in6,
 }