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

[PATCH v3] 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. 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")

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

diff --git a/man2/close_range.2 b/man2/close_range.2
index 380a47365..53ee5524e 100644
--- a/man2/close_range.2
+++ b/man2/close_range.2
@@ -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);
     }
-- 
2.39.3

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

[Alejandro Colomar]

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

Hi Mark,

On Mon, Feb 12, 2024 at 01:07:04PM +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. 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")
> 
> Reported-by: Alexandra Hájková <ahajkova@redhat.com>
> Signed-off-by: Mark Wielaard <mark@klomp.org>

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

> ---
>  man2/close_range.2 | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/man2/close_range.2 b/man2/close_range.2
> index 380a47365..53ee5524e 100644
> --- a/man2/close_range.2
> +++ b/man2/close_range.2
> @@ -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);
>      }
> -- 
> 2.39.3
> 

-- 
<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 v3] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

[Mark Wielaard]

Hi Alejandro,

On Sun, Feb 18, 2024 at 02:09:48AM +0100, Alejandro Colomar wrote:
> On Mon, Feb 12, 2024 at 01:07:04PM +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. 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")
> > 
> > Reported-by: Alexandra Hájková <ahajkova@redhat.com>
> > Signed-off-by: Mark Wielaard <mark@klomp.org>
> 
> 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:

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

Cheers,

Mark

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

[Alejandro Colomar]

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

Hi Mark,

On Sun, Feb 18, 2024 at 01:00:35PM +0100, Mark Wielaard wrote:
> 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:
> 
> > > +.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

-- 
<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 v3] close_range.2: Add _GNU_SOURCE and unistd.h to SYNOPSIS

[Alejandro Colomar]

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

Hi Mark,

On Sun, Feb 18, 2024 at 01:00:35PM +0100, Mark Wielaard wrote:
> 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:
> 
> > > +.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>

diff --git a/man2/close_range.2 b/man2/close_range.2
index bd5d10233..b0c9ef66e 100644
--- a/man2/close_range.2
+++ b/man2/close_range.2
@@ -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

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

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

[G. Branden Robinson]

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

Hi folks,

At 2024-02-18T14:08:59+0100, Alejandro Colomar wrote:
> On Sun, Feb 18, 2024 at 01:00:35PM +0100, Mark Wielaard wrote:
> > 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:
> > 
> > > > +.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

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

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

[Alejandro Colomar]

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

Hi Branden,

On Sun, Feb 18, 2024 at 08:14:47AM -0600, G. Branden Robinson wrote:
> 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

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

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

[G. Branden Robinson]

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

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

Hi Alex,

At 2024-02-18T16:18:38+0100, Alejandro Colomar wrote:
> 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.  :)

> 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.

> 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.

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