Skip to contentSkip to conversation

close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

PATCH Superseded Mark Wielaard 2 participants 3 messages Feb 7, 2024 – Feb 11, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

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.

---
 man2/close_range.2 | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
man2/close_range.2 +4 -1
index 380a47365..fd13ba645 100644
@@ -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 );
Signature · 1 line
2.43.0
#1 lore raw

Hi Mark,

Quoted 15 lines · 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.

---
 man2/close_range.2 | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
man2/close_range.2 +0 -0
index 380a47365..fd13ba645 100644

man2/close_range.2 Standard C library · line 17

Quoted 8 lines
man2/close_range.2 +4 -1
@@ -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 <[email protected]>
Date: Sun Aug 8 10:41:33 2021 +0200

close_range.2: Glibc added a wrapper recently

Fixes c2356ba085ed4f748b81c0ceeba1811b4a549e1c

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

commit c2356ba085ed4f748b81c0ceeba1811b4a549e1c
Author: Michael Kerrisk <[email protected]>
Date: Mon Jul 12 03:23:46 2021 +0200

close_range.2: Glibc 2.34 has added a close_range() wrapper

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

man2/close_range.2 Standard C library · line 20

Quoted 3 lines
man2/close_range.2 +0 -0
 .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

Signature · 2 lines
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.
#2 lore raw

Hi Alejandro,

Quoted 9 lines · Alejandro Colomar

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.

Quoted 21 lines
Quoted 3 lines

.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);
	}
Quoted 1 line

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