[PATCH] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

[PATCH] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

[Mark Wielaard]

close_range is defined in unistd.h when _GNU_SOURCE is defined.
The linux/close_range.h include file only defines the (linux specific)
flags constants.

Reported-by: Alexandra Hájková <ahajkova@redhat.com>
Signed-off-by: Mark Wielaard <mark@klomp.org>
---
 man2/close_range.2 | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/man2/close_range.2 b/man2/close_range.2
index 380a47365..fd13ba645 100644
--- a/man2/close_range.2
+++ b/man2/close_range.2
@@ -11,7 +11,10 @@ Standard C library
 .RI ( libc ", " \-lc )
 .SH SYNOPSIS
 .nf
-.B #include <linux/close_range.h>
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.P
+.BR "#include <linux/close_range.h>" "  /* For the flags constants */"
 .P
 .BI "int close_range(unsigned int " first ", unsigned int " last ,
 .BI "                unsigned int " flags );
-- 
2.43.0

Re: [PATCH] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

[Alejandro Colomar]

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

Hi Mark,

On Wed, Feb 07, 2024 at 11:17:06AM +0100, Mark Wielaard wrote:
> close_range is defined in unistd.h when _GNU_SOURCE is defined.
> The linux/close_range.h include file only defines the (linux specific)
> flags constants.
> 
> Reported-by: Alexandra Hájková <ahajkova@redhat.com>
> Signed-off-by: Mark Wielaard <mark@klomp.org>
> ---
>  man2/close_range.2 | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/close_range.2 b/man2/close_range.2
> index 380a47365..fd13ba645 100644
> --- a/man2/close_range.2
> +++ b/man2/close_range.2
> @@ -11,7 +11,10 @@ Standard C library
>  .RI ( libc ", " \-lc )
>  .SH SYNOPSIS
>  .nf
> -.B #include <linux/close_range.h>
> +.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
> +.B #include <unistd.h>
> +.P
> +.BR "#include <linux/close_range.h>" "  /* For the flags constants */"

It seems this page was written when there was still no wrapper in libc.

But I see that Michael and I did mention there's now a wrapper in glibc:

	commit 71a62d6c3c56b2cec56858f19b8b419c1355db17
	Author: Alejandro Colomar <alx.manpages@gmail.com>
	Date:   Sun Aug 8 10:41:33 2021 +0200

	    close_range.2: Glibc added a wrapper recently
	    
	    Fixes: c2356ba085ed4f748b81c0ceeba1811b4a549e1c
	    Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
	    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

	 man2/close_range.2 | 5 -----
	 1 file changed, 5 deletions(-)

	commit c2356ba085ed4f748b81c0ceeba1811b4a549e1c
	Author: Michael Kerrisk <mtk.manpages@gmail.com>
	Date:   Mon Jul 12 03:23:46 2021 +0200

	    close_range.2: Glibc 2.34 has added a close_range() wrapper
	    
	    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

	 man2/close_range.2 | 1 +
	 1 file changed, 1 insertion(+)

Both of those commits forgot to update the SYNOPSIS.  So, please add the
following tags to your commit message:

Fixes: 71a62d6c3c56 ("close_range.2: Glibc added a wrapper recently")
Fixes: c2356ba085ed ("close_range.2: Glibc 2.34 has added a close_range() wrapper")

>  .P
>  .BI "int close_range(unsigned int " first ", unsigned int " last ,
>  .BI "                unsigned int " flags );

And I notice the glibc wrapper is slightly different from the Linux
kernel system call:

	$ grepc close_range /usr/include/
	/usr/include/unistd.h:extern int close_range (unsigned int __fd, unsigned int __max_fd,
				int __flags) __THROW;


	$ grepc -tfl close_range ~/src/linux/linux/master/
	/home/alx/src/linux/linux/master/include/linux/syscalls.h:asmlinkage long sys_close_range(unsigned int fd, unsigned int max_fd,
					unsigned int flags);
	/home/alx/src/linux/linux/master/fs/open.c:SYSCALL_DEFINE3(close_range, unsigned int, fd, unsigned int, max_fd,
			unsigned int, flags)
	{
		return __close_range(fd, max_fd, flags);
	}

The third parameter is an 'int' in glibc.  Please also update that.

Thanks for the patch.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: [PATCH] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

[Mark Wielaard]

Hi Alejandro,

On Sun, Feb 11, 2024 at 07:49:53PM +0100, Alejandro Colomar wrote:
> It seems this page was written when there was still no wrapper in libc.
> 
> But I see that Michael and I did mention there's now a wrapper in glibc:
> [...] 
> Both of those commits forgot to update the SYNOPSIS.  So, please add the
> following tags to your commit message:
> 
> Fixes: 71a62d6c3c56 ("close_range.2: Glibc added a wrapper recently")
> Fixes: c2356ba085ed ("close_range.2: Glibc 2.34 has added a close_range() wrapper")

I missed thos, will add the Fixes: to v2.

> >  .P
> >  .BI "int close_range(unsigned int " first ", unsigned int " last ,
> >  .BI "                unsigned int " flags );
> 
> And I notice the glibc wrapper is slightly different from the Linux
> kernel system call:
> 
> 	$ grepc close_range /usr/include/
> 	/usr/include/unistd.h:extern int close_range (unsigned int __fd, unsigned int __max_fd,
> 				int __flags) __THROW;
> 
> 
> 	$ grepc -tfl close_range ~/src/linux/linux/master/
> 	/home/alx/src/linux/linux/master/include/linux/syscalls.h:asmlinkage long sys_close_range(unsigned int fd, unsigned int max_fd,
> 					unsigned int flags);
> 	/home/alx/src/linux/linux/master/fs/open.c:SYSCALL_DEFINE3(close_range, unsigned int, fd, unsigned int, max_fd,
> 			unsigned int, flags)
> 	{
> 		return __close_range(fd, max_fd, flags);
> 	}
> 
> The third parameter is an 'int' in glibc.  Please also update that.

Will do. I see freebsd also uses int for flags.

I also noted just now that the example code still uses
syscall(SYS_close_range, 3, ~0U, 0)
even though it defines _GNU_SOURCE and includes unistd.h.
Will also fix that for v2.

Cheers,

Mark