[PATCH] read.2: Fix mangled SYNOPSIS macro

[PATCH] read.2: Fix mangled SYNOPSIS macro

[Anmol Katiyar]

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);

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

Signed-off-by: Anmol Katiyar <anmol.katiyar24@spit.ac.in>
---
 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


-- 




*Disclaimer*
*This email and any files transmitted with it are 
confidential and intended solely for the use of the individual or entity to 
whom they are addressed. If you are not the named addressee you should not 
disseminate, distribute or copy this e-mail. Please notify the sender 
immediately by e-mail if you have received this e-mail by mistake and 
delete this e-mail from your system. If you are not the intended recipient 
you are notified that disclosing, copying, distributing or taking any 
action in reliance on the contents of this information is strictly 
prohibited.*

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

[Alejandro Colomar]

[-- 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 --]