Re: [PATCH] read.2: Fix mangled SYNOPSIS macro

[Alejandro Colomar <alx@kernel.org>]

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

Hi Anmol,

> Date: 2026-09-16 19:22:05+0530
> From: Anmol Katiyar <anmol.katiyar24@spit.ac.in>
>
> The .BR/.BI macro pair for the function prototype was broken:
> .BR alternates bold/roman rather than bold/italic, and a stray
> duplicate "size_t count;" fragment had been left in from an
> apparent botched conversion to the buf[.count] bounds-annotation
> style. This rendered as invalid C:
> 
>     ssize_t read(size_t count;
>                  int fd, void buf[count], size_t count);

This is valid GNU C (ignoring the array of void, of course.)

	$ cat r.c
	#include <stddef.h>
	#include <sys/types.h>

	ssize_t read_char(size_t count;
		          int fd, char buf[count], size_t count);
	$ gcc -Wall -Wextra -S r.c 
	$ 

See at the bottom of this page from the GCC documentation:
<https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html>

Here's the text as of gcc-15 (the documentation has improved a bit in
gcc-16, but the feature hasn't changed since decades ago):

	$ info gcc -n 'Variable Length' | sed -n '/arguments/,$p';
	 You can also use variable-length arrays as arguments to functions:

	     struct entry
	     tester (int len, char data[len][len])
	     {
	       /* ... */
	     }

	 The length of an array is computed once when the storage is allocated
	and is remembered for the scope of the array in case you access it with
	‘sizeof’.

	 If you want to pass the array first and the length afterward, you can
	use a forward declaration in the parameter list--another GNU extension.

	     struct entry
	     tester (int len; char data[len][len], int len)
	     {
	       /* ... */
	     }

	 The ‘int len’ before the semicolon is a “parameter forward
	declaration”, and it serves the purpose of making the name ‘len’ known
	when the declaration of ‘data’ is parsed.

	 You can write any number of such parameter forward declarations in the
	parameter list.  They can be separated by commas or semicolons, but the
	last one must end with a semicolon, which is followed by the "real"
	parameter declarations.  Each forward declaration must match a "real"
	declaration in parameter name and data type.  ISO C99 does not support
	parameter forward declarations.

> Replace with a single correct .BI call, matching the bounds-
> annotation convention used elsewhere in the page set.

The rest of the pages use the same convention as this page.
The convention using [.length] was used in the past, and was changed
precisely because it's not valid C.

> Signed-off-by: Anmol Katiyar <anmol.katiyar24@spit.ac.in>
> ---

Have a lovely day!
Alex

>  man/man2/read.2 | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/man/man2/read.2 b/man/man2/read.2
> index 8eb222743..c460a2a61 100644
> --- a/man/man2/read.2
> +++ b/man/man2/read.2
> @@ -14,8 +14,7 @@ Standard C library
>  .nf
>  .B #include <unistd.h>
>  .P
> -.BR "ssize_t read(" "size_t count;"
> -.BI "             int " fd ", void " buf [ count "], size_t " count );
> +.BI "ssize_t read(int " fd ", void " buf "[." count "], size_t " count );
>  .fi
>  .SH DESCRIPTION
>  .BR read ()
> -- 
> 2.55.0

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

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