From 0afb3ad23f8ea09331f21a377e3ad19c44e4df18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <rouca@debian.org>
Date: Tue, 17 Jan 2023 10:07:43 +0000
Subject: [PATCH] Document use of struct sockaddr_storage in getsockname

Document:
- storage requierement
- future compatibility
---
 man2/getsockname.2 | 56 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/man2/getsockname.2 b/man2/getsockname.2
index e6e8980c9..5914c9e12 100644
--- a/man2/getsockname.2
+++ b/man2/getsockname.2
@@ -39,6 +39,17 @@ The returned address is truncated if the buffer provided is too small;
 in this case,
 .I addrlen
 will return a value greater than was supplied to the call.
+.PP
+For greater portability
+.I addr
+should point to a structure of type
+.I sockaddr_storage.
+.I sockaddr_storage
+structure is large enough to hold any of the other
+.I sockaddr_*
+variants and always well aligned. On return, it should be cast to the correct
+.I sockaddr_*
+type, according to the current protocol family, given by the member ss_family.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
@@ -80,10 +91,55 @@ For background on the
 .I socklen_t
 type, see
 .BR accept (2).
+.PP
+Security and portability wise, use of
+.I struct sockaddr_storage
+type as
+.I addr
+and
+.I addrlen
+set to
+.BI "sizeof(struct sockaddr_storage)"
+is strongly encouraged. Particularly this usage avoid bugs in dual stack IPv4+IPv6 configuration.
+.PP
+Historical use of
+.I addr
+requires one to use a structure specific to the protocol family in use,
+such as
+.I sockaddr_in
+(AF_INET or IPv4),
+.I sockaddr_in6
+(AF_INET6 or IPv6), or
+.I sockaddr_un
+(AF_UNIX)
+cast to a
+.I (struct sockaddr *).
+The purpose of the
+.I struct sockaddr *
+type
+is purely to allow casting of  domain-specific  socket  address  types  to  a
+"generic" type, so as to avoid compiler warnings about type mismatches in calls to the sockets API.
+Nevertheless,
+. I struct sockaddr *
+is too small to hold newer protocol address (for instance IPv6) and not always well aligned.
+.PP
+Even if
+.I sockaddr_storage
+type is large enough at compilation time to hold any of the
+.I sockaddr_*
+variants known by the library,
+this guarantee will not hold for future. Newer protocol may need an increase of
+.I sockaddr_storage
+size or alignement requirement, and safe program should always runtime check if returned
+.I addr
+is smaller or equal to compile time
+.BI "sizeof(struct sockaddr_storage)"
+size.
 .SH SEE ALSO
 .BR bind (2),
 .BR socket (2),
 .BR getifaddrs (3),
+.BR sockaddr_storage (3type),
 .BR ip (7),
 .BR socket (7),
 .BR unix (7)
-- 
2.39.0