Skip to contentSkip to conversation

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

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

lore
Share & tools
lore
#0 lore raw

PATCH v3 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 | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)
man2/close_range.2 +7 -4
index 380a47365..53ee5524e 100644
@@ -11,10 +11,14 @@ 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>" " /* Definition of " CLOSE_RANGE_* "
+.BR "" "                                  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 +209,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 +262,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 for the patch! I've tweaked it a little bit, and applied it:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=9dc4cba62c1d19ff3aa02e062e4a0c03f5299182>

Have a lovely night!
Alex

Quoted 45 lines
---
 man2/close_range.2 | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)
man2/close_range.2 +7 -4
index 380a47365..53ee5524e 100644
@@ -11,10 +11,14 @@ 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>" " /* Definition of " CLOSE_RANGE_* "
+.BR "" "                                  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 +209,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 +262,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 7 lines · Alejandro Colomar
Quoted 6 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.

Quoted 8 lines
Quoted 5 lines
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 for the patch! I've tweaked it a little bit, and applied it:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=9dc4cba62c1d19ff3aa02e062e4a0c03f5299182>

Thanks.

Note that there is now one line which is > 80 chars. You can fix that using this from the original fix, that splits and indents the comment on two lines:

Quoted 2 lines
Quoted 2 lines

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

Cheers,

Mark

#3 lore raw

Hi Mark,

Quoted 6 lines · Mark Wielaard

Note that there is now one line which is > 80 chars. You can fix that using this from the original fix, that splits and indents the comment on two lines:

Quoted 2 lines
Quoted 2 lines

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

Ahhh, I see. I'm using groff from git (what will be groff-1.24.0 some day), which changes the default indentation from 7 to 5, which is why it fits in the line for me. Thanks for reporting that! I'll fix it in a moment.

Cheers,
Alex

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

man page base paragraph inset/indentation (was: [PATCH v3] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS)

Hi folks,

Quoted 5 lines · Alejandro Colomar
Quoted 4 lines · Mark Wielaard

Note that there is now one line which is > 80 chars. You can fix that using this from the original fix, that splits and indents the comment on two lines:

Quoted 7 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

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

Ahhh, I see. I'm using groff from git (what will be groff-1.24.0 some day), which changes the default indentation from 7 to 5, which is why it fits in the line for me. Thanks for reporting that! I'll fix it in a moment.

This rendering parameter is now configurable, of course, to accommodate people who prefer the "old" one. So when generating cat pages, doing diffs, or similar, you can pass the following option to GNU troff(1):

-rBP=7n

This can be done for any version of GNU troff; versions of the GNU man(7) macro package that are too told will simply (and silently) ignore it, and use a base paragraph inset of 7n regardless.

Here's the NEWS item from the forthcoming groff 1.24.0.

o The an (man) and doc (mdoc) macro packages now support a BP register to configure the ("base") paragraph inset amount; that is the amount used by man(7) for paragraphs not within an RS/RE relative inset, and in mdoc(7) for all paragraphs. Formerly, the IN register configured this amount with other indentation and inset amount parameters used by man(7). (In mdoc(7), it had no other purpose.) The base paragraph indentation default is now 5n, corresponding to that used by historical man(7) and mdoc(7) implementations going back to Unix Version 7 (1979) and 4.3BSD-Reno (1990), respectively.

Ingo Schwarze has made a parallel change to mandoc(1), and I expect it to show up in the next release thereof.

https://cvsweb.bsd.lv/mandoc/man_term.c?rev=1.244&content-type=text/x-cvsweb-markup&sortby=date

Regards,
Branden

#5 lore raw

Re: man page base paragraph inset/indentation (was: [PATCH v3] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS)

Hi Branden,

Quoted 5 lines · G. Branden Robinson

This rendering parameter is now configurable, of course, to accommodate people who prefer the "old" one. So when generating cat pages, doing diffs, or similar, you can pass the following option to GNU troff(1):

-rBP=7n

Nah, I like 5n. I could use -RBP=7n in the build system for preventing errors like this one for the time 1.24.0 is not a thing, to catch those formatting issues with make check... but I think I prefer not.

Do you have in mind a date around which you intend to freeze for 1.24.0? Mind the time it will take from a freeze to a release, so we get it in Trixie this time. :)

Have a lovely day!
Alex

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

groff 1.24 scheduling thoughts (was: man page base paragraph inset/indentation)

[dropped Mark and Alexandra from CC, looping in groff@gnu]

Hi Alex,

Quoted 4 lines · Alejandro Colomar

Nah, I like 5n. I could use [-rBP=7n] in the build system for preventing errors like this one for the time 1.24.0 is not a thing, to catch those formatting issues with make check... but I think I prefer not.

Fair. That's why it's a knob. People can twist it or not. :)

Quoted 2 lines

Do you have in mind a date around which you intend to freeze for 1.24.0?

No. There are still several things I'd like to at least try to get done. There is a possibly ambitious "release goals" ticket for 1.24.

https://savannah.gnu.org/bugs/?65099

(Scroll down to see the dependencies.)

Integrating large/complex patches from contributors has proven difficult, and exposed my weaknesses as a project manager. Aggravating factors are (1) I'm the only person who writes regression or unit tests,
(2) I'm nearly the only one who writes documentation for anything except mom(7), and (3) some of the most desirable features are also those that require changes to undocumented or un(der)specified aspects of the system. For example, what _can_ you put in a device control escape sequence (or device control request, or "transparent output")? Can you spray out bytes with the eighth bit set that way? Should you be able to? If not, how do you encode them if you need them? Should each output driver take its own approach or should they share one? This stuff sounds obscure, but you need it for things like PDF bookmarks with non-ASCII characters in them, and better CJK font support.

Still, I think the pain will be worth it--when we crack those nuts, the reward will be pleasant.

The revelation of https://savannah.gnu.org/bugs/?65322 troubles me. On the one hand, since the bug has evidently been around a very long time, and isn't a security issue (the formatter merely gets angry and quits on--apparently--ill-formed input), there's no particular emergency. Still, the idea of stomping another decades-old bug that defeated everyone before me[1] appeals to my vanity. On the other hand, I am nearly clueless about the cause of it,[2] and to track it down I think I'll need to implement the "macro/string/diversion dumper" I've been contemplating, to force the formatter to reveal hidden knowledge.

That, or I could get a lot more skillful with GDB, but so far it seems like a disproportionate amount of the time, the problems I chase with it involve variables that are

$1 = <optimized out>

...even when you specify -O0 -ggdb. Hmm, thanks a lot. That sort of thing is not compatible with the integrity of the drywall in my home.

Quoted 2 lines

Mind the time it will take from a freeze to a release, so we get it in Trixie this time. :)

No doubt. It appeals to my sense of tidiness to have groff's minor release number match the calendar year modulo 100, so, given some experience, I think going for a release candidate this summer would be a good idea. We probably want to code-freeze no later than September 30th.

Regards,
Branden

[1] The bug is so obscure, that is likely not saying much.

[2] My hypothesis for the moment is that a "node"[3] is surviving inside a diversion when it shouldn't be, and while that appears not to be an opening brace node, I think it is something working like that. So the balance is being thrown off, and that is why GNU troff's "finish_get" function is encountering a value of the input level that it didn't expect. Data structures should be introspectable, but diversions are not, and we are finally paying the piper.

[3] A recent commit underscored just how unhelpfully opaque this data structure is, and yet for 30+ years this term has been hurled into the user's face if they screw up.

https://git.savannah.gnu.org/cgit/groff.git/commit/?id=90568dc1afe41c9f909f26e7e3fa6f9d499127bc

"Oh, great, it's a 'node'. Whatever that is."

And then when you gain a bit of experience...

"Oh, great, it's a node. That means it's one of about 20 different things--seriously, 20. No problem. This will be a cinch to debug."

I'd still like to meet James Clark for coffee some day. I will have much positive to say, and much appreciation to express.

But I will also have a look I want to give him.

Just a look.

#7 lore raw
In reply to Mark Wielaard

Hi Mark,

Quoted 6 lines · Mark Wielaard

Note that there is now one line which is > 80 chars. You can fix that using this from the original fix, that splits and indents the comment on two lines:

Quoted 2 lines
Quoted 2 lines

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

I've amended it with your original code, and also realized that we can put the function prototype in a single line now:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=2fe73d74a661e7a9122482b840150e6ef867cdd6>

man2/close_range.2 +4 -4
index bd5d10233..b0c9ef66e 100644
@@ -14,11 +14,11 @@ .SH SYNOPSIS
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <unistd.h>
 .P
-.BR "#include <linux/close_range.h>" " /* Definition of " CLOSE_RANGE_* \
-" constants */"
+.BR "#include <linux/close_range.h>" " /* Definition of " CLOSE_RANGE_* "
+.BR "" "                                  constants */"
 .P
-.BI "int close_range(unsigned int " first ", unsigned int " last ,
-.BI "                int " flags );
+.BI "int close_range(unsigned int " first ", unsigned int " last \
+", int " flags );
 .fi
 .SH DESCRIPTION
 The

Have a lovely day!
Alex

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