Hi Chris, Martin, Joseph,

I'm patching the Linux man-pages project to use forward-declaration
syntax --I'm following Chris's model, (,,,;,,,)--, insted of the
[.identifier] syntax I was using.

I've come up with some pages that need special attention, to make sure
that the standard wording supports them.  I think it doesn, but we
better make sure.

getsockopt(2) needs to forward declare a pointer, because the function
updates the size.  Also, the pointer is restrict-qualified, so the
qualifiers should match in the forward declaration and the actual
parameter.

gethostbyaddr_r(3) is one case where I've had to forward-declare more
than one parameter.

Joseph, I hope you'll be happy that I'm doing this change?  Should I put
you as Reported-by as you complained about the syntax I'm replacing?


Have a lovely day!
Alex


$ git diff -- man2/getsockopt.2

diff --git i/man/man2/getsockopt.2 w/man/man2/getsockopt.2
index e4f47662c..c79894b14 100644
--- i/man/man2/getsockopt.2
+++ w/man/man2/getsockopt.2

@@ -23,11 +23,13 @@ .SH SYNOPSIS
 .nf
 .B #include <sys/socket.h>
 .P
-.BI "int getsockopt(int " sockfd ", int " level ", int " optname ,
-.BI "               void " optval "[restrict *." optlen ],
+.BI "int getsockopt(socklen *restrict " optlen ;
+.BI "               int " sockfd ", int " level ", int " optname ,
+.BI "               void " optval "[restrict *" optlen ],
 .BI "               socklen_t *restrict " optlen );
-.BI "int setsockopt(int " sockfd ", int " level ", int " optname ,
-.BI "               const void " optval [. optlen ],
+.BI "int setsockopt(socklen_t " optlen ;
+.BI "               int " sockfd ", int " level ", int " optname ,
+.BI "               const void " optval [ optlen ],
 .BI "               socklen_t " optlen );
 .fi
 .SH DESCRIPTION

$ mansect SYNOPSIS man2/getsockopt.2 | MANWIDTH=72 man /dev/stdin | cat;
getsockopt(2)             System Calls Manual             getsockopt(2)

SYNOPSIS
     #include <sys/socket.h>

     int getsockopt(socklen *restrict optlen;
                    int sockfd, int level, int optname,
                    void optval[restrict *optlen],
                    socklen_t *restrict optlen);
     int setsockopt(socklen_t optlen;
                    int sockfd, int level, int optname,
                    const void optval[optlen],
                    socklen_t optlen);

Linux man‐pages (unreleased)     (date)                   getsockopt(2)


$ git diff -- man3/gethostbyname.3

diff --git i/man/man3/gethostbyname.3 w/man/man3/gethostbyname.3
index 690a3b82e..a1cb8f129 100644
--- i/man/man3/gethostbyname.3
+++ w/man/man3/gethostbyname.3

@@ -37,7 +37,8 @@ .SH SYNOPSIS
 .B [[deprecated]] extern int h_errno;
 .P
 .BI "[[deprecated]] struct hostent *gethostbyname(const char *" name );
-.BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. size ],
+.BI "[[deprecated]] struct hostent *gethostbyaddr(socklen_t " size ;
+.BI "                                             const void " addr [ size ],
 .BI "                                             socklen_t " size ", int " type );
 .P
 .BI "[[deprecated]] void herror(const char *" s );

@@ -50,28 +51,32 @@ .SH SYNOPSIS
 .B [[deprecated]]
 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
 .P
-.BI "int gethostent_r(struct hostent *restrict " ret ,
-.BI "                 char " buf "[restrict ." bufsize "], size_t " bufsize ,
+.BI "int gethostent_r(size_t " bufsize ;
+.BI "                 struct hostent *restrict " ret ,
+.BI "                 char " buf "[restrict " bufsize "], size_t " bufsize ,
 .BI "                 struct hostent **restrict " result ,
 .BI "                 int *restrict " h_errnop );
 .P
 .B [[deprecated]]
-.BI "int gethostbyaddr_r(const void " addr "[restrict ." size "], socklen_t " size ,
+.BI "int gethostbyaddr_r(socklen_t " size ", size_t " bufsize ;
+.BI "                 const void " addr "[restrict " size "], socklen_t " size ,
 .BI "                 int " type ,
 .BI "                 struct hostent *restrict " ret ,
-.BI "                 char " buf "[restrict ." bufsize "], size_t " bufsize ,
+.BI "                 char " buf "[restrict " bufsize "], size_t " bufsize ,
 .BI "                 struct hostent **restrict " result ,
 .BI "                 int *restrict " h_errnop );
 .B [[deprecated]]
-.BI "int gethostbyname_r(const char *restrict " name ,
+.BI "int gethostbyname_r(size_t " bufsize ;
+.BI "                 const char *restrict " name ,
 .BI "                 struct hostent *restrict " ret ,
-.BI "                 char " buf "[restrict ." bufsize "], size_t " bufsize ,
+.BI "                 char " buf "[restrict " bufsize "], size_t " bufsize ,
 .BI "                 struct hostent **restrict " result ,
 .BI "                 int *restrict " h_errnop );
 .B [[deprecated]]
-.BI "int gethostbyname2_r(const char *restrict " name ", int " af,
+.BI "int gethostbyname2_r(size_t " bufsize ;
+.BI "                 const char *restrict " name ", int " af,
 .BI "                 struct hostent *restrict " ret ,
-.BI "                 char " buf "[restrict ." bufsize "], size_t " bufsize ,
+.BI "                 char " buf "[restrict " bufsize "], size_t " bufsize ,
 .BI "                 struct hostent **restrict " result ,
 .BI "                 int *restrict " h_errnop );
 .fi

$ mansect SYNOPSIS !$ | MANWIDTH=72 man /dev/stdin | cat;
mansect SYNOPSIS man3/gethostbyname.3 | MANWIDTH=72 man /dev/stdin | cat;
gethostbyname(3)        Library Functions Manual       gethostbyname(3)

SYNOPSIS
     #include <netdb.h>

     void sethostent(int stayopen);
     void endhostent(void);

     [[deprecated]] extern int h_errno;

     [[deprecated]] struct hostent *gethostbyname(const char *name);
     [[deprecated]] struct hostent *gethostbyaddr(socklen_t size;
                                                  const void addr[size],
                                                  socklen_t size, int type);

     [[deprecated]] void herror(const char *s);
     [[deprecated]] const char *hstrerror(int err);

     /* System V/POSIX extension */
     struct hostent *gethostent(void);

     /* GNU extensions */
     [[deprecated]]
     struct hostent *gethostbyname2(const char *name, int af);

     int gethostent_r(size_t bufsize;
                      struct hostent *restrict ret,
                      char buf[restrict bufsize], size_t bufsize,
                      struct hostent **restrict result,
                      int *restrict h_errnop);

     [[deprecated]]
     int gethostbyaddr_r(socklen_t size, size_t bufsize;
                      const void addr[restrict size], socklen_t size,
                      int type,
                      struct hostent *restrict ret,
                      char buf[restrict bufsize], size_t bufsize,
                      struct hostent **restrict result,
                      int *restrict h_errnop);
     [[deprecated]]
     int gethostbyname_r(size_t bufsize;
                      const char *restrict name,
                      struct hostent *restrict ret,
                      char buf[restrict bufsize], size_t bufsize,
                      struct hostent **restrict result,
                      int *restrict h_errnop);
     [[deprecated]]
     int gethostbyname2_r(size_t bufsize;
                      const char *restrict name, int af,
                      struct hostent *restrict ret,
                      char buf[restrict bufsize], size_t bufsize,
                      struct hostent **restrict result,
                      int *restrict h_errnop);

 Feature    Test    Macro    Requirements    for    glibc   (see   fea‐
 ture_test_macros(7)):

     gethostbyname2(),  gethostent_r(),  gethostbyaddr_r(),  gethostby‐
     name_r(), gethostbyname2_r():
         Since glibc 2.19:
             _DEFAULT_SOURCE
         glibc up to and including 2.19:
             _BSD_SOURCE || _SVID_SOURCE

     herror(), hstrerror():
         Since glibc 2.19:
             _DEFAULT_SOURCE
         glibc 2.8 to glibc 2.19:
             _BSD_SOURCE || _SVID_SOURCE
         Before glibc 2.8:
             none

     h_errno:
         Since glibc 2.19
             _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
         glibc 2.12 to glibc 2.19:
             _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
         Before glibc 2.12:
             none

Linux man‐pages (unreleased)     (date)                gethostbyname(3)






-- 
<https://www.alejandro-colomar.es/>