[PATCH] sockaddr.3type: BUGS: Document that libc should be fixed using a union

[Alejandro Colomar <alx.manpages@xxxxxxxxx>]

As discussed before, and Bastien and I seem to agree, ideally we should
define the following types:

    struct sockaddr_storage {
        union {
            struct {
                sa_family_t      ss_family;
            };
            struct sockaddr_in   sin;
            struct sockaddr_in6  sin6;
            struct sockaddr_un   sun;
            // ...
        };
    };

    struct [[deprecated]] sockaddr {
        sa_family_t              sa_family;
    };

    union [[gnu::transparent_union]] sockaddr_ptr {
        struct sockaddr_storage  *ss;
        struct sockaddr          *sa;
    };

And then we could define APIs like:

    int bind(int sockfd, const union sockaddr_ptr *addr, socklen_t len);

Link: <https://lore.kernel.org/linux-man/ab492040-2058-bcbe-c920-a9088a20f071@xxxxxxxxx/T/#u>
Link: <https://inbox.sourceware.org/libc-alpha/20230120134043.10247-1-alx@xxxxxxxxxx/T/#u>
Cc: GCC <gcc@xxxxxxxxxxx>
Cc: glibc <libc-alpha@xxxxxxxxxxxxxx>
Cc: Bastien Roucariès <rouca@xxxxxxxxxx>
Cc: Stefan Puiu <stefan.puiu@xxxxxxxxx>
Cc: Igor Sysoev <igor@xxxxxxxxx>
Cc: Rich Felker <dalias@xxxxxxxx>
Cc: Andrew Clayton <a.clayton@xxxxxxxxx>
Cc: Richard Biener <richard.guenther@xxxxxxxxx>
Cc: Zack Weinberg <zack@xxxxxxxxxxxx>
Cc: Florian Weimer <fweimer@xxxxxxxxxx>
Cc: Joseph Myers <joseph@xxxxxxxxxxxxxxxx>
Cc: Jakub Jelinek <jakub@xxxxxxxxxx>
Cc: Eric Blake <eblake@xxxxxxxxxx>
Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
---
 man3type/sockaddr.3type | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/man3type/sockaddr.3type b/man3type/sockaddr.3type
index 319a5e552..239e836fc 100644
--- a/man3type/sockaddr.3type
+++ b/man3type/sockaddr.3type
@@ -120,6 +120,26 @@ .SH NOTES
 .I <netinet/in.h>
 and
 .IR <sys/un.h> .
+.SH BUGS
+.I sockaddr_storage
+was designed back when strict aliasing wasn't a problem.
+Back then,
+one would define a variable of that type,
+and then access it as any of the other
+.IR sockaddr_ *
+types,
+depending on the value of the first member.
+This is Undefined Behavior.
+However, there is no way to use these APIs without invoking Unedfined Behavior,
+either in the user program or in libc,
+so it is still recommended to use this method.
+The only correct way to use different types in an API is through a union.
+However,
+that union must be implemented in the library,
+since the type must be shared between the library and user code,
+so libc should be fixed by implementing
+.I sockaddr_storage
+as a union.
 .SH SEE ALSO
 .BR accept (2),
 .BR bind (2),
-- 
2.39.1