Skip to contentSkip to conversation

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

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

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 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. The flags argument is an int, not an unsigned int, in the glibc wrapper. Use the close_range library call in the example code instead of syscall.

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 | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
man2/close_range.2 +6 -4
index 380a47365..62b728e96 100644
@@ -11,10 +11,13 @@ 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 );
+.BI "                int " flags );
 .fi
 .SH DESCRIPTION
 The
@@ -205,7 +208,6 @@ result from the calls to
 #include <limits.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <sys/syscall.h>
 #include <unistd.h>
 \&
 /* Show the contents of the symbolic links in /proc/self/fd */
@@ -259,7 +261,7 @@ main(int argc, char *argv[])
 \&
     printf("========= About to call close_range() =======\en");
 \&
-    if (syscall(SYS_close_range, 3, \[ti]0U, 0) == \-1) {
+    if (close_range(3, \[ti]0U, 0) == \-1) {
         perror("close_range");
         exit(EXIT_FAILURE);
     }
Signature · 1 line
2.39.3
#1 lore raw

Hi Mark,

Quoted 11 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. The flags argument is an int, not an unsigned int, in the glibc wrapper. Use the close_range library call in the example code instead of syscall.

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

Thanks! LGTM, but please check a small comment below.

Quoted 9 lines
---
 man2/close_range.2 | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
man2/close_range.2 +0 -0
index 380a47365..62b728e96 100644

man2/close_range.2 Standard C library · line 17

Quoted 8 lines
man2/close_range.2 +4 -1
@@ -11,10 +11,13 @@ 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 */"

Could you please format the comment like other pages that do the same thing? See for example membarrier(2).

Have a lovely night!
Alex

Quoted 28 lines
man2/close_range.2 +2 -3
 .P
 .BI "int close_range(unsigned int " first ", unsigned int " last ,
-.BI "                unsigned int " flags );
+.BI "                int " flags );
 .fi
 .SH DESCRIPTION
 The
@@ -205,7 +208,6 @@ result from the calls to
 #include <limits.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <sys/syscall.h>
 #include <unistd.h>
 \&
 /* Show the contents of the symbolic links in /proc/self/fd */
@@ -259,7 +261,7 @@ main(int argc, char *argv[])
 \&
     printf("========= About to call close_range() =======\en");
 \&
-    if (syscall(SYS_close_range, 3, \[ti]0U, 0) == \-1) {
+    if (close_range(3, \[ti]0U, 0) == \-1) {
         perror("close_range");
         exit(EXIT_FAILURE);
     }
Signature · 1 line
2.39.3
Signature · 2 lines
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.
#2 lore raw

Hi Alejandro,

Quoted 6 lines · Alejandro Colomar

Thanks! LGTM, but please check a small comment below.

Quoted 4 lines
---
 man2/close_range.2 | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
Quoted 16 lines

man2/close_range.2 Standard C library · line 17

Quoted 13 lines
man2/close_range.2 +4 -1
index 380a47365..62b728e96 100644
@@ -11,10 +11,13 @@ 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 */"

Could you please format the comment like other pages that do the same thing? See for example membarrier(2).

Sorry, you have to be more explicit what exactly you believe is not the same thing that other pages do. membarrier.2 doesn't need a _GNU_SOURCE define and I believe I used the comment as other pages that do.

Cheers,

Mark

#3 lore raw

Hi Mark,

Quoted 8 lines · Mark Wielaard
Quoted 8 lines
Quoted 7 lines

.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 */"

Quoted 7 lines
Quoted 2 lines

Could you please format the comment like other pages that do the same thing? See for example membarrier(2).

Sorry, you have to be more explicit what exactly you believe is not the same thing that other pages do. membarrier.2 doesn't need a _GNU_SOURCE define and I believe I used the comment as other pages that do.

Sure; no problem!

When we include a header not for a function but for constants, we specify which are those constants. For example, membarrier(2) has

     #include <linux/membarrier.h> /* Definition of MEMBARRIER_* constants */
     #include <sys/syscall.h>      /* Definition of SYS_* constants */

Here, I'd use

     #include <linux/close_range.h> /* Definition of CLOSE_RANGE_* constants */

BTW, I notice that it's near the 80-column limit. We try to limit ourselves to 79 columns, for an obscure reason. For that, we'll need to use only 1 space before the comment (otherwise, I'd agree to use 2).

Have a lovely night!
Alex

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

Hi Alejandro,

Quoted 6 lines · Alejandro Colomar

When we include a header not for a function but for constants, we specify which are those constants. For example, membarrier(2) has

     #include <linux/membarrier.h> /* Definition of MEMBARRIER_* constants */
     #include <sys/syscall.h>      /* Definition of SYS_* constants */

Aha, ok, the other comment. Will reword for V3.

Quoted 6 lines

Here, I'd use

     #include <linux/close_range.h> /* Definition of CLOSE_RANGE_* constants */

BTW, I notice that it's near the 80-column limit. We try to limit ourselves to 79 columns, for an obscure reason. For that, we'll need to use only 1 space before the comment (otherwise, I'd agree to use 2).

Yeah, max 79 max sense (all my terminals are 80 chars wide). Formatting the comment is a little tricky, but I believe I got it.

Cheers,

Mark