From: Alejandro Colomar <alx@kernel.org>
Date: Fri, 13 Dec 2024 13:19:28 +0000 (+0100)
Subject: man/: SYNOPSIS: Use typeof() to improve readability of function pointer types
X-Git-Tag: man-pages-6.10~58
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a4a669ba33d51864b664d53db593f9f6c51ad610;p=thirdparty%2Fman-pages.git

man/: SYNOPSIS: Use typeof() to improve readability of function pointer types

Suggested-by: Jorenar <dev@jorenar.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

diff --git a/man/man2/clone.2 b/man/man2/clone.2
index 88e792257..9428a5645 100644
--- a/man/man2/clone.2
+++ b/man/man2/clone.2
@@ -51,12 +51,13 @@ Standard C library
 .B #define _GNU_SOURCE
 .B #include <sched.h>
 .P
-.BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \
-", int " flags ,
-.BI "          void *_Nullable " "arg" ", ..." \
-"  \fR/*\fP" " pid_t *_Nullable " parent_tid ,
-.BI "                                       void *_Nullable " tls ,
-.BI "                                       pid_t *_Nullable " child_tid " \fR*/\fP );"
+.BI "int clone(typeof(int (void *_Nullable)) *" fn ,
+.BI "          void *" stack ,
+.BI "          int " flags ,
+.BI "          void *_Nullable " arg ", ..."
+.BI "          \f[R]/*\f[] pid_t *_Nullable " parent_tid ,
+.BI "             void *_Nullable " tls ,
+.BI "             pid_t *_Nullable " child_tid " \f[R]*/\f[] );"
 .P
 /* For the prototype of the raw clone() system call, see VERSIONS. */
 .P
diff --git a/man/man2/signal.2 b/man/man2/signal.2
index 22526e942..b4ac3922a 100644
--- a/man/man2/signal.2
+++ b/man/man2/signal.2
@@ -23,7 +23,7 @@ Standard C library
 .nf
 .B #include <signal.h>
 .P
-.B typedef void (*sighandler_t)(int);
+.B "typedef typeof(void (int))  *sighandler_t;"
 .P
 .BI "sighandler_t signal(int " signum ", sighandler_t " handler );
 .fi
diff --git a/man/man3/atexit.3 b/man/man3/atexit.3
index ab2e916f7..f35d26807 100644
--- a/man/man3/atexit.3
+++ b/man/man3/atexit.3
@@ -21,7 +21,7 @@ Standard C library
 .nf
 .B #include <stdlib.h>
 .P
-.BI "int atexit(void (*" function )(void));
+.BI "int atexit(typeof(void (void)) *" function );
 .fi
 .SH DESCRIPTION
 The
diff --git a/man/man3/bsd_signal.3 b/man/man3/bsd_signal.3
index 0f859f908..face18609 100644
--- a/man/man3/bsd_signal.3
+++ b/man/man3/bsd_signal.3
@@ -13,7 +13,7 @@ Standard C library
 .nf
 .B #include <signal.h>
 .P
-.B typedef void (*sighandler_t)(int);
+.B "typedef typeof(void (int))  *sighandler_t;"
 .P
 .BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler );
 .fi
diff --git a/man/man3/bsearch.3 b/man/man3/bsearch.3
index 23e864c5c..40c719e36 100644
--- a/man/man3/bsearch.3
+++ b/man/man3/bsearch.3
@@ -22,8 +22,8 @@ Standard C library
 .BI "void *bsearch(const void " key [. size "], \
 const void " base [. size " * ." n ],
 .BI "              size_t " n ", size_t " size ,
-.BI "              int (*" compar ")(const void [." size "], \
-const void [." size ]));
+.BI "              typeof(int (const void [." size "], const void [." size ]))
+.BI "                  *" compar );
 .fi
 .SH DESCRIPTION
 The
diff --git a/man/man3/dl_iterate_phdr.3 b/man/man3/dl_iterate_phdr.3
index c19b3172a..082a130cf 100644
--- a/man/man3/dl_iterate_phdr.3
+++ b/man/man3/dl_iterate_phdr.3
@@ -15,9 +15,9 @@ Standard C library
 .B #include <link.h>
 .P
 .B int dl_iterate_phdr(
-.BI "          int (*" callback ")(struct dl_phdr_info *" info ,
-.BI "                          size_t " size ", void *" data ),
-.BI "          void *" data );
+.BI "         typeof(int (struct dl_phdr_info *" info ", size_t " size ", void *" data ))
+.BI "             *" callback ,
+.BI "         void *" data );
 .fi
 .SH DESCRIPTION
 The
diff --git a/man/man3/error.3 b/man/man3/error.3
index 44853d1d3..0e081560e 100644
--- a/man/man3/error.3
+++ b/man/man3/error.3
@@ -43,7 +43,7 @@ Standard C library
 .BI "extern unsigned int " error_message_count ;
 .BI "extern int " error_one_per_line ;
 .P
-.BI "extern void (*" error_print_progname ")(void);"
+.BI "extern typeof(void (void))  *" error_print_progname ;
 .fi
 .SH DESCRIPTION
 .BR error ()
diff --git a/man/man3/fts.3 b/man/man3/fts.3
index 7c3f08595..c2f2dd5b2 100644
--- a/man/man3/fts.3
+++ b/man/man3/fts.3
@@ -24,7 +24,8 @@ Standard C library
 .B #include <fts.h>
 .P
 .BI "FTS *fts_open(char *const *" path_argv ", int " options ,
-.BI "              int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));"
+.B  "              typeof(int (const FTSENT **, const FTSENT **))"
+.BI "                  *_Nullable " compar );
 .P
 .BI "FTSENT *fts_read(FTS *" ftsp );
 .P
diff --git a/man/man3/ftw.3 b/man/man3/ftw.3
index f2d45233f..71d6bd40b 100644
--- a/man/man3/ftw.3
+++ b/man/man3/ftw.3
@@ -26,14 +26,16 @@ Standard C library
 .B #include <ftw.h>
 .P
 .BI "int nftw(const char *" dirpath ,
-.BI "        int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
-.BI "                  int " typeflag ", struct FTW *" ftwbuf ),
+.BI "        typeof(int (const char *" fpath ", const struct stat *" sb,
+.BI "                    int " typeflag ", struct FTW *" ftwbuf ))
+.BI "            *" fn,
 .BI "        int " nopenfd ", int " flags );
 .P
 .B [[deprecated]]
 .BI "int ftw(const char *" dirpath ,
-.BI "        int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
-.BI "                  int " typeflag ),
+.BI "        typeof(int (const char *" fpath ", const struct stat *" sb ,
+.BI "                    int " typeflag ))
+.BI "            *" fn,
 .BI "        int " nopenfd );
 .fi
 .P
diff --git a/man/man3/glob.3 b/man/man3/glob.3
index 42d4cbc87..d1a916f9e 100644
--- a/man/man3/glob.3
+++ b/man/man3/glob.3
@@ -23,7 +23,7 @@ Standard C library
 .B #include <glob.h>
 .P
 .BI "int glob(const char *restrict " pattern ", int " flags ,
-.BI "         int (*" errfunc ")(const char *" epath ", int " eerrno ),
+.BI "         typeof(int (const char *" epath ", int " eerrno ")) *" errfunc ,
 .BI "         glob_t *restrict " pglob );
 .BI "void globfree(glob_t *" pglob );
 .fi
diff --git a/man/man3/gsignal.3 b/man/man3/gsignal.3
index d87d9e494..5422945d3 100644
--- a/man/man3/gsignal.3
+++ b/man/man3/gsignal.3
@@ -15,7 +15,7 @@ Standard C library
 .nf
 .B #include <signal.h>
 .P
-.B typedef void (*sighandler_t)(int);
+.B "typedef typeof(void (int))  *sighandler_t;"
 .P
 .BI "[[deprecated]] int gsignal(int " signum );
 .P
diff --git a/man/man3/lsearch.3 b/man/man3/lsearch.3
index dc18d8bf8..0dfda7bd4 100644
--- a/man/man3/lsearch.3
+++ b/man/man3/lsearch.3
@@ -17,13 +17,13 @@ Standard C library
 .BI "void *lfind(const void " key [. size "], \
 const void " base [*. n " * ." size ],
 .BI "            size_t *" n ", size_t " size ,
-.BI "            int(*" compar ")(const void [." size "], \
-const void [." size ]));
+.BI "            typeof(int (const void [." size "], const void [." size ]))
+.BI "                *" compar );
 .BI "void *lsearch(const void " key [. size "], \
 void " base [*. n " * ." size ],
 .BI "            size_t *" n ", size_t " size ,
-.BI "            int(*" compar ")(const void [." size "], \
-const void [." size ]));
+.BI "            typeof(int (const void [." size "], const void [." size ]))
+.BI "                *" compar );
 .fi
 .SH DESCRIPTION
 .BR lfind ()
diff --git a/man/man3/makecontext.3 b/man/man3/makecontext.3
index 24cf78d70..45009a7a6 100644
--- a/man/man3/makecontext.3
+++ b/man/man3/makecontext.3
@@ -16,7 +16,7 @@ Standard C library
 .nf
 .B #include <ucontext.h>
 .P
-.BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(int " arg0 ", ...),"
+.BI "void makecontext(ucontext_t *" ucp ", typeof(void (int " arg0 ", ...)) *" func ,
 .BI "                 int " argc ", ...);"
 .BI "int swapcontext(ucontext_t *restrict " oucp ,
 .BI "                 const ucontext_t *restrict " ucp );
diff --git a/man/man3/malloc_hook.3 b/man/man3/malloc_hook.3
index ea50328af..afb253ea2 100644
--- a/man/man3/malloc_hook.3
+++ b/man/man3/malloc_hook.3
@@ -17,19 +17,20 @@ Standard C library
 .nf
 .B "#include <malloc.h>"
 .P
-.BI "void *(*volatile __malloc_hook)(size_t " size ", const void *" caller );
+.BI "typeof(void *(size_t " size ", const void *" caller ))
+.B  "    *volatile  __malloc_hook;"
 .P
-.BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size ,
-.BI "                         const void *" caller );
+.BI "typeof(void *(void *" p ", size_t " size ", const void *" caller ))
+.B  "    *volatile  __realloc_hook;"
 .P
-.BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size ,
-.BI "                         const void *" caller );
+.BI "typeof(void *(size_t " align ", size_t " size ", const void *" caller ))
+.B  "    *volatile  __memalign_hook;"
 .P
-.BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller );
+.BI "typeof(void *(void *" p ", const void *" caller ))
+.B  "    *volatile  __free_hook;"
 .P
-.B "void (*__malloc_initialize_hook)(void);"
-.P
-.B "void (*volatile __after_morecore_hook)(void);"
+.B "typeof(void (void))            *__malloc_initialize_hook;"
+.B "typeof(void (void)) *volatile   __after_mrecore_hook;"
 .fi
 .SH DESCRIPTION
 The GNU C library lets you modify the behavior of
diff --git a/man/man3/mcheck.3 b/man/man3/mcheck.3
index bd9816bc6..6e87cbe1f 100644
--- a/man/man3/mcheck.3
+++ b/man/man3/mcheck.3
@@ -13,8 +13,9 @@ Standard C library
 .nf
 .B #include <mcheck.h>
 .P
-.BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus ));
-.BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus ));
+.BI "int mcheck(typeof(void (enum mcheck_status " mstatus ")) *" abortfunc );
+.B  "int mcheck_pedantic("
+.BI "           typeof(void (enum mcheck_status " mstatus ")) *" abortfunc );
 .B void mcheck_check_all(void);
 .P
 .BI "enum mcheck_status mprobe(void *" ptr );
diff --git a/man/man3/mpool.3 b/man/man3/mpool.3
index f2e19a06d..ef2d0ede6 100644
--- a/man/man3/mpool.3
+++ b/man/man3/mpool.3
@@ -20,8 +20,9 @@ Standard C library
 .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \
 ", pgno_t " maxcache );
 .P
-.BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *),"
-.BI "                  void (*" pgout ")(void *, pgno_t, void *),"
+.BI "void mpool_filter(MPOOL *" mp ,
+.BI "                  typeof(void (void *, pgno_t, void *)) *" pgin ,
+.BI "                  typeof(void (void *, pgno_t, void *)) *" pgout ,
 .BI "                  void *" pgcookie );
 .P
 .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr );
diff --git a/man/man3/on_exit.3 b/man/man3/on_exit.3
index 22bbb2c6f..38df621e4 100644
--- a/man/man3/on_exit.3
+++ b/man/man3/on_exit.3
@@ -19,7 +19,7 @@ Standard C library
 .nf
 .B #include <stdlib.h>
 .P
-.BI "int on_exit(void (*" function ")(int, void *), void *" arg );
+.BI "int on_exit(typeof(void (int, void *)) *" function ", void *" arg );
 .fi
 .P
 .RS -4
diff --git a/man/man3/pthread_atfork.3 b/man/man3/pthread_atfork.3
index 156f565dd..2f2cbfe23 100644
--- a/man/man3/pthread_atfork.3
+++ b/man/man3/pthread_atfork.3
@@ -12,8 +12,9 @@ POSIX threads library
 .nf
 .B  #include <pthread.h>
 .P
-.BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void),"
-.BI "                   void (*" child ")(void));"
+.BI "int pthread_atfork(typeof(void (void)) *" prepare ,
+.BI "                   typeof(void (void)) *" parent ,
+.BI "                   typeof(void (void)) *" child );
 .fi
 .SH DESCRIPTION
 The
diff --git a/man/man3/pthread_cleanup_push.3 b/man/man3/pthread_cleanup_push.3
index d5fd39486..6cc80cd22 100644
--- a/man/man3/pthread_cleanup_push.3
+++ b/man/man3/pthread_cleanup_push.3
@@ -15,7 +15,7 @@ POSIX threads library
 .nf
 .B #include <pthread.h>
 .P
-.BI "void pthread_cleanup_push(void (*" routine ")(void *), void *" arg );
+.BI "void pthread_cleanup_push(typeof(void (void *)) *" routine ", void *" arg );
 .BI "void pthread_cleanup_pop(int " execute );
 .fi
 .SH DESCRIPTION
diff --git a/man/man3/pthread_cleanup_push_defer_np.3 b/man/man3/pthread_cleanup_push_defer_np.3
index 3535f01f8..6c69a34fc 100644
--- a/man/man3/pthread_cleanup_push_defer_np.3
+++ b/man/man3/pthread_cleanup_push_defer_np.3
@@ -14,7 +14,8 @@ POSIX threads library
 .nf
 .B #include <pthread.h>
 .P
-.BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *), void *" arg );
+.BI "void pthread_cleanup_push_defer_np(typeof(void (void *)) *" routine ,
+.BI "                                   void *" arg );
 .BI "void pthread_cleanup_pop_restore_np(int " execute );
 .fi
 .P
diff --git a/man/man3/pthread_create.3 b/man/man3/pthread_create.3
index 96c229e7e..22926990e 100644
--- a/man/man3/pthread_create.3
+++ b/man/man3/pthread_create.3
@@ -16,7 +16,7 @@ POSIX threads library
 .P
 .BI "int pthread_create(pthread_t *restrict " thread ,
 .BI "                   const pthread_attr_t *restrict " attr ,
-.BI "                   void *(*" start_routine ")(void *),"
+.BI "                   typeof(void *(void *)) *" start_routine ,
 .BI "                   void *restrict " arg );
 .fi
 .SH DESCRIPTION
diff --git a/man/man3/qsort.3 b/man/man3/qsort.3
index 2ff1d3d32..afc560824 100644
--- a/man/man3/qsort.3
+++ b/man/man3/qsort.3
@@ -27,12 +27,12 @@ Standard C library
 .P
 .BI "void qsort(void " base [. size " * ." n "], size_t " n ", \
 size_t " size ,
-.BI "           int (*" compar ")(const void [." size "], \
-const void [." size ]));
+.BI "           typeof(int (const void [." size "], const void [." size "]))"
+.BI "               *" compar );
 .BI "void qsort_r(void " base [. size " * ." n "], size_t " n ", \
 size_t " size ,
-.BI "           int (*" compar ")(const void [." size "], \
-const void [." size "], void *),"
+.BI "           typeof(int (const void [." size "], const void [." size "], void *))"
+.BI "               *" compar ,
 .BI "           void *" arg ");"
 .fi
 .P
diff --git a/man/man3/scandir.3 b/man/man3/scandir.3
index 8e1833fdc..04793faba 100644
--- a/man/man3/scandir.3
+++ b/man/man3/scandir.3
@@ -34,9 +34,9 @@ Standard C library
 .P
 .BI "int scandir(const char *restrict " dirp ,
 .BI "            struct dirent ***restrict " namelist ,
-.BI "            int (*" filter ")(const struct dirent *),"
-.BI "            int (*" compar ")(const struct dirent **,"
-.B "                          const struct dirent **));"
+.BI "            typeof(int (const struct dirent *)) *" filter ,
+.B  "            typeof(int (const struct dirent **, const struct dirent **))"
+.BI "                *" compar );
 .P
 .BI "int alphasort(const struct dirent **" a ", const struct dirent **" b );
 .BI "int versionsort(const struct dirent **" a ", const struct dirent **" b );
@@ -46,9 +46,9 @@ Standard C library
 .P
 .BI "int scandirat(int " dirfd ", const char *restrict " dirp ,
 .BI "            struct dirent ***restrict " namelist ,
-.BI "            int (*" filter ")(const struct dirent *),"
-.BI "            int (*" compar ")(const struct dirent **,"
-.B "                          const struct dirent **));"
+.BI "            typeof(int (const struct dirent *)) *" filter ,
+.B  "            typeof(int (const struct dirent **, const struct dirent **))"
+.BI "                *" compar );
 .fi
 .P
 .RS -4
diff --git a/man/man3/sigset.3 b/man/man3/sigset.3
index c5be34d51..3495373cf 100644
--- a/man/man3/sigset.3
+++ b/man/man3/sigset.3
@@ -13,7 +13,7 @@ Standard C library
 .nf
 .B #include <signal.h>
 .P
-.B typedef void (*sighandler_t)(int);
+.B "typedef typeof(void (int))  *sighandler_t;"
 .P
 .BI "[[deprecated]] sighandler_t sigset(int " sig ", sighandler_t " disp );
 .P
diff --git a/man/man3/sysv_signal.3 b/man/man3/sysv_signal.3
index 27bb179f6..c51a64598 100644
--- a/man/man3/sysv_signal.3
+++ b/man/man3/sysv_signal.3
@@ -14,7 +14,7 @@ Standard C library
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <signal.h>
 .P
-.B typedef void (*sighandler_t)(int);
+.B "typedef typeof(void (int))  *sighandler_t;"
 .P
 .BI "sighandler_t sysv_signal(int " signum ", sighandler_t " handler );
 .fi
diff --git a/man/man3/tsearch.3 b/man/man3/tsearch.3
index cec543f5f..f314461f2 100644
--- a/man/man3/tsearch.3
+++ b/man/man3/tsearch.3
@@ -15,24 +15,25 @@ Standard C library
 .P
 .B typedef enum { preorder, postorder, endorder, leaf } VISIT;
 .P
-.BI "void *tsearch(const void *" key ", void **" rootp ,
-.BI "                int (*" compar ")(const void *, const void *));"
 .BI "void *tfind(const void *" key ", void *const *" rootp ,
-.BI "                int (*" compar ")(const void *, const void *));"
+.BI "            typeof(int (const void *, const void *)) *" compar );
+.BI "void *tsearch(const void *" key ", void **" rootp ,
+.BI "            typeof(int (const void *, const void *)) *" compar );
 .BI "void *tdelete(const void *restrict " key ", void **restrict " rootp ,
-.BI "                int (*" compar ")(const void *, const void *));"
+.BI "            typeof(int (const void *, const void *)) *" compar );
 .BI "void twalk(const void *" root ,
-.BI "                void (*" action ")(const void *" nodep ", VISIT " which ,
-.BI "                               int " depth ));
+.BI "            typeof(void (const void *" nodep ", VISIT " which ", int " depth ))
+.BI "                *" action );
 .P
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <search.h>
 .P
 .BI "void twalk_r(const void *" root ,
-.BI "                void (*" action ")(const void *" nodep ", VISIT " which ,
-.BI "                               void *" closure ),
-.BI "                void *" closure );
-.BI "void tdestroy(void *" root ", void (*" free_node ")(void *" nodep ));
+.BI "            typeof(void (const void *" nodep ", VISIT " which ", void *" closure ))
+.BI "                *" action ,
+.BI "            void *" closure );
+.BI "void tdestroy(void *" root ,
+.BI "            typeof(void (void *" nodep ")) *" free_node );
 .fi
 .SH DESCRIPTION
 .BR tsearch (),
diff --git a/man/man3type/sigevent.3type b/man/man3type/sigevent.3type
index 01ca76620..f3f66a8c2 100644
--- a/man/man3type/sigevent.3type
+++ b/man/man3type/sigevent.3type
@@ -16,7 +16,7 @@ sigevent, sigval \- structure for notification from asynchronous routines
 .BR "    int             sigev_signo;" "   /* Signal number */"
 .BR "    union sigval    sigev_value;" "   /* Data passed with notification */"
 \&
-.B  "    void          (*sigev_notify_function)(union sigval);"
+.B  "    typeof(void (union sigval))  *sigev_notify_function;"
 .BR "                                " "   /* Notification function"
 .BR "                                " "      (SIGEV_THREAD) */"
 .B  "    pthread_attr_t *sigev_notify_attributes;"