[BUG] typo in man2/readlink.2

[BUG] typo in man2/readlink.2

[Dirk Müller]

Hi,

I noticed that man pages 6.17 release includes this in the Synopsis
section of man -l man/man2/readlink.2:

      ssize_t readlink(size_t bufsiz;
                       const char *restrict path,
                       char buf[restrict bufsiz], size_t bufsiz);

I believe this is a typo and it should be:

      ssize_t readlink(const char *restrict path,
                       char buf[restrict bufsiz], size_t bufsiz);

instead. It doesn't make sense to me to have bufsiz twice in the
function signature and as far as I can tell from looking at the header
files
bufsiz is the last argument.

Sorry for not including a patch, but I am not sufficiently skilled at
editing man page sources :-)

Greetings,
Dirk

Re: [BUG] typo in man2/readlink.2

[G. Branden Robinson]

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

Hi Dirk,

At 2026-04-15T20:12:59+0200, Dirk Müller wrote:
> Hi,
> 
> I noticed that man pages 6.17 release includes this in the Synopsis
> section of man -l man/man2/readlink.2:
> 
>       ssize_t readlink(size_t bufsiz;
>                        const char *restrict path,
>                        char buf[restrict bufsiz], size_t bufsiz);
> 
> I believe this is a typo and it should be:
> 
>       ssize_t readlink(const char *restrict path,
>                        char buf[restrict bufsiz], size_t bufsiz);
> 
> instead.

This is something of a FAQ on this mailing list.

https://lore.kernel.org/linux-man/adupQhfJQ7kws17U@debian/

It's a GCC syntax extension.

https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html

> Sorry for not including a patch, but I am not sufficiently skilled at
> editing man page sources :-)

Have you seen groff_man_style(7)?

https://man7.org/linux/man-pages/man7/groff_man_style.7.html

</shameless self-plug>

(Unfortunately Michael hasn't updated to groff 1.24.{0,1} yet.)

Regards,
Branden

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

Re: [BUG] typo in man2/readlink.2

[Dirk Müller]

Hi Branden,

On Wed, Apr 15, 2026 at 8:24 PM G. Branden Robinson
<g.branden.robinson@gmail.com> wrote:

> >       ssize_t readlink(size_t bufsiz;
> >                        const char *restrict path,
> >                        char buf[restrict bufsiz], size_t bufsiz);
> >
> > I believe this is a typo and it should be:
> >
> >       ssize_t readlink(const char *restrict path,
> >                        char buf[restrict bufsiz], size_t bufsiz);
> This is something of a FAQ on this mailing list.
> https://lore.kernel.org/linux-man/adupQhfJQ7kws17U@debian/
> It's a GCC syntax extension.
>
> https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html

Oh, I understand that part. let me try again. The Synpsis shows 4
parameters to the readlink() call:

  ssize_t readlink(size_t, const char*, char buf[], size_t);

I believe it should actually be 3 parameters instead:

  ssize_t readlink(const char*, char buf[], size_t);

with other words, the first argument is a pointer to the source link,
not a repetition of bufsiz (which is at the end).

This page has the, what I consider correct synposis:

https://pubs.opengroup.org/onlinepubs/9699919799/functions/readlink.html

ssize_t readlink(const char *restrict path, char *restrict buf,
       size_t bufsize);

Again, I'm only commenting on the number of parameters, not the
variadic length expression on parameter two (three in the original).

Thanks,
Dirk

Re: [BUG] typo in man2/readlink.2

[Alejandro Colomar]

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

Hi Dirk,

On 2026-04-15T22:00:52+0200, Dirk Müller wrote:
> Hi Branden,
> 
> On Wed, Apr 15, 2026 at 8:24 PM G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
> 
> > >       ssize_t readlink(size_t bufsiz;
> > >                        const char *restrict path,
> > >                        char buf[restrict bufsiz], size_t bufsiz);
> > >
> > > I believe this is a typo and it should be:
> > >
> > >       ssize_t readlink(const char *restrict path,
> > >                        char buf[restrict bufsiz], size_t bufsiz);
> > This is something of a FAQ on this mailing list.
> > https://lore.kernel.org/linux-man/adupQhfJQ7kws17U@debian/
> > It's a GCC syntax extension.
> >
> > https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html

Look at the very bottom of that page.

> 
> Oh, I understand that part.

I believe you didn't.

> let me try again. The Synpsis shows 4
> parameters to the readlink() call:
> 
>   ssize_t readlink(size_t, const char*, char buf[], size_t);

That's not what readlink(2) documents.  readlink(2) has a semicolon (;)
after the fisrt 'size_t bufsiz'.  That means it's a forward declaration
of a function parameter, and not a real parameter declaration.

> 
> I believe it should actually be 3 parameters instead:
> 
>   ssize_t readlink(const char*, char buf[], size_t);
> 
> with other words, the first argument is a pointer to the source link,
> not a repetition of bufsiz (which is at the end).
> 
> This page has the, what I consider correct synposis:
> 
> https://pubs.opengroup.org/onlinepubs/9699919799/functions/readlink.html
> 
> ssize_t readlink(const char *restrict path, char *restrict buf,
>        size_t bufsize);

This synopsis is compatible with the one from readlink(2).  See by
yourself:

	alx@devuan:~/tmp$ cat rl.c 
	#include <sys/types.h>

	ssize_t readlink(
	    const char *path, char *buf, size_t bufsiz);

	ssize_t readlink(size_t bufsiz;
	    const char *path, char buf[bufsiz], size_t bufsiz);
	alx@devuan:~/tmp$ gcc -Wall -Wextra -Wno-vla-parameter -S rl.c 
	alx@devuan:~/tmp$ 

> Again, I'm only commenting on the number of parameters, not the
> variadic length expression on parameter two (three in the original).

Both prototypes have 3 parameters.


Have a lovely night!
Alex

> 
> Thanks,
> Dirk
> 

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

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

Re: [BUG] typo in man2/readlink.2

[Dirk Müller]

Hi Alejandro,

On Wed, Apr 15, 2026 at 11:36 PM Alejandro Colomar <alx@kernel.org> wrote:

> That's not what readlink(2) documents.  readlink(2) has a semicolon (;)
> after the fisrt 'size_t bufsiz'.  That means it's a forward declaration
> of a function parameter, and not a real parameter declaration.

Ah, got it! Thanks for being patient with me. This made me realize
what tricked me here (other than not being able to distinguish ; and ,
on my particular terminal today):

In `man 2 strlcpy`,  or `man 2 strncpy`, and probably a few others the
forward declaration is in "regular font" not in bold/highighted color
for the type. for 2 readlink the forward declaration type is bolded. I
derive a visual clue from that to scan for the argument types.

Is there a particular style preferred? Either strlcpy/strncpy needs to
be also doing bold for the forward declaration or readlink should be
changed to not be bold on the forward declaration.

WDYT?

Thanks,
Dirk

Re: [BUG] typo in man2/readlink.2

[Alejandro Colomar]

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

Hi Dirk,

On 2026-04-15T23:57:12+0200, Dirk Müller wrote:
> Hi Alejandro,
> 
> On Wed, Apr 15, 2026 at 11:36 PM Alejandro Colomar <alx@kernel.org> wrote:
> 
> > That's not what readlink(2) documents.  readlink(2) has a semicolon (;)
> > after the fisrt 'size_t bufsiz'.  That means it's a forward declaration
> > of a function parameter, and not a real parameter declaration.
> 
> Ah, got it! Thanks for being patient with me. This made me realize
> what tricked me here (other than not being able to distinguish ; and ,
> on my particular terminal today):

:)

> 
> In `man 2 strlcpy`,  or `man 2 strncpy`, and probably a few others the
> forward declaration is in "regular font" not in bold/highighted color

That's correct.  We call it Roman font, BTW.

> for the type.

Both the type and the identifier should be in roman, actually.

> for 2 readlink the forward declaration type is bolded.

I can't reproduce that in my terminal.  I see the forward declaration of
the parameter in readlink(2) also in Roman.

> I derive a visual clue from that to scan for the argument types.

Yup.  The commit responsible for that was:

	$ git show 8eea66b8 -- man/man2/readlink.2;
	commit 8eea66b827a11bc8983da517499cc236c6cd97ba
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2025-06-06 13:27:02 +0200

	    man/: SYNOPSIS: 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/man2/readlink.2 b/man/man2/readlink.2
	index 8e543851..b6c663cd 100644
	--- a/man/man2/readlink.2
	+++ b/man/man2/readlink.2
	@@ -13,14 +13,14 @@ .SH SYNOPSIS
	 .nf
	 .B #include <unistd.h>
	 .P
	-.BI "ssize_t readlink(size_t " bufsiz ;
	+.BR "ssize_t readlink(" "size_t bufsiz;"
	 .BI "                 const char *restrict " path ,
	 .BI "                 char " buf "[restrict " bufsiz "], size_t " bufsiz );
	 .P
	 .BR "#include <fcntl.h>            " "/* Definition of " AT_* " constants */"
	 .B #include <unistd.h>
	 .P
	-.BI "ssize_t readlinkat(size_t " bufsiz ;
	+.BR "ssize_t readlinkat(" "size_t bufsiz;"
	 .BI "                 int " dirfd ", const char *restrict " path ,
	 .BI "                 char " buf "[restrict " bufsiz "], size_t " bufsiz );
	 .P

> Is there a particular style preferred? Either strlcpy/strncpy needs to
> be also doing bold for the forward declaration or readlink should be
> changed to not be bold on the forward declaration.

From what I can see (both when reading readlink(2) and strncpy(3), and
reading the diff pasted above), readlink is in Roman as expected.

If you can reproduce the difference, please share the details.  Maybe
there's something wrong that I'm not seeing.


Cheers,
Alex

> 
> WDYT?
> 
> Thanks,
> Dirk



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

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

Re: [BUG] typo in man2/readlink.2

[Dirk Müller]

Hi Alejandro,


> If you can reproduce the difference, please share the details.  Maybe
> there's something wrong that I'm not seeing.

Sorry for the noise, this was a downstream issue which I now resolved.
Thanks again for your help.

Greetings,
Dirk

Re: [BUG] typo in man2/readlink.2

[Alejandro Colomar]

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

Hi Dirk,

On 2026-04-17T08:41:22+0200, Dirk Müller wrote:
> Hi Alejandro,
> 
> 
> > If you can reproduce the difference, please share the details.  Maybe
> > there's something wrong that I'm not seeing.
> 
> Sorry for the noise,

No problem!

> this was a downstream issue which I now resolved.
> Thanks again for your help.

Nice!  You're welcome!  :-)


Have a lovely day!
Alex

> 
> Greetings,
> Dirk
> 

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

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