Forward Deceleration Changes

Forward Deceleration Changes

[Mark Naughton]

I noticed that recent man pages have started to include forward
declarations in function arguments with sizes. These are a C2Y
proposal. I was wondering what the justification for the change is?
Shouldn't the man pages stick to standard declarations to avoid
confusion?
e.g fread() and fwrite()

https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man/man3/fread.3?id=d2c2db8830f8fcbb736bdea52b398257447bef6b

Thanks,
Mark Naughton

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6597 bytes --]

Hi Mark,

On Tue, Jun 03, 2025 at 12:04:05PM +0100, Mark Naughton wrote:
> I noticed that recent man pages have started to include forward
> declarations in function arguments with sizes.

Yes.  That happened mainly in

	commit d2c2db8830f8fcbb736bdea52b398257447bef6b
	Author:     Alejandro Colomar <alx@kernel.org>
	AuthorDate: Fri Mar 14 18:33:41 2025 +0100
	Commit:     Alejandro Colomar <alx@kernel.org>
	CommitDate: Fri Mar 14 18:55:19 2025 +0100

	    man/: SYNOPSIS: Use GNU forward-declarations of parameters for sizes of array parameters
	    
	    This syntax has been proposed for standardization in N3433.
	    
	    Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3433.pdf>
	    Cc: Christopher Bazley <chris.bazley.wg14@gmail.com>
	    Cc: Martin Uecker <uecker@tugraz.at>
	    Cc: Joseph Myers <josmyers@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

Prior to that, there was

	commit 1eed67e75deff662dffce3195e55e608809eaafd
	Author:     Alejandro Colomar <alx.manpages@gmail.com>
	AuthorDate: Fri Aug 26 22:48:26 2022 +0200
	Commit:     Alejandro Colomar <alx@kernel.org>
	CommitDate: Thu Nov 10 00:44:59 2022 +0100

	    Various pages: SYNOPSIS: Use VLA syntax in function parameters
	    
	    The WG14 charter for C23 added one principle to the ones in
	    previous standards:
	    
	    [
	    15.  Application Programming Interfaces (APIs) should be
	    self-documenting when possible.  In particular, the order of
	    parameters in function declarations should be arranged such that
	    the size of an array appears before the array.  The purpose is to
	    allow Variable-Length Array (VLA) notation to be used. This not
	    only makes the code's purpose clearer to human readers, but also
	    makes static analysis easier.  Any new APIs added to the Standard
	    should take this into consideration.
	    ]
	    
	    ISO C doesn't allow using VLA syntax when the parameter used for
	    the size of the array is declared _after_ the parameter that is a
	    VLa.  That's a minor issue that could be easily changed in the
	    language without backwards-compatibility issues, and in fact it
	    seems to have been proposed, and not yet discarded, even if it's
	    not going to change in C23.
	    
	    Since the manual pages SYNOPSIS are not bounded by strict C legal
	    syntax, but we already use some "tricks" to try to convey the most
	    information to the reader even if it might not be the most legal
	    syntax, we can also make a small compromise in this case, using
	    illegal syntax (at least not yet legalized) to add important
	    information to the function prototypes.
	    
	    If we're lucky, compiler authors, and maybe even WG14 members, may
	    be satisfied by the syntax used in these manual pages, and may
	    decide to implement this feature to the language.
	    
	    It seems to me a sound syntax that isn't ambiguous, even if it
	    deviates from the common pattern in C that declarations _always_
	    come before use.  But it's a reasonable tradeoff.
	    
	    This change will make the contract between the programmer and the
	    implementation clearer just by reading a prototype.  For example,
	    
	      size_t strlcpy(char *restrict dst, const char *restrict src,
			     size_t size);
	    
		vs
	    
	      size_t strlcpy(char dst[restrict .size], const char *restrict src,
			     size_t size);
	    
	    the second prototype above makes it clear that the 'dst' buffer
	    will be safe from overflow, but the 'src' one clearly needs to be
	    NUL-terminated, or it might cause UB, since nothing tells the
	    function how long it is.
	    
	    Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2611.htm>
	    Cc: Ingo Schwarze <schwarze@openbsd.org>
	    Cc: JeanHeyd Meneide <wg14@soasis.org>
	    Cc: Martin Uecker <uecker@tugraz.at>
	    Cc: <gcc@gcc.gnu.org>
	    Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

> These are a C2Y
> proposal.

And an old GNU extension:
<https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html#Arrays-of-Variable-Length>

> I was wondering what the justification for the change is?

For the initial change to use [.identifier] notation, the rationale is
documentation.  Otherwise, it's unclear which parameters are numbers of
elements for which pointers.  In some pages it's obvious; in others,
it's not so obvious.

Joseph Myers had concerns with that notation, since it was neither
standard nor an existing vendor extension.  We (Joseph, Martin, and I)
had long discussions about adding support for it in GCC, but ended up
agreeing that GNU's existing syntax is better.

> Shouldn't the man pages stick to standard declarations to avoid
> confusion?

I don't think so, and this has never been the case.  You can for example
have a look at the open(2) manual page in man-pages-5.13, when
Michael Kerrisk was the maintainer of the project.

alx@devuan:~/src/linux/man-pages/man-pages/master$ git status
HEAD detached at man-pages-5.13
nothing to commit, working tree clean
alx@devuan:~/src/linux/man-pages/man-pages/master$ man ./man2/open.2 | grep 'int open('
     int open(const char *pathname, int flags);
     int open(const char *pathname, int flags, mode_t mode);

That wasn't standard syntax.  It's not valid to redeclare a function
with a different prototype.  It was useful, though, to show the only two
valid ways that one can call this function.  I've improved it to reduce
confusion, by using standards-conforming syntax:

$ man 2 open | grep -A1 'int open('
     int open(const char *path, int flags, ...
                /* mode_t mode */ );

In this case, I decided that standard syntax is better, because it
documents that the function is variadic, which warns the programmer that
it should be extra careful when using it, as there's less type safety
than with usual functions.

In the case of array parameters, I think documenting the parameters as
arrays and their number of elements has more weight than using standard
syntax.

> e.g fread() and fwrite()
> 
> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man/man3/fread.3?id=d2c2db8830f8fcbb736bdea52b398257447bef6b

Let's hope people will catch up with this feature soonish.  Many have
reported good feedback about it; I think more than those that have
reported confusion.

> 
> Thanks,
> Mark Naughton

Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Mark Naughton]

The [.identifier] notation is fine, it serves a purpose. I don't know
what value adding the forward declarations does, they are more for the
compiler, not the programmer.
When I first got the updated man pages, I thought the forward
declarations were the first arguments to the function.

I suspect new C programmers would find the forward declaration
prototypes quite confusing also since they are not even part of the
language.

When I open a man page I want to see "what arguments do I pass and in
what order". With this change you have to parse the prototype for the
semi-colon
to see the start of the args.

Mark

On Tue, Jun 3, 2025 at 12:40 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Mark,
>
> On Tue, Jun 03, 2025 at 12:04:05PM +0100, Mark Naughton wrote:
> > I noticed that recent man pages have started to include forward
> > declarations in function arguments with sizes.
>
> Yes.  That happened mainly in
>
>         commit d2c2db8830f8fcbb736bdea52b398257447bef6b
>         Author:     Alejandro Colomar <alx@kernel.org>
>         AuthorDate: Fri Mar 14 18:33:41 2025 +0100
>         Commit:     Alejandro Colomar <alx@kernel.org>
>         CommitDate: Fri Mar 14 18:55:19 2025 +0100
>
>             man/: SYNOPSIS: Use GNU forward-declarations of parameters for sizes of array parameters
>
>             This syntax has been proposed for standardization in N3433.
>
>             Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3433.pdf>
>             Cc: Christopher Bazley <chris.bazley.wg14@gmail.com>
>             Cc: Martin Uecker <uecker@tugraz.at>
>             Cc: Joseph Myers <josmyers@redhat.com>
>             Signed-off-by: Alejandro Colomar <alx@kernel.org>
>
> Prior to that, there was
>
>         commit 1eed67e75deff662dffce3195e55e608809eaafd
>         Author:     Alejandro Colomar <alx.manpages@gmail.com>
>         AuthorDate: Fri Aug 26 22:48:26 2022 +0200
>         Commit:     Alejandro Colomar <alx@kernel.org>
>         CommitDate: Thu Nov 10 00:44:59 2022 +0100
>
>             Various pages: SYNOPSIS: Use VLA syntax in function parameters
>
>             The WG14 charter for C23 added one principle to the ones in
>             previous standards:
>
>             [
>             15.  Application Programming Interfaces (APIs) should be
>             self-documenting when possible.  In particular, the order of
>             parameters in function declarations should be arranged such that
>             the size of an array appears before the array.  The purpose is to
>             allow Variable-Length Array (VLA) notation to be used. This not
>             only makes the code's purpose clearer to human readers, but also
>             makes static analysis easier.  Any new APIs added to the Standard
>             should take this into consideration.
>             ]
>
>             ISO C doesn't allow using VLA syntax when the parameter used for
>             the size of the array is declared _after_ the parameter that is a
>             VLa.  That's a minor issue that could be easily changed in the
>             language without backwards-compatibility issues, and in fact it
>             seems to have been proposed, and not yet discarded, even if it's
>             not going to change in C23.
>
>             Since the manual pages SYNOPSIS are not bounded by strict C legal
>             syntax, but we already use some "tricks" to try to convey the most
>             information to the reader even if it might not be the most legal
>             syntax, we can also make a small compromise in this case, using
>             illegal syntax (at least not yet legalized) to add important
>             information to the function prototypes.
>
>             If we're lucky, compiler authors, and maybe even WG14 members, may
>             be satisfied by the syntax used in these manual pages, and may
>             decide to implement this feature to the language.
>
>             It seems to me a sound syntax that isn't ambiguous, even if it
>             deviates from the common pattern in C that declarations _always_
>             come before use.  But it's a reasonable tradeoff.
>
>             This change will make the contract between the programmer and the
>             implementation clearer just by reading a prototype.  For example,
>
>               size_t strlcpy(char *restrict dst, const char *restrict src,
>                              size_t size);
>
>                 vs
>
>               size_t strlcpy(char dst[restrict .size], const char *restrict src,
>                              size_t size);
>
>             the second prototype above makes it clear that the 'dst' buffer
>             will be safe from overflow, but the 'src' one clearly needs to be
>             NUL-terminated, or it might cause UB, since nothing tells the
>             function how long it is.
>
>             Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2611.htm>
>             Cc: Ingo Schwarze <schwarze@openbsd.org>
>             Cc: JeanHeyd Meneide <wg14@soasis.org>
>             Cc: Martin Uecker <uecker@tugraz.at>
>             Cc: <gcc@gcc.gnu.org>
>             Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>
> > These are a C2Y
> > proposal.
>
> And an old GNU extension:
> <https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html#Arrays-of-Variable-Length>
>
> > I was wondering what the justification for the change is?
>
> For the initial change to use [.identifier] notation, the rationale is
> documentation.  Otherwise, it's unclear which parameters are numbers of
> elements for which pointers.  In some pages it's obvious; in others,
> it's not so obvious.
>
> Joseph Myers had concerns with that notation, since it was neither
> standard nor an existing vendor extension.  We (Joseph, Martin, and I)
> had long discussions about adding support for it in GCC, but ended up
> agreeing that GNU's existing syntax is better.
>
> > Shouldn't the man pages stick to standard declarations to avoid
> > confusion?
>
> I don't think so, and this has never been the case.  You can for example
> have a look at the open(2) manual page in man-pages-5.13, when
> Michael Kerrisk was the maintainer of the project.
>
> alx@devuan:~/src/linux/man-pages/man-pages/master$ git status
> HEAD detached at man-pages-5.13
> nothing to commit, working tree clean
> alx@devuan:~/src/linux/man-pages/man-pages/master$ man ./man2/open.2 | grep 'int open('
>      int open(const char *pathname, int flags);
>      int open(const char *pathname, int flags, mode_t mode);
>
> That wasn't standard syntax.  It's not valid to redeclare a function
> with a different prototype.  It was useful, though, to show the only two
> valid ways that one can call this function.  I've improved it to reduce
> confusion, by using standards-conforming syntax:
>
> $ man 2 open | grep -A1 'int open('
>      int open(const char *path, int flags, ...
>                 /* mode_t mode */ );
>
> In this case, I decided that standard syntax is better, because it
> documents that the function is variadic, which warns the programmer that
> it should be extra careful when using it, as there's less type safety
> than with usual functions.
>
> In the case of array parameters, I think documenting the parameters as
> arrays and their number of elements has more weight than using standard
> syntax.
>
> > e.g fread() and fwrite()
> >
> > https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man/man3/fread.3?id=d2c2db8830f8fcbb736bdea52b398257447bef6b
>
> Let's hope people will catch up with this feature soonish.  Many have
> reported good feedback about it; I think more than those that have
> reported confusion.
>
> >
> > Thanks,
> > Mark Naughton
>
> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1707 bytes --]

Hi Mark,

On Tue, Jun 03, 2025 at 01:21:47PM +0100, Mark Naughton wrote:
> The [.identifier] notation is fine, it serves a purpose. I don't know
> what value adding the forward declarations does,

Hmmm, ironically enough, the argument for changing from [.identifier] to
forward declarations was using standard syntax.

I agree that all else being equal, I prefer the [.identifier] notation
in the manual pages; it is more readable.  And I defended it for some
time.  However, having forward declarations at the edge of being
standard, and having been a GNU extension for a very long time, there
was a strong argument for using it.

> they are more for the
> compiler, not the programmer.
> When I first got the updated man pages, I thought the forward
> declarations were the first arguments to the function.
> 
> I suspect new C programmers would find the forward declaration
> prototypes quite confusing also since they are not even part of the
> language.

I tend to disagree with that.  ISO C is only a dialect.  GNU C is an
equally valid dialect of the same language.  It is indeed the dialect
that most programmers use on Linux systems, ISO C being a minority
dialect that only some pedantic programmers use.

> When I open a man page I want to see "what arguments do I pass and in
> what order". With this change you have to parse the prototype for the
> semi-colon
> to see the start of the args.

I tried to use a style that makes the ';' stand out more, by breaking
the line after it.  But I agree that the first times you look at it, it
can be a bit confusing and hard to distinguish.


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Mark Harris]

> > When I open a man page I want to see "what arguments do I pass and in
> > what order". With this change you have to parse the prototype for the
> > semi-colon
> > to see the start of the args.
>
> I tried to use a style that makes the ';' stand out more, by breaking
> the line after it.  But I agree that the first times you look at it, it
> can be a bit confusing and hard to distinguish.

The main issue with the forward declaration syntax is that it is easy
to mistake the forward declarations for arguments, especially when
just quickly checking the man page to remind yourself which argument
is first.  If you want to retain this syntax, what might help is to
remove the bold font style from the forward declarations, or change
their formatting in some other way to be different than that of the
arguments.


 - Mark

Re: Forward Deceleration Changes

[Mark Naughton]

Agreed, Mark.

Mark

On Tue, Jun 3, 2025 at 3:48 PM Mark Harris <mark.hsj@gmail.com> wrote:
>
> > > When I open a man page I want to see "what arguments do I pass and in
> > > what order". With this change you have to parse the prototype for the
> > > semi-colon
> > > to see the start of the args.
> >
> > I tried to use a style that makes the ';' stand out more, by breaking
> > the line after it.  But I agree that the first times you look at it, it
> > can be a bit confusing and hard to distinguish.
>
> The main issue with the forward declaration syntax is that it is easy
> to mistake the forward declarations for arguments, especially when
> just quickly checking the man page to remind yourself which argument
> is first.  If you want to retain this syntax, what might help is to
> remove the bold font style from the forward declarations, or change
> their formatting in some other way to be different than that of the
> arguments.
>
>
>  - Mark
>

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1375 bytes --]

Hi Mark and Mark,

On Tue, Jun 03, 2025 at 03:52:59PM +0100, Mark Naughton wrote:
> Agreed, Mark.
> 
> Mark
> 
> On Tue, Jun 3, 2025 at 3:48 PM Mark Harris <mark.hsj@gmail.com> wrote:
> >
> > > > When I open a man page I want to see "what arguments do I pass and in
> > > > what order". With this change you have to parse the prototype for the
> > > > semi-colon
> > > > to see the start of the args.
> > >
> > > I tried to use a style that makes the ';' stand out more, by breaking
> > > the line after it.  But I agree that the first times you look at it, it
> > > can be a bit confusing and hard to distinguish.
> >
> > The main issue with the forward declaration syntax is that it is easy
> > to mistake the forward declarations for arguments, especially when
> > just quickly checking the man page to remind yourself which argument
> > is first.  If you want to retain this syntax, what might help is to
> > remove the bold font style from the forward declarations, or change
> > their formatting in some other way to be different than that of the
> > arguments.

Hmmm, agreed.  I had been thinking about it.  Maybe using all roman for
both the type and the variable name would be good.  Thanks!  I'll do it
when I finish some other work I'm doing at the moment.


Have a lovely night!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Mark Naughton]

Looks like someone else thought this was a bug:
https://bugzilla.kernel.org/show_bug.cgi?id=220192


As the new man pages rolls out to more distros, I believe these bug
reports will keep coming due to the confusing nature of the change.

Mark

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 703 bytes --]

Hi Mark,

On Wed, Jun 04, 2025 at 01:00:16PM +0100, Mark Naughton wrote:
> Looks like someone else thought this was a bug:
> https://bugzilla.kernel.org/show_bug.cgi?id=220192
> 
> 
> As the new man pages rolls out to more distros, I believe these bug
> reports will keep coming due to the confusing nature of the change.

Yep, I'm taking this as a clear sign that I need to do something.  I've
put this as my priority for now.  I still need to finish some other
thing that I'm doing at the moment, as it will make it easier to fix
this too.  So, expect this to be fixed in a couple of weeks.


Have a lovely day!
Alex

> 
> Mark
> 
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Florian Weimer]

* Alejandro Colomar:

> Hi Mark and Mark,
>
> On Tue, Jun 03, 2025 at 03:52:59PM +0100, Mark Naughton wrote:
>> Agreed, Mark.
>> 
>> Mark
>> 
>> On Tue, Jun 3, 2025 at 3:48 PM Mark Harris <mark.hsj@gmail.com> wrote:
>> >
>> > > > When I open a man page I want to see "what arguments do I pass and in
>> > > > what order". With this change you have to parse the prototype for the
>> > > > semi-colon
>> > > > to see the start of the args.
>> > >
>> > > I tried to use a style that makes the ';' stand out more, by breaking
>> > > the line after it.  But I agree that the first times you look at it, it
>> > > can be a bit confusing and hard to distinguish.
>> >
>> > The main issue with the forward declaration syntax is that it is easy
>> > to mistake the forward declarations for arguments, especially when
>> > just quickly checking the man page to remind yourself which argument
>> > is first.  If you want to retain this syntax, what might help is to
>> > remove the bold font style from the forward declarations, or change
>> > their formatting in some other way to be different than that of the
>> > arguments.
>
> Hmmm, agreed.  I had been thinking about it.  Maybe using all roman for
> both the type and the variable name would be good.  Thanks!  I'll do it
> when I finish some other work I'm doing at the moment.

Somewhat related: This syntax is currently used for inputs that can be
either strings or arrays.  Two examples:

       size_t strnlen(size_t maxlen;
                      const char s[maxlen], size_t maxlen);

       int strncmp(size_t n;
                   const char s1[n], const char s2[n], size_t n);

Obviously, we want

     strncnmp(subject, "prefix", 6)

to be valid independently of the length of the subject string, and the
declaration with the array syntax does not seem to be compatible with
that.

Thanks,
Florian

strncmp(3) in the SYNOPSIS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2506 bytes --]

Hi Florian,

On Thu, Jun 05, 2025 at 04:53:02PM +0200, Florian Weimer wrote:
> Somewhat related: This syntax is currently used for inputs that can be
> either strings or arrays.  Two examples:
> 
>        size_t strnlen(size_t maxlen;
>                       const char s[maxlen], size_t maxlen);
> 
>        int strncmp(size_t n;
>                    const char s1[n], const char s2[n], size_t n);
> 
> Obviously, we want
> 
>      strncnmp(subject, "prefix", 6)
> 
> to be valid independently of the length of the subject string,

I'm not sure I understand your statement.  It assumes that the subject
is a string, which it need not be.

	[[gnu::nonstring]] char subject[7] = "asdfghi";
	strncmp(subject, "prefix", 6);

> and the
> declaration with the array syntax does not seem to be compatible with
> that.

The only way to be pedantically correct with this API would be to use a
pointer (or an incomplete array), but then you have the issue of
pessimizing documentation of the use with non-strings.  I don't want to
do that.

Yes, that's a bit opinionated, but I'm working on having strprefix() and
strsuffix() in ISO C, which would render this use case of strncmp(3)
obsolete, so hopefully that aspect of the documentation can be neglected
in the SYNOPSIS (of course it will be well documented in the
DESCRIPTION).

I suggest you implement something like this in glibc:

<https://github.com/shadow-maint/shadow/blob/master/lib/string/strcmp/strprefix.h>

	// string prefix
	#define strprefix(s, prefix)                                          \
	({                                                                    \
		const char  *p_;                                              \
									      \
		p_ = strprefix_(s, prefix);                                   \
									      \
		_Generic(s,                                                   \
			const char *:                     p_,                 \
			const void *:                     p_,                 \
			char *:        const_cast(char *, p_),                \
			void *:        const_cast(char *, p_)                 \
		);                                                            \
	})

	inline const char *
	strprefix_(const char *s, const char *prefix)
	{
		if (strncmp(s, prefix, strlen(prefix)) != 0)
			return NULL;

		return s + strlen(prefix);
	}



Have a lovely day!
Alex

> 
> Thanks,
> Florian
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: strncmp(3) in the SYNOPSIS

[Florian Weimer]

* Alejandro Colomar:

> Hi Florian,
>
> On Thu, Jun 05, 2025 at 04:53:02PM +0200, Florian Weimer wrote:
>> Somewhat related: This syntax is currently used for inputs that can be
>> either strings or arrays.  Two examples:
>> 
>>        size_t strnlen(size_t maxlen;
>>                       const char s[maxlen], size_t maxlen);
>> 
>>        int strncmp(size_t n;
>>                    const char s1[n], const char s2[n], size_t n);
>> 
>> Obviously, we want
>> 
>>      strncnmp(subject, "prefix", 6)
>> 
>> to be valid independently of the length of the subject string,
>
> I'm not sure I understand your statement.  It assumes that the subject
> is a string, which it need not be.
>
> 	[[gnu::nonstring]] char subject[7] = "asdfghi";
> 	strncmp(subject, "prefix", 6);

My point is that *if* it is a string, it can be arbitrary long.  It does
not have to contain at least five characters, it can be shorter.  These
two choices are valid:

  subject is a string
  subject is an array that is at least six bytes long

They overlap, but both options are needed.  For example, "?" is not an
array that is at least six bytes long.

Thanks,
Florian

Re: strncmp(3) in the SYNOPSIS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 757 bytes --]

Hi Florian,

On Thu, Jun 05, 2025 at 05:28:23PM +0200, Florian Weimer wrote:
> My point is that *if* it is a string, it can be arbitrary long.  It does
> not have to contain at least five characters, it can be shorter.  These
> two choices are valid:
> 
>   subject is a string
>   subject is an array that is at least six bytes long
> 
> They overlap, but both options are needed.  For example, "?" is not an
> array that is at least six bytes long.

Yep, that's correct.  Hmmm, I don't know; maybe for consistency I could
remove those [n] and just use [].  We'll see.  Please remind me in a
month or so; possibly with a patch, if you want.


Cheers,
Alex

> 
> Thanks,
> Florian
> 
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6188 bytes --]


Hi Marks,

On Tue, Jun 03, 2025 at 03:52:59PM +0100, Mark Naughton wrote:
> Agreed, Mark.
> 
> Mark
> 
> On Tue, Jun 3, 2025 at 3:48 PM Mark Harris <mark.hsj@gmail.com> wrote:
> >
> > > > When I open a man page I want to see "what arguments do I pass and in
> > > > what order". With this change you have to parse the prototype for the
> > > > semi-colon
> > > > to see the start of the args.
> > >
> > > I tried to use a style that makes the ';' stand out more, by breaking
> > > the line after it.  But I agree that the first times you look at it, it
> > > can be a bit confusing and hard to distinguish.
> >
> > The main issue with the forward declaration syntax is that it is easy
> > to mistake the forward declarations for arguments, especially when
> > just quickly checking the man page to remind yourself which argument
> > is first.  If you want to retain this syntax, what might help is to
> > remove the bold font style from the forward declarations, or change
> > their formatting in some other way to be different than that of the
> > arguments.

I've pushed a change to my branch.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=fda4e7b0c420f42f704dedd71733d6766a8eb41c>

You can check the PDF online with the new formatting:
<https://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#fread.3>

Here's an excerpt of the commit showing just the changes in fread(3):

	$ git show -- man/man3/fread.3
	commit fda4e7b0c420f42f704dedd71733d6766a8eb41c (HEAD -> main, alx/main, alx/contrib, alx/HEAD, contrib)
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Fri Jun 6 13:27:02 2025 +0200

	    man/: Don't highlight forward declarations of function parameters
	    
	    Previously, many people confused these for actual parameters, since it's
	    hard to distinguish a ',' from ';'.  By removing bold/italics from
	    these, it will be easier to distinguish them.
	    
	    The cases have been found with a script:
	    
		    $ find -type f \
		    | xargs grep -l '^\.TH ' \
		    | sort \
		    | xargs mansect SYNOPSIS \
		    | man /dev/stdin \
		    | grep -e '^[^ ]' -e '[^ ]( [^ )].*[^)];' \
		    | less;
	    
	    Reported-by: Mark Naughton <mnaughto@redhat.com>
	    Suggested-by: Mark Harris <mark.hsj@gmail.com>
	    Acked-by: Mark Naughton <mnaughto@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/fread.3 b/man/man3/fread.3
	index cb259224b..a1eb2e791 100644
	--- a/man/man3/fread.3
	+++ b/man/man3/fread.3
	@@ -16,8 +16,8 @@ .SH SYNOPSIS
	 .fi
	 .P
	 .SY size_t\~fread(
	-.BI size_t\~ size ,
	-.BI size_t\~ n ;
	+size_t\~size,
	+size_t\~n;
	 .br
	 .BI void\~ ptr [restrict\~ size \~*\~ n ],
	 .br
	@@ -27,8 +27,8 @@ .SH SYNOPSIS
	 .BI FILE\~*restrict\~ stream );
	 .YS .
	 .SY size_t\~fwrite(
	-.BI size_t\~ size ,
	-.BI size_t\~ n ;
	+size_t\~size,
	+size_t\~n;
	 .br
	 .BI const\~void\~ ptr [restrict\~ size \~*\~ n ],
	 .br


This is based on another commit which I've been working on these days,
which makes use of SY/YS for formatting function prototypes.

	$ git show fc3664f9e80d -- man/man3/fread.3
	commit fc3664f9e80d84731424cbf4cfe9dd50298cbfba
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Sun Nov 24 21:40:41 2024 +0100

	    man/: SYNOPSIS: Use SY/YS
	    
	    This makes it easier to write the SYNOPSIS, which will reduce the
	    learning curve for contributors.
	    
	    Another benefit is that the prototypes are wrapped correctly for the
	    terminal width that the reader is using, so it's not hardcoded at 80.
	    It also removes the need for carefully aligning the prototypes by the
	    author of a page.
	    
	    It causes a small unwanted problem: a white space is added after the
	    opening parenthesis.  That's a minor trade-off for the benefits it
	    brings.  Once groff 1.24.0 is released, we'll be able to use an
	    extension that it provides, which allows us to remove that space, by
	    using the second argument to SY.
	    
	    Use it even in functions that don't need it (0 or 1 parameters), for
	    consistency.  This will make it easier to grep for function prototypes
	    in the source code.
	    
	    The cases have been found with a script:
	    
		    $ find -type f \
		    | xargs grep -l '^\.TH ' \
		    | sort \
		    | xargs mansect SYNOPSIS \
		    | man /dev/stdin \
		    | grep -e '^[^ ]' -e '[^ ]([^ )].*\(,\|;\)' \
		    | less;
	    
	    Suggested-by: "G. Branden Robinson" <branden@debian.org>
	    Cc: Ingo Schwarze <schwarze@openbsd.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/fread.3 b/man/man3/fread.3
	index 55b74b93a..cb259224b 100644
	--- a/man/man3/fread.3
	+++ b/man/man3/fread.3
	@@ -13,16 +13,30 @@ .SH LIBRARY
	 .SH SYNOPSIS
	 .nf
	 .B #include <stdio.h>
	-.P
	-.BI "size_t fread(size_t " size ", size_t " n ;
	-.BI "             void " ptr "[restrict " size " * " n ],
	-.BI "             size_t " size ", size_t " n ,
	-.BI "             FILE *restrict " stream );
	-.BI "size_t fwrite(size_t " size ", size_t " n ;
	-.BI "             const void " ptr "[restrict " size " * " n ],
	-.BI "             size_t " size ", size_t " n ,
	-.BI "             FILE *restrict " stream );
	 .fi
	+.P
	+.SY size_t\~fread(
	+.BI size_t\~ size ,
	+.BI size_t\~ n ;
	+.br
	+.BI void\~ ptr [restrict\~ size \~*\~ n ],
	+.br
	+.BI size_t\~ size ,
	+.BI size_t\~ n ,
	+.br
	+.BI FILE\~*restrict\~ stream );
	+.YS .
	+.SY size_t\~fwrite(
	+.BI size_t\~ size ,
	+.BI size_t\~ n ;
	+.br
	+.BI const\~void\~ ptr [restrict\~ size \~*\~ n ],
	+.br
	+.BI size_t\~ size ,
	+.BI size_t\~ n ,
	+.br
	+.BI FILE\~*restrict\~ stream );
	+.YS
	 .SH DESCRIPTION
	 The function
	 .BR fread ()


I'm not going to release these changes soon, though.  They cause some
minor temporary regressions, so I'm considering when I should do it.
But eventually, these changes will be released.


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 554 bytes --]

Hi Mark & Mark,

On Fri, Jun 06, 2025 at 03:05:20PM +0200, Alejandro Colomar wrote:
> I'm not going to release these changes soon, though.  They cause some
> minor temporary regressions, so I'm considering when I should do it.
> But eventually, these changes will be released.

I found a way to do this without a regression.  I've pushed the change
already to master.  Please check that you like the pages now.  I find
them much nicer.  I'll try to have a release soon.


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Forward Deceleration Changes

[Mark Harris]

Alejandro Colomar wrote:
>
> Hi Mark & Mark,
>
> On Fri, Jun 06, 2025 at 03:05:20PM +0200, Alejandro Colomar wrote:
> > I'm not going to release these changes soon, though.  They cause some
> > minor temporary regressions, so I'm considering when I should do it.
> > But eventually, these changes will be released.
>
> I found a way to do this without a regression.  I've pushed the change
> already to master.  Please check that you like the pages now.  I find
> them much nicer.  I'll try to have a release soon.

This does look better than the bolded forward declarations; thanks for
doing this.

Honestly, though, I think it would be even better without the forward
declarations at all, which are just repeating information that is
already present shortly afterwards.  It may not follow the proposed C
declaration syntax, but the Synopsis section already does not match
what you would write in C.  That is, you wouldn't write:

       #include <stdio.h>

       size_t fread(size_t size, size_t n;
                    void ptr[restrict size * n],
                    size_t size, size_t n,
                    FILE *restrict stream);

as stated in the Synopsis section.  Not only is an array of void
invalid, but at best that would declare the function twice.

What the reader needs to know is how to call the function, not how to
declare it.  In fact, users are discouraged from declaring the
function, which is already taken care of by the header file.  It's
just that the C function call syntax doesn't include the types, so the
types are added using the same syntax that is used in declarations,
even though the reader has no need for another function declaration.
The syntax without the forward declarations is closer to the function
call syntax that is needed, while also providing the necessary type
information.



 - Mark

>
>
> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>

Re: Forward Deceleration Changes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2646 bytes --]

Hi Mark,

On Sat, Jun 28, 2025 at 04:38:31PM -0700, Mark Harris wrote:
> Alejandro Colomar wrote:
> >
> > Hi Mark & Mark,
> >
> > On Fri, Jun 06, 2025 at 03:05:20PM +0200, Alejandro Colomar wrote:
> > > I'm not going to release these changes soon, though.  They cause some
> > > minor temporary regressions, so I'm considering when I should do it.
> > > But eventually, these changes will be released.
> >
> > I found a way to do this without a regression.  I've pushed the change
> > already to master.  Please check that you like the pages now.  I find
> > them much nicer.  I'll try to have a release soon.
> 
> This does look better than the bolded forward declarations; thanks for
> doing this.

You're welcome!

> Honestly, though, I think it would be even better without the forward
> declarations at all, which are just repeating information that is
> already present shortly afterwards.  It may not follow the proposed C
> declaration syntax, but the Synopsis section already does not match
> what you would write in C.  That is, you wouldn't write:
> 
>        #include <stdio.h>
> 
>        size_t fread(size_t size, size_t n;
>                     void ptr[restrict size * n],
>                     size_t size, size_t n,
>                     FILE *restrict stream);
> 
> as stated in the Synopsis section.  Not only is an array of void
> invalid, but at best that would declare the function twice.
> 
> What the reader needs to know is how to call the function, not how to
> declare it.  In fact, users are discouraged from declaring the
> function, which is already taken care of by the header file.  It's
> just that the C function call syntax doesn't include the types, so the
> types are added using the same syntax that is used in declarations,
> even though the reader has no need for another function declaration.
> The syntax without the forward declarations is closer to the function
> call syntax that is needed, while also providing the necessary type
> information.

I've had people complain in the opposite direction too, so I guess we
can say the current way is a compromise that works for both.

About arrays of void, I'm not as worried as I'd be if we used the
parameters without a forward declaration.  If programmers try to declare
their functions using arrays of void, their compiler will tell them they
can't.  However, if someone tries the same thing with undeclared
parameters, it might "work", which would be rather dangerous.

So, I'll keep the standard syntax in that regard.


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: strncmp(3) in the SYNOPSIS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1095 bytes --]

Hi Florian,

On Thu, Jun 05, 2025 at 05:33:31PM +0200, Alejandro Colomar wrote:
> Hi Florian,
> 
> On Thu, Jun 05, 2025 at 05:28:23PM +0200, Florian Weimer wrote:
> > My point is that *if* it is a string, it can be arbitrary long.  It does
> > not have to contain at least five characters, it can be shorter.  These
> > two choices are valid:
> > 
> >   subject is a string
> >   subject is an array that is at least six bytes long
> > 
> > They overlap, but both options are needed.  For example, "?" is not an
> > array that is at least six bytes long.
> 
> Yep, that's correct.  Hmmm, I don't know; maybe for consistency I could
> remove those [n] and just use [].  We'll see.  Please remind me in a
> month or so; possibly with a patch, if you want.

I've applied a patch fixing this misuse of [n].  Thanks!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=e11a82a6f7098b94bcd00fb767a1db269e3a83db>
(use port 80).


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]