[Oops; I had a typo in Martin's address] On Fri, Mar 14, 2025 at 01:49:29PM +0100, Alejandro Colomar wrote: > 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/> -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
