_Generic.3: EXAMPLES: Add sockaddr_cast() macro

This macro is an example of how C++-style casts can be implemented in C.
They are better than C's casts because they only allow certain
conversions, while disallowing most.  This adds considerable type
safety.  They also make code more greppable.

A macro similar to const_cast() can also be implemented in a similar
manner:

 /* This code is in the public domain. */

 #define qual_cast(t, p)                               \
    _Generic(typeof_unqual(&*(p)),                     \
    typeof_unqual(t):                                  \
        _Generic(&*(p),                                \
        const t:          (t) (p),                     \
        volatile t:       (t) (p),                     \
        const volatile t: (t) (p),                     \
        default:              (p))                     \
    default:                                           \
        (p)                                            \
    )

Note that typeof_unqual() is yet unsupported by GCC and Clang, and will
be added to C23.  Similar behavior can be achieved by combining GNU
builtins.

Cc: Andrew Clayton <andrew@digital-domain.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man3/_Generic.3 b/man3/_Generic.3
index ddee5f6c4c54a4f839a98c44aac3cf4b5ef3e884..6ff5e24ea76a871fb3fb1c9f510ead406bdb58a6 100644 (file)
--- a/man3/_Generic.3
+++ b/man3/_Generic.3
@@ -27,12 +27,101 @@ that will behave differently depending on the type of the argument.
 .SH STANDARDS
 C11 and later.
 .SH EXAMPLES
+The following code demonstrates how to write
+a macro similar to C++'s
+.BR \%static_cast (),
+which will allow casting safely between a limited set of types.
+It is useful for example when calling
+system calls or library functions that use compatible structures,
+like for example
+.BR bind (2)
+with
+.BR \%sockaddr (3type).
+.IP
+.EX
+/* This code is in the public domain. */
+
+#include <netinet/in.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+
+#define sockaddr_cast(t, p)                            \e
+    _Generic(&*(p),                                    \e
+    struct sockaddr *:                                 \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr_in *:             (t) (p),     \e
+        struct sockaddr_in6 *:            (t) (p),     \e
+        struct sockaddr_un *:             (t) (p),     \e
+        default:                              (p)),    \e
+    struct sockaddr **:                                \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr_in **:            (t) (p),     \e
+        struct sockaddr_in6 **:           (t) (p),     \e
+        struct sockaddr_un **:            (t) (p),     \e
+        default:                              (p)),    \e
+    const struct sockaddr *:                           \e
+        _Generic((t) NULL,                             \e
+        const struct sockaddr_in *:       (t) (p),     \e
+        const struct sockaddr_in6 *:      (t) (p),     \e
+        const struct sockaddr_un *:       (t) (p),     \e
+        default:                              (p)),    \e
+                                                       \e
+    struct sockaddr_in *:                              \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr *:                (t) (p),     \e
+        default:                              (p)),    \e
+    struct sockaddr_in **:                             \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr **:               (t) (p),     \e
+        default:                              (p)),    \e
+    const struct sockaddr_in *:                        \e
+        _Generic((t) NULL,                             \e
+        const struct sockaddr *:          (t) (p),     \e
+        default:                              (p)),    \e
+                                                       \e
+    struct sockaddr_in6 *:                             \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr *:                (t) (p),     \e
+        default:                              (p)),    \e
+    struct sockaddr_in6 **:                            \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr **:               (t) (p),     \e
+        default:                              (p)),    \e
+    const struct sockaddr_in6 *:                       \e
+        _Generic((t) NULL,                             \e
+        const struct sockaddr *:          (t) (p),     \e
+        default:                              (p)),    \e
+                                                       \e
+    struct sockaddr_un *:                              \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr *:                (t) (p),     \e
+        default:                              (p)),    \e
+    struct sockaddr_un **:                             \e
+        _Generic((typeof_unqual(t)) NULL,              \e
+        struct sockaddr **:               (t) (p),     \e
+        default:                              (p)),    \e
+    const struct sockaddr_un *:                        \e
+        _Generic((t) NULL,                             \e
+        const struct sockaddr *:          (t) (p),     \e
+        default:                              (p)),    \e
+                                                       \e
+    default:                                           \e
+        (p)                                            \e
+    )
+
+socklen_t           slen;
+struct sockaddr_un  sun;
+
+slen = sizeof(ss);
+getsockname(sfd, sockaddr_cast(struct sockaddr *, &sun), &slen);
+.EE
+.PP
 The following program demonstrates how to write
 a replacement for the standard
 .BR imaxabs (3)
 function, which being a function can't really provide what it promises:
 seamlessly upgrading to the widest available type.
-.PP
+.IP
 .\" SRC BEGIN (_Generic.c)
 .EX
 #include <stdint.h>