[PATCH 00/23] More patches from others

[PATCH 00/23] More patches from others

[Alejandro Colomar]

Hello, Michael!

Here's another patch set with patches from others,
and a few small fixes of mine.

Cheers,

Alex



Alejandro Colomar (7):
  sigaction.2: Apply minor tweaks to Peter's patch
  futex.2: Minor tweaks to Kurt's patch
  getopt.3: Minor tweak to James's patch
  termios.3: ffix
  mount_setattr.2: Minor tweaks to Chirstian's patch
  ldd.1: Fix example command
  close_range.2: Glibc added a wrapper recently

Christian Brauner (1):
  mount_setattr.2: New manual page documenting the mount_setattr()
    system call

G. Branden Robinson (1):
  man-pages.7: wfix

James O. D. Hunt (1):
  getopt.3: Further clarification of optstring

Kurt Kanzenbach (1):
  futex.2: Document FUTEX_LOCK_PI2

Michael Weiß (1):
  namespaces.7: ffix

Mike Rapoport (1):
  man2: new page describing memfd_secret() system call

Pali Rohár (6):
  termios.3: Document missing baudrate constants
  termios.3: Use bold style for Bnn and EXTn macro constants
  ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2
  ioctl_tty.2: Update DTR example
  termios.3: Add information how to set baud rate to any other value
  termios.3: SPARC architecture has 4 different Bnnn constants

Peter Collingbourne (1):
  sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection
    protocol

Štěpán Němec (1):
  unix.7: tfix

наб (2):
  pipe.7: also mention writev(2) in atomicity section
  regex.3: wfix

 man1/ldd.1           |    5 +-
 man2/close_range.2   |    5 -
 man2/futex.2         |  111 +++--
 man2/ioctl_tty.2     |   32 +-
 man2/memfd_secret.2  |  146 ++++++
 man2/mount_setattr.2 | 1006 ++++++++++++++++++++++++++++++++++++++++++
 man2/sigaction.2     |  133 ++++++
 man3/getopt.3        |   10 +-
 man3/regex.3         |    4 +-
 man3/termios.3       |   74 +++-
 man7/man-pages.7     |    2 +-
 man7/namespaces.7    |    3 +-
 man7/pipe.7          |    2 +
 man7/unix.7          |    2 +-
 14 files changed, 1478 insertions(+), 57 deletions(-)
 create mode 100644 man2/memfd_secret.2
 create mode 100644 man2/mount_setattr.2

-- 
2.32.0

[PATCH 01/23] pipe.7: also mention writev(2) in atomicity section

[Alejandro Colomar]

From: наб <nabijaczleweli@nabijaczleweli.xyz>

writev(2) notes that buffers don't interleave with other process'
(a reasonable question to ask), but points to pipe(7) for an exception.
pipe(7) did /not/ mention "writev", "iov", "scat", or "gath", which are,
in order, reasonable search terms: this was confusing at best and
alarming at worst

By mentioning writev(2) in the heading, we clearly note that this sort
of interleaving behaviour matches write(2)'s and isn't a concern

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/pipe.7 | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/man7/pipe.7 b/man7/pipe.7
index c3210320c..29f6cf6cb 100644
--- a/man7/pipe.7
+++ b/man7/pipe.7
@@ -246,6 +246,8 @@ limits; see BUGS.
 .SS PIPE_BUF
 POSIX.1 says that
 .BR write (2)s
+and
+.BR writev (2)s
 of less than
 .B PIPE_BUF
 bytes must be atomic: the output data is written to the pipe as a
-- 
2.32.0

Re: [PATCH 01/23] pipe.7: also mention writev(2) in atomicity section

[Alejandro Colomar (man-pages)]

Hi Michael,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: наб <nabijaczleweli@nabijaczleweli.xyz>
> 
> writev(2) notes that buffers don't interleave with other process'
> (a reasonable question to ask), but points to pipe(7) for an exception.
> pipe(7) did /not/ mention "writev", "iov", "scat", or "gath", which are,
> in order, reasonable search terms: this was confusing at best and
> alarming at worst
> 
> By mentioning writev(2) in the heading, we clearly note that this sort
> of interleaving behaviour matches write(2)'s and isn't a concern
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Oops, drop this one that I already sent in the previous set.

Cheers,

Alex

> ---
>  man7/pipe.7 | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/man7/pipe.7 b/man7/pipe.7
> index c3210320c..29f6cf6cb 100644
> --- a/man7/pipe.7
> +++ b/man7/pipe.7
> @@ -246,6 +246,8 @@ limits; see BUGS.
>  .SS PIPE_BUF
>  POSIX.1 says that
>  .BR write (2)s
> +and
> +.BR writev (2)s
>  of less than
>  .B PIPE_BUF
>  bytes must be atomic: the output data is written to the pipe as a
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH 01/23] pipe.7: also mention writev(2) in atomicity section

[Michael Kerrisk (man-pages)]

On 8/8/21 3:20 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 8/8/21 10:41 AM, Alejandro Colomar wrote:
>> From: наб <nabijaczleweli@nabijaczleweli.xyz>
>>
>> writev(2) notes that buffers don't interleave with other process'
>> (a reasonable question to ask), but points to pipe(7) for an exception.
>> pipe(7) did /not/ mention "writev", "iov", "scat", or "gath", which are,
>> in order, reasonable search terms: this was confusing at best and
>> alarming at worst
>>
>> By mentioning writev(2) in the heading, we clearly note that this sort
>> of interleaving behaviour matches write(2)'s and isn't a concern
>>
>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> 
> Oops, drop this one that I already sent in the previous set.

Dropped.

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 02/23] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol

[Alejandro Colomar]

From: Peter Collingbourne <pcc@google.com>

Signed-off-by: Peter Collingbourne <pcc@google.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/sigaction.2 | 123 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 57ad6418c..4bf6f095e 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -261,6 +261,44 @@ This flag is meaningful only when establishing a signal handler.
 .\" .I sa_sigaction
 .\" field was added in Linux 2.1.86.)
 .\"
+.TP
+.B SA_UNSUPPORTED
+Used to dynamically probe for flag bit support.
+.IP
+If an attempt to register a handler succeeds with this flag set in
+.I act->sa_flags
+alongside other flags that are potentially unsupported by the kernel,
+and an immediately subsequent
+.BR sigaction ()
+call specifying the same signal number n and with non-NULL
+.I oldact
+yields
+.B SA_UNSUPPORTED
+.I clear
+in
+.IR oldact->sa_flags ,
+then
+.I oldact->sa_flags
+may be used as a bitmask
+describing which of the potentially unsupported flags are,
+in fact, supported.
+See the section "Dynamically probing for flag bit support"
+below for more details.
+.TP
+.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)"
+Normally, when delivering a signal,
+an architecture-specific set of tag bits are cleared from the
+.I si_addr
+field of
+.IR siginfo_t .
+If this flag is set,
+an architecture-specific subset of the tag bits will be preserved in
+.IR si_addr .
+.IP
+Programs that need to be compatible with Linux versions older than 5.11
+must use
+.B SA_UNSUPPORTED
+to probe for support.
 .SS The siginfo_t argument to a SA_SIGINFO handler
 When the
 .B SA_SIGINFO
@@ -846,6 +884,91 @@ Triggered by a
 .BR seccomp (2)
 filter rule.
 .RE
+.SS Dynamically probing for flag bit support
+The
+.BR sigaction ()
+call on Linux accepts unknown bits set in
+.I act->sa_flags
+without error.
+The behavior of the kernel starting with Linux 5.11 is that a second
+.BR sigaction ()
+will clear unknown bits from
+.IR oldact->sa_flags .
+However, historically, a second
+.BR sigaction ()
+call would typically leave those bits set in
+.IR oldact->sa_flags .
+.PP
+This means that support for new flags cannot be detected
+simply by testing for a flag in
+.IR sa_flags ,
+and a program must test that
+.B SA_UNSUPPORTED
+has been cleared before relying on the contents of
+.IR sa_flags .
+.PP
+Since the behavior of the signal handler cannot be guaranteed
+unless the check passes,
+it is wise to either block the affected signal
+while registering the handler and performing the check in this case,
+or where this is not possible,
+for example if the signal is synchronous, to issue the second
+.BR sigaction ()
+in the signal handler itself.
+.PP
+In kernels that do not support a specific flag,
+the kernel's behavior is as if the flag was not set,
+even if the flag was set in
+.IR act->sa_flags .
+.PP
+The flags
+.BR SA_NOCLDSTOP ,
+.BR SA_NOCLDWAIT ,
+.BR SA_SIGINFO ,
+.BR SA_ONSTACK ,
+.BR SA_RESTART ,
+.BR SA_NODEFER ,
+.BR SA_RESETHAND ,
+and, if defined by the architecture,
+.B SA_RESTORER
+may not be reliably probed for using this mechanism,
+because they were introduced before Linux 5.11.
+However, in general, programs may assume that these flags are supported,
+since they have all been supported since Linux 2.6,
+which was released in the year 2003.
+.PP
+The following example program exits with status 0 if
+.B SA_EXPOSE_TAGBITS
+is determined to be supported, and 1 otherwise.
+.PP
+.EX
+#include <signal.h>
+#include <stdio.h>
+#include <unistd.h>
+
+void handler(int signo, siginfo_t *info, void *context) {
+    struct sigaction oldact;
+    if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
+        !(oldact.sa_flags & SA_UNSUPPORTED) &&
+        (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
+        _exit(0);
+    } else {
+        _exit(1);
+    }
+}
+
+int main(void) {
+    struct sigaction act = {0};
+    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
+    act.sa_sigaction = handler;
+    if (sigaction(SIGSEGV, &act, 0) != 0) {
+        perror("sigaction");
+        return 1;
+    }
+
+    raise(SIGSEGV);
+}
+.EE
 .SH RETURN VALUE
 .BR sigaction ()
 returns 0 on success; on error, \-1 is returned, and
-- 
2.32.0

Re: [PATCH 02/23] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol

[Michael Kerrisk (man-pages)]

Hello Peter and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Peter Collingbourne <pcc@google.com>
> 
> Signed-off-by: Peter Collingbourne <pcc@google.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks for this patch Peter. Applied.

Cheers,

Michael

> ---
>  man2/sigaction.2 | 123 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 123 insertions(+)
> 
> diff --git a/man2/sigaction.2 b/man2/sigaction.2
> index 57ad6418c..4bf6f095e 100644
> --- a/man2/sigaction.2
> +++ b/man2/sigaction.2
> @@ -261,6 +261,44 @@ This flag is meaningful only when establishing a signal handler.
>  .\" .I sa_sigaction
>  .\" field was added in Linux 2.1.86.)
>  .\"
> +.TP
> +.B SA_UNSUPPORTED
> +Used to dynamically probe for flag bit support.
> +.IP
> +If an attempt to register a handler succeeds with this flag set in
> +.I act->sa_flags
> +alongside other flags that are potentially unsupported by the kernel,
> +and an immediately subsequent
> +.BR sigaction ()
> +call specifying the same signal number n and with non-NULL
> +.I oldact
> +yields
> +.B SA_UNSUPPORTED
> +.I clear
> +in
> +.IR oldact->sa_flags ,
> +then
> +.I oldact->sa_flags
> +may be used as a bitmask
> +describing which of the potentially unsupported flags are,
> +in fact, supported.
> +See the section "Dynamically probing for flag bit support"
> +below for more details.
> +.TP
> +.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)"
> +Normally, when delivering a signal,
> +an architecture-specific set of tag bits are cleared from the
> +.I si_addr
> +field of
> +.IR siginfo_t .
> +If this flag is set,
> +an architecture-specific subset of the tag bits will be preserved in
> +.IR si_addr .
> +.IP
> +Programs that need to be compatible with Linux versions older than 5.11
> +must use
> +.B SA_UNSUPPORTED
> +to probe for support.
>  .SS The siginfo_t argument to a SA_SIGINFO handler
>  When the
>  .B SA_SIGINFO
> @@ -846,6 +884,91 @@ Triggered by a
>  .BR seccomp (2)
>  filter rule.
>  .RE
> +.SS Dynamically probing for flag bit support
> +The
> +.BR sigaction ()
> +call on Linux accepts unknown bits set in
> +.I act->sa_flags
> +without error.
> +The behavior of the kernel starting with Linux 5.11 is that a second
> +.BR sigaction ()
> +will clear unknown bits from
> +.IR oldact->sa_flags .
> +However, historically, a second
> +.BR sigaction ()
> +call would typically leave those bits set in
> +.IR oldact->sa_flags .
> +.PP
> +This means that support for new flags cannot be detected
> +simply by testing for a flag in
> +.IR sa_flags ,
> +and a program must test that
> +.B SA_UNSUPPORTED
> +has been cleared before relying on the contents of
> +.IR sa_flags .
> +.PP
> +Since the behavior of the signal handler cannot be guaranteed
> +unless the check passes,
> +it is wise to either block the affected signal
> +while registering the handler and performing the check in this case,
> +or where this is not possible,
> +for example if the signal is synchronous, to issue the second
> +.BR sigaction ()
> +in the signal handler itself.
> +.PP
> +In kernels that do not support a specific flag,
> +the kernel's behavior is as if the flag was not set,
> +even if the flag was set in
> +.IR act->sa_flags .
> +.PP
> +The flags
> +.BR SA_NOCLDSTOP ,
> +.BR SA_NOCLDWAIT ,
> +.BR SA_SIGINFO ,
> +.BR SA_ONSTACK ,
> +.BR SA_RESTART ,
> +.BR SA_NODEFER ,
> +.BR SA_RESETHAND ,
> +and, if defined by the architecture,
> +.B SA_RESTORER
> +may not be reliably probed for using this mechanism,
> +because they were introduced before Linux 5.11.
> +However, in general, programs may assume that these flags are supported,
> +since they have all been supported since Linux 2.6,
> +which was released in the year 2003.
> +.PP
> +The following example program exits with status 0 if
> +.B SA_EXPOSE_TAGBITS
> +is determined to be supported, and 1 otherwise.
> +.PP
> +.EX
> +#include <signal.h>
> +#include <stdio.h>
> +#include <unistd.h>
> +
> +void handler(int signo, siginfo_t *info, void *context) {
> +    struct sigaction oldact;
> +    if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
> +        !(oldact.sa_flags & SA_UNSUPPORTED) &&
> +        (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
> +        _exit(0);
> +    } else {
> +        _exit(1);
> +    }
> +}
> +
> +int main(void) {
> +    struct sigaction act = {0};
> +    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
> +    act.sa_sigaction = handler;
> +    if (sigaction(SIGSEGV, &act, 0) != 0) {
> +        perror("sigaction");
> +        return 1;
> +    }
> +
> +    raise(SIGSEGV);
> +}
> +.EE
>  .SH RETURN VALUE
>  .BR sigaction ()
>  returns 0 on success; on error, \-1 is returned, and
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 03/23] sigaction.2: Apply minor tweaks to Peter's patch

[Alejandro Colomar]

- Move example program to a new EXAMPLES section
- Invert logic in the handler to have the failure in the conditional path,
  and the success out of any conditionals.
- Use NULL, EXIT_SUCCESS, and EXIT_FAILURE instead of magic numbers
- Separate declarations from code
- Put function return type on its own line
- Put function opening brace on its line

Cc: Peter Collingbourne <pcc@google.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/sigaction.2 | 76 +++++++++++++++++++++++++++---------------------
 1 file changed, 43 insertions(+), 33 deletions(-)

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 4bf6f095e..18404dde1 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -936,39 +936,6 @@ because they were introduced before Linux 5.11.
 However, in general, programs may assume that these flags are supported,
 since they have all been supported since Linux 2.6,
 which was released in the year 2003.
-.PP
-The following example program exits with status 0 if
-.B SA_EXPOSE_TAGBITS
-is determined to be supported, and 1 otherwise.
-.PP
-.EX
-#include <signal.h>
-#include <stdio.h>
-#include <unistd.h>
-
-void handler(int signo, siginfo_t *info, void *context) {
-    struct sigaction oldact;
-    if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
-        !(oldact.sa_flags & SA_UNSUPPORTED) &&
-        (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
-        _exit(0);
-    } else {
-        _exit(1);
-    }
-}
-
-int main(void) {
-    struct sigaction act = {0};
-    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
-    act.sa_sigaction = handler;
-    if (sigaction(SIGSEGV, &act, 0) != 0) {
-        perror("sigaction");
-        return 1;
-    }
-
-    raise(SIGSEGV);
-}
-.EE
 .SH RETURN VALUE
 .BR sigaction ()
 returns 0 on success; on error, \-1 is returned, and
@@ -1174,6 +1141,49 @@ This bug was fixed in kernel 2.6.14.
 .SH EXAMPLES
 See
 .BR mprotect (2).
+.PP
+The following example program exits with status
+.B EXIT_SUCCESS
+if
+.B SA_EXPOSE_TAGBITS
+is determined to be supported, and
+.B EXIT_FAILURE
+otherwise.
+.PP
+.EX
+#include <signal.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <unistd.h>
+
+void
+handler(int signo, siginfo_t *info, void *context)
+{
+    struct sigaction oldact;
+
+    if (sigaction(SIGSEGV, NULL, &oldact) != 0 ||
+        (oldact.sa_flags & SA_UNSUPPORTED) ||
+        !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
+        _exit(EXIT_FAILURE);
+    }
+    _exit(EXIT_SUCCESS);
+}
+
+int
+main(void)
+{
+    struct sigaction act = {0};
+
+    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
+    act.sa_sigaction = &handler;
+    if (sigaction(SIGSEGV, &act, NULL) != 0) {
+        perror("sigaction");
+        exit(EXIT_FAILURE);
+    }
+
+    raise(SIGSEGV);
+}
+.EE
 .SH SEE ALSO
 .BR kill (1),
 .BR kill (2),
-- 
2.32.0

Re: [PATCH 03/23] sigaction.2: Apply minor tweaks to Peter's patch

[Michael Kerrisk (man-pages)]

Hi Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> - Move example program to a new EXAMPLES section

Not a big thing, but perhaps it would have been nicer to have 
two patches, the first doing the pieces below, and the second
doing the step above. That would enable me to more easily see
what changes you made below. But, I am not sure; maybe that
is more work than is justified...

> - Invert logic in the handler to have the failure in the conditional path,
>   and the success out of any conditionals.
> - Use NULL, EXIT_SUCCESS, and EXIT_FAILURE instead of magic numbers
> - Separate declarations from code
> - Put function return type on its own line
> - Put function opening brace on its line
> 
> Cc: Peter Collingbourne <pcc@google.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/sigaction.2 | 76 +++++++++++++++++++++++++++---------------------
>  1 file changed, 43 insertions(+), 33 deletions(-)
> 
> diff --git a/man2/sigaction.2 b/man2/sigaction.2
> index 4bf6f095e..18404dde1 100644
> --- a/man2/sigaction.2
> +++ b/man2/sigaction.2
> @@ -936,39 +936,6 @@ because they were introduced before Linux 5.11.
>  However, in general, programs may assume that these flags are supported,
>  since they have all been supported since Linux 2.6,
>  which was released in the year 2003.
> -.PP
> -The following example program exits with status 0 if
> -.B SA_EXPOSE_TAGBITS
> -is determined to be supported, and 1 otherwise.
> -.PP
> -.EX
> -#include <signal.h>
> -#include <stdio.h>
> -#include <unistd.h>
> -
> -void handler(int signo, siginfo_t *info, void *context) {
> -    struct sigaction oldact;
> -    if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
> -        !(oldact.sa_flags & SA_UNSUPPORTED) &&
> -        (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
> -        _exit(0);
> -    } else {
> -        _exit(1);
> -    }
> -}
> -
> -int main(void) {
> -    struct sigaction act = {0};
> -    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
> -    act.sa_sigaction = handler;
> -    if (sigaction(SIGSEGV, &act, 0) != 0) {
> -        perror("sigaction");
> -        return 1;
> -    }
> -
> -    raise(SIGSEGV);
> -}
> -.EE
>  .SH RETURN VALUE
>  .BR sigaction ()
>  returns 0 on success; on error, \-1 is returned, and
> @@ -1174,6 +1141,49 @@ This bug was fixed in kernel 2.6.14.
>  .SH EXAMPLES
>  See
>  .BR mprotect (2).
> +.PP
> +The following example program exits with status
> +.B EXIT_SUCCESS
> +if
> +.B SA_EXPOSE_TAGBITS
> +is determined to be supported, and
> +.B EXIT_FAILURE
> +otherwise.
> +.PP
> +.EX
> +#include <signal.h>
> +#include <stdlib.h>
> +#include <stdio.h>
> +#include <unistd.h>
> +
> +void
> +handler(int signo, siginfo_t *info, void *context)
> +{
> +    struct sigaction oldact;
> +
> +    if (sigaction(SIGSEGV, NULL, &oldact) != 0 ||
> +        (oldact.sa_flags & SA_UNSUPPORTED) ||
> +        !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
> +        _exit(EXIT_FAILURE);
> +    }
> +    _exit(EXIT_SUCCESS);
> +}
> +
> +int
> +main(void)
> +{
> +    struct sigaction act = {0};
> +
> +    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
> +    act.sa_sigaction = &handler;
> +    if (sigaction(SIGSEGV, &act, NULL) != 0) {
> +        perror("sigaction");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    raise(SIGSEGV);
> +}
> +.EE
>  .SH SEE ALSO
>  .BR kill (1),
>  .BR kill (2),

All looks good. I also had some additional fixes (2 patches). See below.

Cheers,

Michael

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 5262b81c9..3225dc990 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -1161,9 +1161,9 @@ handler(int signo, siginfo_t *info, void *context)
 {
     struct sigaction oldact;
 
-    if (sigaction(SIGSEGV, NULL, &oldact) != 0 ||
-        (oldact.sa_flags & SA_UNSUPPORTED) ||
-        !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
+    if (sigaction(SIGSEGV, NULL, &oldact) == \-1 ||
+            (oldact.sa_flags & SA_UNSUPPORTED) ||
+            !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
         _exit(EXIT_FAILURE);
     }
     _exit(EXIT_SUCCESS);
@@ -1172,11 +1172,11 @@ handler(int signo, siginfo_t *info, void *context)
 int
 main(void)
 {
-    struct sigaction act = {0};
+    struct sigaction act = { 0 };
 
     act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
     act.sa_sigaction = &handler;
-    if (sigaction(SIGSEGV, &act, NULL) != 0) {
+    if (sigaction(SIGSEGV, &act, NULL) == \-1) {
         perror("sigaction");
         exit(EXIT_FAILURE);
     }


diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 18404dde1..5262b81c9 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -266,13 +266,13 @@ This flag is meaningful only when establishing a signal handler.
 Used to dynamically probe for flag bit support.
 .IP
 If an attempt to register a handler succeeds with this flag set in
-.I act->sa_flags
+.I act\->sa_flags
 alongside other flags that are potentially unsupported by the kernel,
 and an immediately subsequent
 .BR sigaction ()
-call specifying the same signal number n and with non-NULL
+call specifying the same signal number and with a non-NULL
 .I oldact
-yields
+argument yields
 .B SA_UNSUPPORTED
 .I clear
 in
@@ -888,16 +888,16 @@ filter rule.
 The
 .BR sigaction ()
 call on Linux accepts unknown bits set in
-.I act->sa_flags
+.I act\->sa_flags
 without error.
 The behavior of the kernel starting with Linux 5.11 is that a second
 .BR sigaction ()
 will clear unknown bits from
-.IR oldact->sa_flags .
+.IR oldact\->sa_flags .
 However, historically, a second
 .BR sigaction ()
 call would typically leave those bits set in
-.IR oldact->sa_flags .
+.IR oldact\->sa_flags .
 .PP
 This means that support for new flags cannot be detected
 simply by testing for a flag in
@@ -919,7 +919,7 @@ in the signal handler itself.
 In kernels that do not support a specific flag,
 the kernel's behavior is as if the flag was not set,
 even if the flag was set in
-.IR act->sa_flags .
+.IR act\->sa_flags .
 .PP
 The flags
 .BR SA_NOCLDSTOP ,



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 03/23] sigaction.2: Apply minor tweaks to Peter's patch

[Alejandro Colomar (man-pages)]

Hi Michael,

On 8/9/21 2:34 AM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 8/8/21 10:41 AM, Alejandro Colomar wrote:
>> - Move example program to a new EXAMPLES section
> 
> Not a big thing, but perhaps it would have been nicer to have
> two patches, the first doing the pieces below, and the second
> doing the step above. That would enable me to more easily see
> what changes you made below. But, I am not sure; maybe that
> is more work than is justified...

If you haven't pushed yet, you can drop it and I'll break it into two :)

Not so much work:  I could write a commit with a simple move, and then 
checkout the file from the old commit, and commit the difference into a 
second commit.

But I see you already pushed.

> All looks good. I also had some additional fixes (2 patches). See below.

Those 2 look good to me too.

Cheers,

Alex



-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH 04/23] namespaces.7: ffix

[Alejandro Colomar]

From: Michael Weiß <michael.weiss@aisec.fraunhofer.de>

Signed-off-by: Michael Weiß <michael.weiss@aisec.fraunhofer.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/namespaces.7 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man7/namespaces.7 b/man7/namespaces.7
index 0ac32c77e..850dca844 100644
--- a/man7/namespaces.7
+++ b/man7/namespaces.7
@@ -71,7 +71,8 @@ Time	CLONE_NEWTIME	\fBtime_namespaces\fP(7)	T{
 Boot and monotonic
 clocks
 T}
-User	CLONE_NEWUSER	\fBuser_namespaces\fP(7)	T{User and group IDs
+User	CLONE_NEWUSER	\fBuser_namespaces\fP(7)	T{
+User and group IDs
 T}
 UTS	CLONE_NEWUTS	\fButs_namespaces\fP(7)	T{
 Hostname and NIS
-- 
2.32.0

Re: [PATCH 04/23] namespaces.7: ffix

[Michael Kerrisk (man-pages)]

Hello Michael and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Michael Weiß <michael.weiss@aisec.fraunhofer.de>
> 
> Signed-off-by: Michael Weiß <michael.weiss@aisec.fraunhofer.de>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks, patch applied.

Cheers,

Michael

> ---
>  man7/namespaces.7 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/namespaces.7 b/man7/namespaces.7
> index 0ac32c77e..850dca844 100644
> --- a/man7/namespaces.7
> +++ b/man7/namespaces.7
> @@ -71,7 +71,8 @@ Time	CLONE_NEWTIME	\fBtime_namespaces\fP(7)	T{
>  Boot and monotonic
>  clocks
>  T}
> -User	CLONE_NEWUSER	\fBuser_namespaces\fP(7)	T{User and group IDs
> +User	CLONE_NEWUSER	\fBuser_namespaces\fP(7)	T{
> +User and group IDs
>  T}
>  UTS	CLONE_NEWUTS	\fButs_namespaces\fP(7)	T{
>  Hostname and NIS
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 05/23] unix.7: tfix

[Alejandro Colomar]

From: Štěpán Němec <stepnem@gmail.com>

Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
 man7/unix.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man7/unix.7 b/man7/unix.7
index fc2834fe4..6d30b25cd 100644
--- a/man7/unix.7
+++ b/man7/unix.7
@@ -819,7 +819,7 @@ reference to it is closed.
 To pass file descriptors or credentials over a
 .BR SOCK_STREAM
 socket, you must
-to send or receive at least one byte of nonancillary data in the same
+send or receive at least one byte of nonancillary data in the same
 .BR sendmsg (2)
 or
 .BR recvmsg (2)
-- 
2.32.0

Re: [PATCH 05/23] unix.7: tfix

[Michael Kerrisk (man-pages)]

Hello Štěpán and Alex, 

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Štěpán Němec <stepnem@gmail.com>
> 
> Signed-off-by: Štěpán Němec <stepnem@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man7/unix.7 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man7/unix.7 b/man7/unix.7
> index fc2834fe4..6d30b25cd 100644
> --- a/man7/unix.7
> +++ b/man7/unix.7
> @@ -819,7 +819,7 @@ reference to it is closed.
>  To pass file descriptors or credentials over a
>  .BR SOCK_STREAM
>  socket, you must
> -to send or receive at least one byte of nonancillary data in the same
> +send or receive at least one byte of nonancillary data in the same
>  .BR sendmsg (2)
>  or
>  .BR recvmsg (2)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 06/23] futex.2: Document FUTEX_LOCK_PI2

[Alejandro Colomar]

From: Kurt Kanzenbach <kurt@linutronix.de>

FUTEX_LOCK_PI2 is a new futex operation which was recently introduced into the
Linux kernel. It works exactly like FUTEX_LOCK_PI. However, it has support for
selectable clocks for timeouts. By default CLOCK_MONOTONIC is used. If
FUTEX_CLOCK_REALTIME is specified then the timeout is measured against
CLOCK_REALTIME.

This new operation addresses an inconsistency in the futex interface:
FUTEX_LOCK_PI only works with timeouts based on CLOCK_REALTIME in contrast to
all the other PI operations.

Document the FUTEX_LOCK_PI2 command.

Signed-off-by: Kurt Kanzenbach <kurt@linutronix.de>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/futex.2 | 53 ++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/man2/futex.2 b/man2/futex.2
index ada96c517..2f340e0e0 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -241,10 +241,13 @@ and so on.
 This option bit can be employed only with the
 .BR FUTEX_WAIT_BITSET ,
 .BR FUTEX_WAIT_REQUEUE_PI ,
-and
 (since Linux 4.5)
 .\" commit 337f13046ff03717a9e99675284a817527440a49
-.BR FUTEX_WAIT
+.BR FUTEX_WAIT ,
+and
+(since Linux v5.14.0)
+.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
+.BR FUTEX_LOCK_PI2
 operations.
 .IP
 If this option is set, the kernel measures the
@@ -904,7 +907,9 @@ value to 0 if the previous value was the expected TID.
 If a futex is already acquired (i.e., has a nonzero value),
 waiters must employ the
 .B FUTEX_LOCK_PI
-operation to acquire the lock.
+or
+.B FUTEX_LOCK_PI2
+operations to acquire the lock.
 If other threads are waiting for the lock, then the
 .B FUTEX_WAITERS
 bit is set in the futex value;
@@ -964,6 +969,8 @@ Note that the PI futex operations must be used as paired operations
 and are subject to some additional requirements:
 .IP * 3
 .B FUTEX_LOCK_PI
+,
+.B FUTEX_LOCK_PI2
 and
 .B FUTEX_TRYLOCK_PI
 pair with
@@ -1122,6 +1129,27 @@ arguments are ignored.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"
 .TP
+.BR FUTEX_LOCK_PI2 " (since Linux 5.14.0)"
+.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
+This operation works similar like
+.BR FUTEX_LOCK_PI .
+The only difference is the
+timeout argument.
+.BR FUTEX_LOCK_PI2
+has support for selectable clocks.
+.IP
+If
+.I timeout
+is not NULL, the structure it points to specifies
+an absolute timeout.
+If
+.I timeout
+is NULL, the operation can block indefinitely.
+.IP
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
+.TP
 .BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
 .\" commit c87e2837be82df479a6bae9f155c43516d2feebc
 This operation tries to acquire the lock at
@@ -1168,6 +1196,8 @@ arguments are ignored.
 .\" commit c87e2837be82df479a6bae9f155c43516d2feebc
 This operation wakes the top priority waiter that is waiting in
 .B FUTEX_LOCK_PI
+or
+.B FUTEX_LOCK_PI2
 on the futex address provided by the
 .I uaddr
 argument.
@@ -1379,6 +1409,9 @@ Returns the number of waiters that were woken up.
 .B FUTEX_LOCK_PI
 Returns 0 if the futex was successfully locked.
 .TP
+.B FUTEX_LOCK_PI2
+Returns 0 if the futex was successfully locked.
+.TP
 .B FUTEX_TRYLOCK_PI
 Returns 0 if the futex was successfully locked.
 .TP
@@ -1435,6 +1468,7 @@ is not equal to the expected value
 .TP
 .BR EAGAIN
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The futex owner thread ID of
@@ -1448,6 +1482,7 @@ Try again.
 .TP
 .BR EDEADLK
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The futex word at
@@ -1536,11 +1571,14 @@ The kernel detected an inconsistency between the user-space state at
 .I uaddr
 and the kernel state\(emthat is, it detected a waiter which waits in
 .BR FUTEX_LOCK_PI
+or
+.BR FUTEX_LOCK_PI2
 on
 .IR uaddr .
 .TP
 .B EINVAL
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_UNLOCK_PI )
 The kernel detected an inconsistency between the user-space state at
@@ -1590,6 +1628,8 @@ that is, the kernel detected a waiter which waits on
 .I uaddr
 via
 .BR FUTEX_LOCK_PI
+or
+.BR FUTEX_LOCK_PI2
 (instead of
 .BR FUTEX_WAIT_REQUEUE_PI ).
 .TP
@@ -1618,6 +1658,7 @@ The system-wide limit on the total number of open files has been reached.
 .TP
 .BR ENOMEM
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The kernel could not allocate memory to hold state information.
@@ -1634,11 +1675,13 @@ option was specified in
 but the accompanying operation was neither
 .BR FUTEX_WAIT ,
 .BR FUTEX_WAIT_BITSET ,
+.BR FUTEX_WAIT_REQUEUE_PI ,
 nor
-.BR FUTEX_WAIT_REQUEUE_PI .
+.BR FUTEX_LOCK_PI2 .
 .TP
 .BR ENOSYS
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_UNLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI ,
@@ -1649,6 +1692,7 @@ are not supported on some CPU variants.
 .TP
 .BR EPERM
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The caller is not allowed to attach itself to the futex at
@@ -1665,6 +1709,7 @@ The caller does not own the lock represented by the futex word.
 .TP
 .BR ESRCH
 .RB ( FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
 .BR FUTEX_CMP_REQUEUE_PI )
 The thread ID in the futex word at
-- 
2.32.0

Re: [PATCH 06/23] futex.2: Document FUTEX_LOCK_PI2

[Michael Kerrisk (man-pages)]

hello Kurt and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Kurt Kanzenbach <kurt@linutronix.de>
> 
> FUTEX_LOCK_PI2 is a new futex operation which was recently introduced into the
> Linux kernel. It works exactly like FUTEX_LOCK_PI. However, it has support for
> selectable clocks for timeouts. By default CLOCK_MONOTONIC is used. If
> FUTEX_CLOCK_REALTIME is specified then the timeout is measured against
> CLOCK_REALTIME.
> 
> This new operation addresses an inconsistency in the futex interface:
> FUTEX_LOCK_PI only works with timeouts based on CLOCK_REALTIME in contrast to
> all the other PI operations.
> 
> Document the FUTEX_LOCK_PI2 command.
> 
> Signed-off-by: Kurt Kanzenbach <kurt@linutronix.de>
> Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

But I have a note below.

> ---
>  man2/futex.2 | 53 ++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 49 insertions(+), 4 deletions(-)
> 
> diff --git a/man2/futex.2 b/man2/futex.2
> index ada96c517..2f340e0e0 100644
> --- a/man2/futex.2
> +++ b/man2/futex.2
> @@ -241,10 +241,13 @@ and so on.
>  This option bit can be employed only with the
>  .BR FUTEX_WAIT_BITSET ,
>  .BR FUTEX_WAIT_REQUEUE_PI ,
> -and
>  (since Linux 4.5)
>  .\" commit 337f13046ff03717a9e99675284a817527440a49
> -.BR FUTEX_WAIT
> +.BR FUTEX_WAIT ,
> +and
> +(since Linux v5.14.0)
> +.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
> +.BR FUTEX_LOCK_PI2
>  operations.
>  .IP
>  If this option is set, the kernel measures the
> @@ -904,7 +907,9 @@ value to 0 if the previous value was the expected TID.
>  If a futex is already acquired (i.e., has a nonzero value),
>  waiters must employ the
>  .B FUTEX_LOCK_PI
> -operation to acquire the lock.
> +or
> +.B FUTEX_LOCK_PI2
> +operations to acquire the lock.
>  If other threads are waiting for the lock, then the
>  .B FUTEX_WAITERS
>  bit is set in the futex value;
> @@ -964,6 +969,8 @@ Note that the PI futex operations must be used as paired operations
>  and are subject to some additional requirements:
>  .IP * 3
>  .B FUTEX_LOCK_PI
> +,
> +.B FUTEX_LOCK_PI2
>  and
>  .B FUTEX_TRYLOCK_PI
>  pair with
> @@ -1122,6 +1129,27 @@ arguments are ignored.
>  .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
>  .\"
>  .TP
> +.BR FUTEX_LOCK_PI2 " (since Linux 5.14.0)"
> +.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
> +This operation works similar like
> +.BR FUTEX_LOCK_PI .
> +The only difference is the
> +timeout argument.
> +.BR FUTEX_LOCK_PI2
> +has support for selectable clocks.

I think the page could help the reader by reminding them how the
clock is selected, as is done in the description of FUTEX_WAIT.

> +.IP
> +If
> +.I timeout
> +is not NULL, the structure it points to specifies
> +an absolute timeout.
> +If
> +.I timeout
> +is NULL, the operation can block indefinitely.

The above is the same as FUTEX_LOCK_PI, right? So, it
probably doesn't need repeating.

I've reworked this description to be:

       FUTEX_LOCK_PI2 (since Linux 5.14)
              This operation is the same as FUTEX_LOCK_PI, except that
              the clock against which timeout is measured is selectable.
              By default, the (absolute) timeout specified in timeout is
              measured againt the CLOCK_MONOTONIC clock, but if the
              FUTEX_CLOCK_REALTIME flag is specified in futex_op, then
              the timeout is measured against the CLOCK_REALTIME clock.

Is it okay?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 06/23] futex.2: Document FUTEX_LOCK_PI2

[Kurt Kanzenbach]

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

Hi Michael,

On Mon Aug 09 2021, Michael Kerrisk (man-pages) wrote:
>> +.IP
>> +If
>> +.I timeout
>> +is not NULL, the structure it points to specifies
>> +an absolute timeout.
>> +If
>> +.I timeout
>> +is NULL, the operation can block indefinitely.
>
> The above is the same as FUTEX_LOCK_PI, right? So, it
> probably doesn't need repeating.
>
> I've reworked this description to be:
>
>        FUTEX_LOCK_PI2 (since Linux 5.14)
>               This operation is the same as FUTEX_LOCK_PI, except that
>               the clock against which timeout is measured is selectable.
>               By default, the (absolute) timeout specified in timeout is
>               measured againt the CLOCK_MONOTONIC clock, but if the
>               FUTEX_CLOCK_REALTIME flag is specified in futex_op, then
>               the timeout is measured against the CLOCK_REALTIME clock.
>
> Is it okay?

Sounds good.

Thanks,
Kurt

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

Re: [PATCH 06/23] futex.2: Document FUTEX_LOCK_PI2

[Michael Kerrisk (man-pages)]

On Mon, 9 Aug 2021 at 10:14, Kurt Kanzenbach <kurt@linutronix.de> wrote:
>
> Hi Michael,
>
> On Mon Aug 09 2021, Michael Kerrisk (man-pages) wrote:
> >> +.IP
> >> +If
> >> +.I timeout
> >> +is not NULL, the structure it points to specifies
> >> +an absolute timeout.
> >> +If
> >> +.I timeout
> >> +is NULL, the operation can block indefinitely.
> >
> > The above is the same as FUTEX_LOCK_PI, right? So, it
> > probably doesn't need repeating.
> >
> > I've reworked this description to be:
> >
> >        FUTEX_LOCK_PI2 (since Linux 5.14)
> >               This operation is the same as FUTEX_LOCK_PI, except that
> >               the clock against which timeout is measured is selectable.
> >               By default, the (absolute) timeout specified in timeout is
> >               measured againt the CLOCK_MONOTONIC clock, but if the
> >               FUTEX_CLOCK_REALTIME flag is specified in futex_op, then
> >               the timeout is measured against the CLOCK_REALTIME clock.
> >
> > Is it okay?
>
> Sounds good.

Okay. Thanks.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 07/23] futex.2: Minor tweaks to Kurt's patch

[Alejandro Colomar]

Cc: Kurt Kanzenbach <kurt@linutronix.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/futex.2 | 78 ++++++++++++++++++++++++++--------------------------
 1 file changed, 39 insertions(+), 39 deletions(-)

diff --git a/man2/futex.2 b/man2/futex.2
index 2f340e0e0..facdf60c9 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -222,9 +222,9 @@ This allows the kernel to make some additional performance optimizations.
 .\" taking reference counts on file backing store, and so on.
 .IP
 As a convenience,
-.IR <linux/futex.h>
+.I <linux/futex.h>
 defines a set of constants with the suffix
-.BR _PRIVATE
+.B _PRIVATE
 that are equivalents of all of the operations listed below,
 .\" except the obsolete FUTEX_FD, for which the "private" flag was
 .\" meaningless
@@ -245,21 +245,21 @@ This option bit can be employed only with the
 .\" commit 337f13046ff03717a9e99675284a817527440a49
 .BR FUTEX_WAIT ,
 and
-(since Linux v5.14.0)
+(since Linux 5.14)
 .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
-.BR FUTEX_LOCK_PI2
+.B FUTEX_LOCK_PI2
 operations.
 .IP
 If this option is set, the kernel measures the
 .I timeout
 against the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
 clock.
 .IP
 If this option is not set, the kernel measures the
 .I timeout
 against the
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
 clock.
 .PP
 The operation specified in
@@ -968,9 +968,8 @@ PI futexes are operated on by specifying one of the values listed below in
 Note that the PI futex operations must be used as paired operations
 and are subject to some additional requirements:
 .IP * 3
-.B FUTEX_LOCK_PI
-,
-.B FUTEX_LOCK_PI2
+.BR FUTEX_LOCK_PI ,
+.BR FUTEX_LOCK_PI2 ,
 and
 .B FUTEX_TRYLOCK_PI
 pair with
@@ -1123,19 +1122,20 @@ The
 .IR uaddr2 ,
 .IR val ,
 and
-.IR val3
+.I val3
 arguments are ignored.
 .\"
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"
 .TP
-.BR FUTEX_LOCK_PI2 " (since Linux 5.14.0)"
+.BR FUTEX_LOCK_PI2 " (since Linux 5.14)"
 .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
-This operation works similar like
+This operation works similar to
 .BR FUTEX_LOCK_PI .
 The only difference is the
-timeout argument.
-.BR FUTEX_LOCK_PI2
+.I timeout
+argument.
+.B FUTEX_LOCK_PI2
 has support for selectable clocks.
 .IP
 If
@@ -1466,7 +1466,7 @@ The value pointed to by
 is not equal to the expected value
 .IR val3 .
 .TP
-.BR EAGAIN
+.B EAGAIN
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
@@ -1480,7 +1480,7 @@ is about to exit,
 but has not yet handled the internal state cleanup.
 Try again.
 .TP
-.BR EDEADLK
+.B EDEADLK
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
@@ -1522,18 +1522,18 @@ a spurious wakeup; since Linux 2.6.22, this no longer happens.
 .TP
 .B EINVAL
 The operation in
-.IR futex_op
+.I futex_op
 is one of those that employs a timeout, but the supplied
 .I timeout
 argument was invalid
 .RI ( tv_sec
 was less than zero, or
-.IR tv_nsec
+.I tv_nsec
 was not less than 1,000,000,000).
 .TP
 .B EINVAL
 The operation specified in
-.IR futex_op
+.I futex_op
 employs one or both of the pointers
 .I uaddr
 and
@@ -1545,17 +1545,17 @@ the address is not four-byte-aligned.
 .RB ( FUTEX_WAIT_BITSET ,
 .BR FUTEX_WAKE_BITSET )
 The bit mask supplied in
-.IR val3
+.I val3
 is zero.
 .TP
 .B EINVAL
 .RB ( FUTEX_CMP_REQUEUE_PI )
 .I uaddr
 equals
-.IR uaddr2
+.I uaddr2
 (i.e., an attempt was made to requeue to the same futex).
 .TP
-.BR EINVAL
+.B EINVAL
 .RB ( FUTEX_FD )
 The signal number supplied in
 .I val
@@ -1570,9 +1570,9 @@ is invalid.
 The kernel detected an inconsistency between the user-space state at
 .I uaddr
 and the kernel state\(emthat is, it detected a waiter which waits in
-.BR FUTEX_LOCK_PI
+.B FUTEX_LOCK_PI
 or
-.BR FUTEX_LOCK_PI2
+.B FUTEX_LOCK_PI2
 on
 .IR uaddr .
 .TP
@@ -1588,7 +1588,7 @@ This indicates either state corruption
 or that the kernel found a waiter on
 .I uaddr
 which is waiting via
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
 or
 .BR FUTEX_WAIT_BITSET .
 .TP
@@ -1601,9 +1601,9 @@ and the kernel state;
 .\"	The kernel sees: I have non PI state for a futex you tried to
 .\"     tell me was PI
 that is, the kernel detected a waiter which waits via
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
 or
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
 on
 .IR uaddr2 .
 .TP
@@ -1613,9 +1613,9 @@ The kernel detected an inconsistency between the user-space state at
 .I uaddr
 and the kernel state;
 that is, the kernel detected a waiter which waits via
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
 or
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
 on
 .IR uaddr .
 .TP
@@ -1627,9 +1627,9 @@ and the kernel state;
 that is, the kernel detected a waiter which waits on
 .I uaddr
 via
-.BR FUTEX_LOCK_PI
+.B FUTEX_LOCK_PI
 or
-.BR FUTEX_LOCK_PI2
+.B FUTEX_LOCK_PI2
 (instead of
 .BR FUTEX_WAIT_REQUEUE_PI ).
 .TP
@@ -1656,7 +1656,7 @@ Invalid argument.
 .RB ( FUTEX_FD )
 The system-wide limit on the total number of open files has been reached.
 .TP
-.BR ENOMEM
+.B ENOMEM
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
@@ -1669,7 +1669,7 @@ Invalid operation specified in
 .TP
 .B ENOSYS
 The
-.BR FUTEX_CLOCK_REALTIME
+.B FUTEX_CLOCK_REALTIME
 option was specified in
 .IR futex_op ,
 but the accompanying operation was neither
@@ -1679,7 +1679,7 @@ but the accompanying operation was neither
 nor
 .BR FUTEX_LOCK_PI2 .
 .TP
-.BR ENOSYS
+.B ENOSYS
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
@@ -1690,7 +1690,7 @@ A run-time check determined that the operation is not available.
 The PI-futex operations are not implemented on all architectures and
 are not supported on some CPU variants.
 .TP
-.BR EPERM
+.B EPERM
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
@@ -1703,11 +1703,11 @@ the futex at
 .IR uaddr2 ).
 (This may be caused by a state corruption in user space.)
 .TP
-.BR EPERM
+.B EPERM
 .RB ( FUTEX_UNLOCK_PI )
 The caller does not own the lock represented by the futex word.
 .TP
-.BR ESRCH
+.B ESRCH
 .RB ( FUTEX_LOCK_PI ,
 .BR FUTEX_LOCK_PI2 ,
 .BR FUTEX_TRYLOCK_PI ,
@@ -1716,7 +1716,7 @@ The thread ID in the futex word at
 .I uaddr
 does not exist.
 .TP
-.BR ESRCH
+.B ESRCH
 .RB ( FUTEX_CMP_REQUEUE_PI )
 The thread ID in the futex word at
 .I uaddr2
@@ -1724,7 +1724,7 @@ does not exist.
 .TP
 .B ETIMEDOUT
 The operation in
-.IR futex_op
+.I futex_op
 employed the timeout specified in
 .IR timeout ,
 and the timeout expired before the operation completed.
-- 
2.32.0

Re: [PATCH 07/23] futex.2: Minor tweaks to Kurt's patch

[Michael Kerrisk (man-pages)]

Hi Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> Cc: Kurt Kanzenbach <kurt@linutronix.de>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

I've applied this patch, but:

a) It doesn't do what it says on the tin; that is, it fixes more than
   just Kurt's patch.
b) The .BR ==> .B and .IR ==> .I changes are not wrong, but they
   are also not strictly necessary, since

       .BR x

   is equivalent to

       .B x

   There are many existing pages that inadvertently use .[BI]R
   unnecessarily, and while one could fix them, it creates a lot
   of churn for no really useful purpose. That said, I'm fine
   with such fixes on new patches such as Kurt's.

Thanks,

Michael

> ---
>  man2/futex.2 | 78 ++++++++++++++++++++++++++--------------------------
>  1 file changed, 39 insertions(+), 39 deletions(-)
> 
> diff --git a/man2/futex.2 b/man2/futex.2
> index 2f340e0e0..facdf60c9 100644
> --- a/man2/futex.2
> +++ b/man2/futex.2
> @@ -222,9 +222,9 @@ This allows the kernel to make some additional performance optimizations.
>  .\" taking reference counts on file backing store, and so on.
>  .IP
>  As a convenience,
> -.IR <linux/futex.h>
> +.I <linux/futex.h>
>  defines a set of constants with the suffix
> -.BR _PRIVATE
> +.B _PRIVATE
>  that are equivalents of all of the operations listed below,
>  .\" except the obsolete FUTEX_FD, for which the "private" flag was
>  .\" meaningless
> @@ -245,21 +245,21 @@ This option bit can be employed only with the
>  .\" commit 337f13046ff03717a9e99675284a817527440a49
>  .BR FUTEX_WAIT ,
>  and
> -(since Linux v5.14.0)
> +(since Linux 5.14)
>  .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
> -.BR FUTEX_LOCK_PI2
> +.B FUTEX_LOCK_PI2
>  operations.
>  .IP
>  If this option is set, the kernel measures the
>  .I timeout
>  against the
> -.BR CLOCK_REALTIME
> +.B CLOCK_REALTIME
>  clock.
>  .IP
>  If this option is not set, the kernel measures the
>  .I timeout
>  against the
> -.BR CLOCK_MONOTONIC
> +.B CLOCK_MONOTONIC
>  clock.
>  .PP
>  The operation specified in
> @@ -968,9 +968,8 @@ PI futexes are operated on by specifying one of the values listed below in
>  Note that the PI futex operations must be used as paired operations
>  and are subject to some additional requirements:
>  .IP * 3
> -.B FUTEX_LOCK_PI
> -,
> -.B FUTEX_LOCK_PI2
> +.BR FUTEX_LOCK_PI ,
> +.BR FUTEX_LOCK_PI2 ,
>  and
>  .B FUTEX_TRYLOCK_PI
>  pair with
> @@ -1123,19 +1122,20 @@ The
>  .IR uaddr2 ,
>  .IR val ,
>  and
> -.IR val3
> +.I val3
>  arguments are ignored.
>  .\"
>  .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
>  .\"
>  .TP
> -.BR FUTEX_LOCK_PI2 " (since Linux 5.14.0)"
> +.BR FUTEX_LOCK_PI2 " (since Linux 5.14)"
>  .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
> -This operation works similar like
> +This operation works similar to
>  .BR FUTEX_LOCK_PI .
>  The only difference is the
> -timeout argument.
> -.BR FUTEX_LOCK_PI2
> +.I timeout
> +argument.
> +.B FUTEX_LOCK_PI2
>  has support for selectable clocks.
>  .IP
>  If
> @@ -1466,7 +1466,7 @@ The value pointed to by
>  is not equal to the expected value
>  .IR val3 .
>  .TP
> -.BR EAGAIN
> +.B EAGAIN
>  .RB ( FUTEX_LOCK_PI ,
>  .BR FUTEX_LOCK_PI2 ,
>  .BR FUTEX_TRYLOCK_PI ,
> @@ -1480,7 +1480,7 @@ is about to exit,
>  but has not yet handled the internal state cleanup.
>  Try again.
>  .TP
> -.BR EDEADLK
> +.B EDEADLK
>  .RB ( FUTEX_LOCK_PI ,
>  .BR FUTEX_LOCK_PI2 ,
>  .BR FUTEX_TRYLOCK_PI ,
> @@ -1522,18 +1522,18 @@ a spurious wakeup; since Linux 2.6.22, this no longer happens.
>  .TP
>  .B EINVAL
>  The operation in
> -.IR futex_op
> +.I futex_op
>  is one of those that employs a timeout, but the supplied
>  .I timeout
>  argument was invalid
>  .RI ( tv_sec
>  was less than zero, or
> -.IR tv_nsec
> +.I tv_nsec
>  was not less than 1,000,000,000).
>  .TP
>  .B EINVAL
>  The operation specified in
> -.IR futex_op
> +.I futex_op
>  employs one or both of the pointers
>  .I uaddr
>  and
> @@ -1545,17 +1545,17 @@ the address is not four-byte-aligned.
>  .RB ( FUTEX_WAIT_BITSET ,
>  .BR FUTEX_WAKE_BITSET )
>  The bit mask supplied in
> -.IR val3
> +.I val3
>  is zero.
>  .TP
>  .B EINVAL
>  .RB ( FUTEX_CMP_REQUEUE_PI )
>  .I uaddr
>  equals
> -.IR uaddr2
> +.I uaddr2
>  (i.e., an attempt was made to requeue to the same futex).
>  .TP
> -.BR EINVAL
> +.B EINVAL
>  .RB ( FUTEX_FD )
>  The signal number supplied in
>  .I val
> @@ -1570,9 +1570,9 @@ is invalid.
>  The kernel detected an inconsistency between the user-space state at
>  .I uaddr
>  and the kernel state\(emthat is, it detected a waiter which waits in
> -.BR FUTEX_LOCK_PI
> +.B FUTEX_LOCK_PI
>  or
> -.BR FUTEX_LOCK_PI2
> +.B FUTEX_LOCK_PI2
>  on
>  .IR uaddr .
>  .TP
> @@ -1588,7 +1588,7 @@ This indicates either state corruption
>  or that the kernel found a waiter on
>  .I uaddr
>  which is waiting via
> -.BR FUTEX_WAIT
> +.B FUTEX_WAIT
>  or
>  .BR FUTEX_WAIT_BITSET .
>  .TP
> @@ -1601,9 +1601,9 @@ and the kernel state;
>  .\"	The kernel sees: I have non PI state for a futex you tried to
>  .\"     tell me was PI
>  that is, the kernel detected a waiter which waits via
> -.BR FUTEX_WAIT
> +.B FUTEX_WAIT
>  or
> -.BR FUTEX_WAIT_BITSET
> +.B FUTEX_WAIT_BITSET
>  on
>  .IR uaddr2 .
>  .TP
> @@ -1613,9 +1613,9 @@ The kernel detected an inconsistency between the user-space state at
>  .I uaddr
>  and the kernel state;
>  that is, the kernel detected a waiter which waits via
> -.BR FUTEX_WAIT
> +.B FUTEX_WAIT
>  or
> -.BR FUTEX_WAIT_BITSET
> +.B FUTEX_WAIT_BITSET
>  on
>  .IR uaddr .
>  .TP
> @@ -1627,9 +1627,9 @@ and the kernel state;
>  that is, the kernel detected a waiter which waits on
>  .I uaddr
>  via
> -.BR FUTEX_LOCK_PI
> +.B FUTEX_LOCK_PI
>  or
> -.BR FUTEX_LOCK_PI2
> +.B FUTEX_LOCK_PI2
>  (instead of
>  .BR FUTEX_WAIT_REQUEUE_PI ).
>  .TP
> @@ -1656,7 +1656,7 @@ Invalid argument.
>  .RB ( FUTEX_FD )
>  The system-wide limit on the total number of open files has been reached.
>  .TP
> -.BR ENOMEM
> +.B ENOMEM
>  .RB ( FUTEX_LOCK_PI ,
>  .BR FUTEX_LOCK_PI2 ,
>  .BR FUTEX_TRYLOCK_PI ,
> @@ -1669,7 +1669,7 @@ Invalid operation specified in
>  .TP
>  .B ENOSYS
>  The
> -.BR FUTEX_CLOCK_REALTIME
> +.B FUTEX_CLOCK_REALTIME
>  option was specified in
>  .IR futex_op ,
>  but the accompanying operation was neither
> @@ -1679,7 +1679,7 @@ but the accompanying operation was neither
>  nor
>  .BR FUTEX_LOCK_PI2 .
>  .TP
> -.BR ENOSYS
> +.B ENOSYS
>  .RB ( FUTEX_LOCK_PI ,
>  .BR FUTEX_LOCK_PI2 ,
>  .BR FUTEX_TRYLOCK_PI ,
> @@ -1690,7 +1690,7 @@ A run-time check determined that the operation is not available.
>  The PI-futex operations are not implemented on all architectures and
>  are not supported on some CPU variants.
>  .TP
> -.BR EPERM
> +.B EPERM
>  .RB ( FUTEX_LOCK_PI ,
>  .BR FUTEX_LOCK_PI2 ,
>  .BR FUTEX_TRYLOCK_PI ,
> @@ -1703,11 +1703,11 @@ the futex at
>  .IR uaddr2 ).
>  (This may be caused by a state corruption in user space.)
>  .TP
> -.BR EPERM
> +.B EPERM
>  .RB ( FUTEX_UNLOCK_PI )
>  The caller does not own the lock represented by the futex word.
>  .TP
> -.BR ESRCH
> +.B ESRCH
>  .RB ( FUTEX_LOCK_PI ,
>  .BR FUTEX_LOCK_PI2 ,
>  .BR FUTEX_TRYLOCK_PI ,
> @@ -1716,7 +1716,7 @@ The thread ID in the futex word at
>  .I uaddr
>  does not exist.
>  .TP
> -.BR ESRCH
> +.B ESRCH
>  .RB ( FUTEX_CMP_REQUEUE_PI )
>  The thread ID in the futex word at
>  .I uaddr2
> @@ -1724,7 +1724,7 @@ does not exist.
>  .TP
>  .B ETIMEDOUT
>  The operation in
> -.IR futex_op
> +.I futex_op
>  employed the timeout specified in
>  .IR timeout ,
>  and the timeout expired before the operation completed.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 08/23] man2: new page describing memfd_secret() system call

[Alejandro Colomar]

From: Mike Rapoport <rppt@linux.ibm.com>

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/memfd_secret.2 | 146 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 man2/memfd_secret.2

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
new file mode 100644
index 000000000..466aa4236
--- /dev/null
+++ b/man2/memfd_secret.2
@@ -0,0 +1,146 @@
+.\" Copyright (c) 2021, IBM Corporation.
+.\" Written by Mike Rapoport <rppt@linux.ibm.com>
+.\"
+.\" Based on memfd_create(2) man page
+.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
+.\"
+.\" %%%LICENSE_START(GPLv2+)
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
+.SH NAME
+memfd_secret \- create an anonymous file to access secret memory regions
+.SH SYNOPSIS
+.nf
+.PP
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_memfd_secret, unsigned int " flags );
+.fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR memfd_secret (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+.BR memfd_secret ()
+creates an anonymous file and returns a file descriptor that refers to it.
+The file provides a way to create and access memory regions
+with stronger protection than usual RAM-based files and
+anonymous memory mappings.
+Once all references to the file are dropped, it is automatically released.
+The initial size of the file is set to 0.
+Following the call, the file size should be set using
+.BR ftruncate (2).
+.PP
+The memory areas backing the file created with
+.BR memfd_create(2)
+are visible only to the contexts that have access to the file descriptor.
+These areas are removed from the kernel page tables
+and only the page tables of the processes holding the file descriptor
+map the corresponding physical memory.
+.PP
+The following values may be bitwise ORed in
+.I flags
+to control the behavior of
+.BR memfd_secret (2):
+.TP
+.B FD_CLOEXEC
+Set the close-on-exec flag on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.PP
+As its return value,
+.BR memfd_secret ()
+returns a new file descriptor that can be used to refer to an anonymous file.
+This file descriptor is opened for both reading and writing
+.RB ( O_RDWR )
+and
+.B O_LARGEFILE
+is set for the file descriptor.
+.PP
+With respect to
+.BR fork (2)
+and
+.BR execve (2),
+the usual semantics apply for the file descriptor created by
+.BR memfd_secret ().
+A copy of the file descriptor is inherited by the child produced by
+.BR fork (2)
+and refers to the same file.
+The file descriptor is preserved across
+.BR execve (2),
+unless the close-on-exec flag has been set.
+.PP
+The memory regions backed with
+.BR memfd_secret ()
+are locked in the same way as
+.BR mlock (2),
+however the implementation will not try to
+populate the whole range during the
+.BR mmap (2)
+call.
+The amount of memory allowed for memory mappings
+of the file descriptor obeys the same rules as
+.BR mlock (2)
+and cannot exceed
+.BR RLIMIT_MEMLOCK .
+.SH RETURN VALUE
+On success,
+.BR memfd_secret ()
+returns a new file descriptor.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I flags
+included unknown bits.
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B EMFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOMEM
+There was insufficient memory to create a new anonymous file.
+.TP
+.B ENOSYS
+.BR memfd_secret ()
+is not implemented on this architecture.
+.SH VERSIONS
+The
+.BR memfd_secret (2)
+system call first appeared in Linux 5.14.
+.SH CONFORMING TO
+The
+.BR memfd_secret (2)
+system call is Linux-specific.
+.SH SEE ALSO
+.BR fcntl (2),
+.BR ftruncate (2),
+.BR mlock (2),
+.BR mmap (2),
+.BR setrlimit (2)
-- 
2.32.0

Re: [PATCH 08/23] man2: new page describing memfd_secret() system call

[Michael Kerrisk (man-pages)]

Hi Mike and Alex,

I think some more work is needed for this page. Mike, would
you be willing to do some work on the points below please?

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Mike Rapoport <rppt@linux.ibm.com>
> 
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/memfd_secret.2 | 146 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 146 insertions(+)
>  create mode 100644 man2/memfd_secret.2
> 
> diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
> new file mode 100644
> index 000000000..466aa4236
> --- /dev/null
> +++ b/man2/memfd_secret.2
> @@ -0,0 +1,146 @@
> +.\" Copyright (c) 2021, IBM Corporation.
> +.\" Written by Mike Rapoport <rppt@linux.ibm.com>
> +.\"
> +.\" Based on memfd_create(2) man page
> +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
> +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(GPLv2+)
> +.\"
> +.\" This program is free software; you can redistribute it and/or modify
> +.\" it under the terms of the GNU General Public License as published by
> +.\" the Free Software Foundation; either version 2 of the License, or
> +.\" (at your option) any later version.
> +.\"
> +.\" This program is distributed in the hope that it will be useful,
> +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +.\" GNU General Public License for more details.
> +.\"
> +.\" You should have received a copy of the GNU General Public
> +.\" License along with this manual; if not, see
> +.\" <http://www.gnu.org/licenses/>.
> +.\" %%%LICENSE_END
> +.\"
> +.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
> +.SH NAME
> +memfd_secret \- create an anonymous file to access secret memory regions
> +.SH SYNOPSIS
> +.nf
> +.PP
> +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> +.B #include <unistd.h>
> +.PP
> +.BI "int syscall(SYS_memfd_secret, unsigned int " flags );
> +.fi
> +.PP
> +.IR Note :
> +glibc provides no wrapper for
> +.BR memfd_secret (),
> +necessitating the use of
> +.BR syscall (2).
> +.SH DESCRIPTION
> +.BR memfd_secret ()
> +creates an anonymous file and returns a file descriptor that refers to it.

s/file/RAM-based file/

> +The file provides a way to create and access memory regions
> +with stronger protection than usual RAM-based files and
> +anonymous memory mappings.
> +Once all references to the file are dropped, it is automatically released.

"dropped" is not clear. Should it be something like:

    Once all open references to the file are closed,

> +The initial size of the file is set to 0.
> +Following the call, the file size should be set using
> +.BR ftruncate (2).
> +.PP
> +The memory areas backing the file created with
> +.BR memfd_create(2)
> +are visible only to the contexts that have access to the file descriptor.

"contexts" is not clear here. Can you reword to explain what you mean?
(processes, threads, something else?)

> +These areas are removed from the kernel page tables

s/These areas are/The memory region is/

> +and only the page tables of the processes holding the file descriptor
> +map the corresponding physical memory.

Perhaps a sentence here such as:

"(Thus, the pages in the region can't be accessed by the kernel itself,
so that, for example, pointers to the region can't be passed to 
system calls.)"

> +.PP
> +The following values may be bitwise ORed in
> +.I flags
> +to control the behavior of
> +.BR memfd_secret (2):
> +.TP
> +.B FD_CLOEXEC
> +Set the close-on-exec flag on the new file descriptor.

s/.$/, which causes the region to be removed from the process on execve(2)./

> +See the description of the
> +.B O_CLOEXEC
> +flag in
> +.BR open (2)
> +for reasons why this may be useful.

Maybe the previous sentence is not necessary?

> +.PP
> +As its return value,
> +.BR memfd_secret ()
> +returns a new file descriptor that can be used to refer to an anonymous file.

s/that can be used to refer/that refers/

> +This file descriptor is opened for both reading and writing
> +.RB ( O_RDWR )
> +and
> +.B O_LARGEFILE
> +is set for the file descriptor.
> +.PP
> +With respect to
> +.BR fork (2)
> +and
> +.BR execve (2),
> +the usual semantics apply for the file descriptor created by
> +.BR memfd_secret ().
> +A copy of the file descriptor is inherited by the child produced by
> +.BR fork (2)
> +and refers to the same file.
> +The file descriptor is preserved across
> +.BR execve (2),
> +unless the close-on-exec flag has been set.
> +.PP
> +The memory regions backed with
> +.BR memfd_secret ()
> +are locked in the same way as
> +.BR mlock (2),

I find the wording here just a little unclear

How about:

    The memory region is locked into memory in the same way as
    with mlock(2), so that it will never be written into swap

> +however the implementation will not try to> +populate the whole range during the
> +.BR mmap (2)
> +call.

s/call./call that attaches the region into the process's address space;
        instead, the pages are only actually allocated as they are
        faulted in./

> +The amount of memory allowed for memory mappings
> +of the file descriptor obeys the same rules as
> +.BR mlock (2)
> +and cannot exceed
> +.BR RLIMIT_MEMLOCK .
> +.SH RETURN VALUE
> +On success,
> +.BR memfd_secret ()
> +returns a new file descriptor.
> +On error, \-1 is returned and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +.I flags
> +included unknown bits.
> +.TP
> +.B EMFILE
> +The per-process limit on the number of open file descriptors has been reached.
> +.TP
> +.B EMFILE
> +The system-wide limit on the total number of open files has been reached.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to create a new anonymous file.
> +.TP
> +.B ENOSYS
> +.BR memfd_secret ()
> +is not implemented on this architecture.
> +.SH VERSIONS
> +The
> +.BR memfd_secret (2)
> +system call first appeared in Linux 5.14.
> +.SH CONFORMING TO
> +The
> +.BR memfd_secret (2)
> +system call is Linux-specific.
> +.SH SEE ALSO
> +.BR fcntl (2),
> +.BR ftruncate (2),
> +.BR mlock (2),
> +.BR mmap (2),
> +.BR setrlimit (2)

I feel like this page could benefit from a NOTES section
that explains the rationale for the system call. This could
note that the fact that the region is not accessible from the
kernel removes a whole class of security attacks.

Also, the NOTES section could mention the  "secretmem_enable"
boot option, what its purpose is, what values it can have,
and what is default behavior if this option is not specified.

Also, is ti still the case that if this system call is used,
then users can no longer hibernate their systems? If so,
this really should be mentioned in NOTES!

Also, in NOTES perhaps it is worth mentioning that the
pages in the region can enter the cache (right?).

Perhaps Jon's articles at https://lwn.net/Articles/865256/
https://lwn.net/Articits/835342/ and https://lwn.net/Articles/812325/,
as well as your own commit message
(https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=1507f51255c9)
may inspire some other ideas on details that should be included
in NOTES.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 08/23] man2: new page describing memfd_secret() system call

[Mike Rapoport]

Hi Michael,

On Mon, Aug 09, 2021 at 04:00:46AM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Mike and Alex,
> 
> I think some more work is needed for this page. Mike, would
> you be willing to do some work on the points below please?

I'm really stretched at the moment, so it'll take a while.

What do you say about starting without the elaborate NOTES section and only
updating the page according to your comments below?

I will add the NOTES section a bit later then.
 
> On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> > From: Mike Rapoport <rppt@linux.ibm.com>
> > 
> > Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> > Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> > ---
> >  man2/memfd_secret.2 | 146 ++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 146 insertions(+)
> >  create mode 100644 man2/memfd_secret.2
> > 
> > diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
> > new file mode 100644
> > index 000000000..466aa4236
> > --- /dev/null
> > +++ b/man2/memfd_secret.2
> > @@ -0,0 +1,146 @@
> > +.\" Copyright (c) 2021, IBM Corporation.
> > +.\" Written by Mike Rapoport <rppt@linux.ibm.com>
> > +.\"
> > +.\" Based on memfd_create(2) man page
> > +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
> > +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+)
> > +.\"
> > +.\" This program is free software; you can redistribute it and/or modify
> > +.\" it under the terms of the GNU General Public License as published by
> > +.\" the Free Software Foundation; either version 2 of the License, or
> > +.\" (at your option) any later version.
> > +.\"
> > +.\" This program is distributed in the hope that it will be useful,
> > +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> > +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> > +.\" GNU General Public License for more details.
> > +.\"
> > +.\" You should have received a copy of the GNU General Public
> > +.\" License along with this manual; if not, see
> > +.\" <http://www.gnu.org/licenses/>.
> > +.\" %%%LICENSE_END
> > +.\"
> > +.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
> > +.SH NAME
> > +memfd_secret \- create an anonymous file to access secret memory regions
> > +.SH SYNOPSIS
> > +.nf
> > +.PP
> > +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> > +.B #include <unistd.h>
> > +.PP
> > +.BI "int syscall(SYS_memfd_secret, unsigned int " flags );
> > +.fi
> > +.PP
> > +.IR Note :
> > +glibc provides no wrapper for
> > +.BR memfd_secret (),
> > +necessitating the use of
> > +.BR syscall (2).
> > +.SH DESCRIPTION
> > +.BR memfd_secret ()
> > +creates an anonymous file and returns a file descriptor that refers to it.
> 
> s/file/RAM-based file/
> 
> > +The file provides a way to create and access memory regions
> > +with stronger protection than usual RAM-based files and
> > +anonymous memory mappings.
> > +Once all references to the file are dropped, it is automatically released.
> 
> "dropped" is not clear. Should it be something like:
> 
>     Once all open references to the file are closed,
> 
> > +The initial size of the file is set to 0.
> > +Following the call, the file size should be set using
> > +.BR ftruncate (2).
> > +.PP
> > +The memory areas backing the file created with
> > +.BR memfd_create(2)
> > +are visible only to the contexts that have access to the file descriptor.
> 
> "contexts" is not clear here. Can you reword to explain what you mean?
> (processes, threads, something else?)
> 
> > +These areas are removed from the kernel page tables
> 
> s/These areas are/The memory region is/
> 
> > +and only the page tables of the processes holding the file descriptor
> > +map the corresponding physical memory.
> 
> Perhaps a sentence here such as:
> 
> "(Thus, the pages in the region can't be accessed by the kernel itself,
> so that, for example, pointers to the region can't be passed to 
> system calls.)"
> 
> > +.PP
> > +The following values may be bitwise ORed in
> > +.I flags
> > +to control the behavior of
> > +.BR memfd_secret (2):
> > +.TP
> > +.B FD_CLOEXEC
> > +Set the close-on-exec flag on the new file descriptor.
> 
> s/.$/, which causes the region to be removed from the process on execve(2)./
> 
> > +See the description of the
> > +.B O_CLOEXEC
> > +flag in
> > +.BR open (2)
> > +for reasons why this may be useful.
> 
> Maybe the previous sentence is not necessary?
> 
> > +.PP
> > +As its return value,
> > +.BR memfd_secret ()
> > +returns a new file descriptor that can be used to refer to an anonymous file.
> 
> s/that can be used to refer/that refers/
> 
> > +This file descriptor is opened for both reading and writing
> > +.RB ( O_RDWR )
> > +and
> > +.B O_LARGEFILE
> > +is set for the file descriptor.
> > +.PP
> > +With respect to
> > +.BR fork (2)
> > +and
> > +.BR execve (2),
> > +the usual semantics apply for the file descriptor created by
> > +.BR memfd_secret ().
> > +A copy of the file descriptor is inherited by the child produced by
> > +.BR fork (2)
> > +and refers to the same file.
> > +The file descriptor is preserved across
> > +.BR execve (2),
> > +unless the close-on-exec flag has been set.
> > +.PP
> > +The memory regions backed with
> > +.BR memfd_secret ()
> > +are locked in the same way as
> > +.BR mlock (2),
> 
> I find the wording here just a little unclear
> 
> How about:
> 
>     The memory region is locked into memory in the same way as
>     with mlock(2), so that it will never be written into swap
> 
> > +however the implementation will not try to> +populate the whole range during the
> > +.BR mmap (2)
> > +call.
> 
> s/call./call that attaches the region into the process's address space;
>         instead, the pages are only actually allocated as they are
>         faulted in./
> 
> > +The amount of memory allowed for memory mappings
> > +of the file descriptor obeys the same rules as
> > +.BR mlock (2)
> > +and cannot exceed
> > +.BR RLIMIT_MEMLOCK .
> > +.SH RETURN VALUE
> > +On success,
> > +.BR memfd_secret ()
> > +returns a new file descriptor.
> > +On error, \-1 is returned and
> > +.I errno
> > +is set to indicate the error.
> > +.SH ERRORS
> > +.TP
> > +.B EINVAL
> > +.I flags
> > +included unknown bits.
> > +.TP
> > +.B EMFILE
> > +The per-process limit on the number of open file descriptors has been reached.
> > +.TP
> > +.B EMFILE
> > +The system-wide limit on the total number of open files has been reached.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to create a new anonymous file.
> > +.TP
> > +.B ENOSYS
> > +.BR memfd_secret ()
> > +is not implemented on this architecture.
> > +.SH VERSIONS
> > +The
> > +.BR memfd_secret (2)
> > +system call first appeared in Linux 5.14.
> > +.SH CONFORMING TO
> > +The
> > +.BR memfd_secret (2)
> > +system call is Linux-specific.
> > +.SH SEE ALSO
> > +.BR fcntl (2),
> > +.BR ftruncate (2),
> > +.BR mlock (2),
> > +.BR mmap (2),
> > +.BR setrlimit (2)
> 
> I feel like this page could benefit from a NOTES section
> that explains the rationale for the system call. This could
> note that the fact that the region is not accessible from the
> kernel removes a whole class of security attacks.
> 
> Also, the NOTES section could mention the  "secretmem_enable"
> boot option, what its purpose is, what values it can have,
> and what is default behavior if this option is not specified.
> 
> Also, is ti still the case that if this system call is used,
> then users can no longer hibernate their systems? If so,
> this really should be mentioned in NOTES!
> 
> Also, in NOTES perhaps it is worth mentioning that the
> pages in the region can enter the cache (right?).
> 
> Perhaps Jon's articles at https://lwn.net/Articles/865256/
> https://lwn.net/Articits/835342/ and https://lwn.net/Articles/812325/,
> as well as your own commit message
> (https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=1507f51255c9)
> may inspire some other ideas on details that should be included
> in NOTES.
> 
> Thanks,
> 
> Michael
> 
> -- 
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

-- 
Sincerely yours,
Mike.

[PATCH 09/23] termios.3: Document missing baudrate constants

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

These baudrate macro constants are defined in bits/termios.h and are
already supported.

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man3/termios.3 b/man3/termios.3
index 797778680..01c209944 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -945,6 +945,18 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 	B57600
 	B115200
 	B230400
+	B460800
+	B500000
+	B576000
+	B921600
+	B1000000
+	B1152000
+	B1500000
+	B2000000
+	B2500000
+	B3000000
+	B3500000
+	B4000000
 .ft P
 .fi
 .PP
-- 
2.32.0

Re: [PATCH 09/23] termios.3: Document missing baudrate constants

[Michael Kerrisk (man-pages)]

Hello Pili and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> These baudrate macro constants are defined in bits/termios.h and are
> already supported.
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man3/termios.3 | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 797778680..01c209944 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -945,6 +945,18 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>  	B57600
>  	B115200
>  	B230400
> +	B460800
> +	B500000
> +	B576000
> +	B921600
> +	B1000000
> +	B1152000
> +	B1500000
> +	B2000000
> +	B2500000
> +	B3000000
> +	B3500000
> +	B4000000
>  .ft P
>  .fi
>  .PP
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 10/23] getopt.3: Further clarification of optstring

[Alejandro Colomar]

From: "James O. D. Hunt" <jamesodhunt@gmail.com>

Explain that `optstring` cannot contain a semi-colon (`;`) character.

Also explain that `optstring` can include `+` as an option character,
possibly in addition to that character being used as the first character
in `optstring` to denote `POSIXLY_CORRECT` behaviour.

Signed-off-by: James O. D. Hunt <jamesodhunt@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/getopt.3 | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/man3/getopt.3 b/man3/getopt.3
index ce4c28088..315224c64 100644
--- a/man3/getopt.3
+++ b/man3/getopt.3
@@ -130,7 +130,7 @@ A legitimate option character is any visible one byte
 .BR ascii (7)
 character (for which
 .BR isgraph (3)
-would return nonzero) that is not \(aq\-\(aq or \(aq:\(aq.
+would return nonzero) that is not \(aq\-\(aq, \(aq:\(aq  or \(aq;\(aq.
 If such a
 character is followed by a colon, the option requires an argument, so
 .BR getopt ()
@@ -166,6 +166,14 @@ If the first character of
 .B POSIXLY_CORRECT
 is set, then option processing stops as soon as a nonoption argument is
 encountered.
+If \(aq+\(aq is not the first character of
+.IR optstring ,
+it is treated as a normal option.
+If
+.B POSIXLY_CORRECT
+behaviour is required in this case
+.I optstring
+will contain two \(aq+\(aq symbols.
 If the first character of \fIoptstring\fP is \(aq\-\(aq, then
 each nonoption \fIargv\fP-element is handled as if it were the argument of
 an option with character code 1.  (This is used by programs that were
-- 
2.32.0

Re: [PATCH 10/23] getopt.3: Further clarification of optstring

[Michael Kerrisk (man-pages)]

Hello James and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: "James O. D. Hunt" <jamesodhunt@gmail.com>
> 
> Explain that `optstring` cannot contain a semi-colon (`;`) character.
> 
> Also explain that `optstring` can include `+` as an option character,
> possibly in addition to that character being used as the first character
> in `optstring` to denote `POSIXLY_CORRECT` behaviour.
> 
> Signed-off-by: James O. D. Hunt <jamesodhunt@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man3/getopt.3 | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/getopt.3 b/man3/getopt.3
> index ce4c28088..315224c64 100644
> --- a/man3/getopt.3
> +++ b/man3/getopt.3
> @@ -130,7 +130,7 @@ A legitimate option character is any visible one byte
>  .BR ascii (7)
>  character (for which
>  .BR isgraph (3)
> -would return nonzero) that is not \(aq\-\(aq or \(aq:\(aq.
> +would return nonzero) that is not \(aq\-\(aq, \(aq:\(aq  or \(aq;\(aq.
>  If such a
>  character is followed by a colon, the option requires an argument, so
>  .BR getopt ()
> @@ -166,6 +166,14 @@ If the first character of
>  .B POSIXLY_CORRECT
>  is set, then option processing stops as soon as a nonoption argument is
>  encountered.
> +If \(aq+\(aq is not the first character of
> +.IR optstring ,
> +it is treated as a normal option.
> +If
> +.B POSIXLY_CORRECT
> +behaviour is required in this case
> +.I optstring
> +will contain two \(aq+\(aq symbols.
>  If the first character of \fIoptstring\fP is \(aq\-\(aq, then
>  each nonoption \fIargv\fP-element is handled as if it were the argument of
>  an option with character code 1.  (This is used by programs that were

Thanks. The patch is good and I applied it

@James: it would be helpful to explain in the commit
message how you verified these details.

@Alex: do not be shy of asking people to improve there commit
messages in this way :-).

See my modified commit message below.

Cheers,

Michael

    getopt.3: Further clarification of optstring
    
    Explain that `optstring` cannot contain a semi-colon (`;`)
    character.
    [mtk: verfiried with a small test program; see also posix/getopt.c
    in the glibc sources:
    
        if (temp == NULL || c == ':' || c == ';')
          {
            if (print_errors)
              fprintf (stderr, _("%s: invalid option -- '%c'\n"), argv[0], c);
            d->optopt = c;
            return '?';
          }
    ]
    
    Also explain that `optstring` can include `+` as an option
    character, possibly in addition to that character being used as
    the first character in `optstring` to denote `POSIXLY_CORRECT`
    behaviour.
    [mtk: verified with a small test program.]
    
    Test program below. Example runs:
    
    $ ./a.out -+
    opt = 43 (+); optind = 2
    Got plus
    $ ./a.out -';'
    ./a.out: invalid option -- ';'
    opt = 63 (?); optind = 2; optopt = 59 (;)
    Unrecognized option (-;)
    Usage: ./a.out [-p arg] [-x]
    
    Signed-off-by: James O. D. Hunt <jamesodhunt@gmail.com>
    Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
    
    8x---8x---8x---8x---8x---8x---8x---8x---8x---8x---8x---
    #include <ctype.h>
    #include <sys/types.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <unistd.h>
    
    #define printable(ch) (isprint((unsigned char) ch) ? ch : '#')
    
    static void             /* Print "usage" message and exit */
    usageError(char *progName, char *msg, int opt)
    {
        if (msg != NULL && opt != 0)
            fprintf(stderr, "%s (-%c)\n", msg, printable(opt));
        fprintf(stderr, "Usage: %s [-p arg] [-x]\n", progName);
        exit(EXIT_FAILURE);
    }
    
    int
    main(int argc, char *argv[])
    {
        int opt, xfnd;
        char *pstr;
    
        xfnd = 0;
        pstr = NULL;
    
        while ((opt = getopt(argc, argv, "p:x+;")) != -1) {
            printf("opt =%3d (%c); optind = %d", opt, printable(opt), optind);
            if (opt == '?' || opt == ':')
                printf("; optopt =%3d (%c)", optopt, printable(optopt));
            printf("\n");
    
            switch (opt) {
            case 'p': pstr = optarg;                break;
            case 'x': xfnd++;                       break;
            case ';': printf("Got semicolon\n");    break;
            case '+': printf("Got plus\n"); break;
            case ':': usageError(argv[0], "Missing argument", optopt);
            case '?': usageError(argv[0], "Unrecognized option", optopt);
            default:
                      printf("Unexpected case in switch()\n");
                      exit(EXIT_FAILURE);
            }
        }

        if (xfnd != 0)
            printf("-x was specified (count=%d)\n", xfnd);
        if (pstr != NULL)
            printf("-p was specified with the value \"%s\"\n", pstr);
        if (optind < argc)
            printf("First nonoption argument is \"%s\" at argv[%d]\n",
                    argv[optind], optind);
        exit(EXIT_SUCCESS);
    }

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 10/23] getopt.3: Further clarification of optstring

[Alejandro Colomar (man-pages)]

Hi Michael,

On 8/9/21 12:11 AM, Michael Kerrisk (man-pages) wrote:
> 
> Thanks. The patch is good and I applied it
> 
> @James: it would be helpful to explain in the commit
> message how you verified these details.
> 
> @Alex: do not be shy of asking people to improve there commit
> messages in this way :-).

Yes, I should :-)


> 
> See my modified commit message below.
> 
> Cheers,
> 
> Michael
> 
>      getopt.3: Further clarification of optstring
>      
>      Explain that `optstring` cannot contain a semi-colon (`;`)
>      character.
>      [mtk: verfiried with a small test program; see also posix/getopt.c
>      in the glibc sources:
>      
>          if (temp == NULL || c == ':' || c == ';')
>            {
>              if (print_errors)
>                fprintf (stderr, _("%s: invalid option -- '%c'\n"), argv[0], c);
>              d->optopt = c;
>              return '?';
>            }
>      ]
>      
>      Also explain that `optstring` can include `+` as an option
>      character, possibly in addition to that character being used as
>      the first character in `optstring` to denote `POSIXLY_CORRECT`
>      behaviour.
>      [mtk: verified with a small test program.]
>      
>      Test program below. Example runs:
>      
>      $ ./a.out -+
>      opt = 43 (+); optind = 2
>      Got plus
>      $ ./a.out -';'
>      ./a.out: invalid option -- ';'
>      opt = 63 (?); optind = 2; optopt = 59 (;)
>      Unrecognized option (-;)
>      Usage: ./a.out [-p arg] [-x]
>      
>      Signed-off-by: James O. D. Hunt <jamesodhunt@gmail.com>
>      Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>      Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
>      
>      8x---8x---8x---8x---8x---8x---8x---8x---8x---8x---8x---
>      #include <ctype.h>
>      #include <sys/types.h>
>      #include <stdio.h>
>      #include <stdlib.h>
>      #include <unistd.h>
>      
>      #define printable(ch) (isprint((unsigned char) ch) ? ch : '#')
>      
>      static void             /* Print "usage" message and exit */
>      usageError(char *progName, char *msg, int opt)
>      {
>          if (msg != NULL && opt != 0)
>              fprintf(stderr, "%s (-%c)\n", msg, printable(opt));
>          fprintf(stderr, "Usage: %s [-p arg] [-x]\n", progName);
>          exit(EXIT_FAILURE);
>      }
>      
>      int
>      main(int argc, char *argv[])
>      {
>          int opt, xfnd;
>          char *pstr;
>      
>          xfnd = 0;
>          pstr = NULL;
>      
>          while ((opt = getopt(argc, argv, "p:x+;")) != -1) {
>              printf("opt =%3d (%c); optind = %d", opt, printable(opt), optind);
>              if (opt == '?' || opt == ':')
>                  printf("; optopt =%3d (%c)", optopt, printable(optopt));
>              printf("\n");
>      
>              switch (opt) {
>              case 'p': pstr = optarg;                break;
>              case 'x': xfnd++;                       break;
>              case ';': printf("Got semicolon\n");    break;
>              case '+': printf("Got plus\n"); break;
>              case ':': usageError(argv[0], "Missing argument", optopt);
>              case '?': usageError(argv[0], "Unrecognized option", optopt);
>              default:
>                        printf("Unexpected case in switch()\n");
>                        exit(EXIT_FAILURE);
>              }
>          }
> 
>          if (xfnd != 0)
>              printf("-x was specified (count=%d)\n", xfnd);
>          if (pstr != NULL)
>              printf("-p was specified with the value \"%s\"\n", pstr);
>          if (optind < argc)
>              printf("First nonoption argument is \"%s\" at argv[%d]\n",
>                      argv[optind], optind);
>          exit(EXIT_SUCCESS);
>      }
> 

Nice!

Thanks,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH 11/23] getopt.3: Minor tweak to James's patch

[Alejandro Colomar]

Cc: James O. D. Hunt <jamesodhunt@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/getopt.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/getopt.3 b/man3/getopt.3
index 315224c64..f5970075d 100644
--- a/man3/getopt.3
+++ b/man3/getopt.3
@@ -130,7 +130,7 @@ A legitimate option character is any visible one byte
 .BR ascii (7)
 character (for which
 .BR isgraph (3)
-would return nonzero) that is not \(aq\-\(aq, \(aq:\(aq  or \(aq;\(aq.
+would return nonzero) that is not \(aq\-\(aq, \(aq:\(aq, or \(aq;\(aq.
 If such a
 character is followed by a colon, the option requires an argument, so
 .BR getopt ()
-- 
2.32.0

Re: [PATCH 11/23] getopt.3: Minor tweak to James's patch

[Michael Kerrisk (man-pages)]

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> Cc: James O. D. Hunt <jamesodhunt@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man3/getopt.3 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man3/getopt.3 b/man3/getopt.3
> index 315224c64..f5970075d 100644
> --- a/man3/getopt.3
> +++ b/man3/getopt.3
> @@ -130,7 +130,7 @@ A legitimate option character is any visible one byte
>  .BR ascii (7)
>  character (for which
>  .BR isgraph (3)
> -would return nonzero) that is not \(aq\-\(aq, \(aq:\(aq  or \(aq;\(aq.
> +would return nonzero) that is not \(aq\-\(aq, \(aq:\(aq, or \(aq;\(aq.
>  If such a
>  character is followed by a colon, the option requires an argument, so
>  .BR getopt ()

Thanks, Alex. Patch applied.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 12/23] termios.3: Use bold style for Bnn and EXTn macro constants

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/man3/termios.3 b/man3/termios.3
index 01c209944..b7cdec507 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -1068,8 +1068,14 @@ and
 are nonstandard, but available on the BSDs.
 .SH NOTES
 UNIX\ V7 and several later systems have a list of baud rates
-where after the fourteen values B0, ..., B9600 one finds the
-two constants EXTA, EXTB ("External A" and "External B").
+where after the fourteen values
+.BR B0 ,
+\&.\|.\|.\|,
+.B B9600
+one finds the two constants
+.BR EXTA ,
+.B EXTB
+("External A" and "External B").
 Many systems extend the list with much higher baud rates.
 .PP
 The effect of a nonzero \fIduration\fP with
-- 
2.32.0

Re: [PATCH 12/23] termios.3: Use bold style for Bnn and EXTn macro constants

[Michael Kerrisk (man-pages)]

Hello Pali and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man3/termios.3 | 10 ++++++++--
>  1 file changed, 8 insertions(+), 2 deletions(-)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 01c209944..b7cdec507 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -1068,8 +1068,14 @@ and
>  are nonstandard, but available on the BSDs.
>  .SH NOTES
>  UNIX\ V7 and several later systems have a list of baud rates
> -where after the fourteen values B0, ..., B9600 one finds the
> -two constants EXTA, EXTB ("External A" and "External B").
> +where after the fourteen values
> +.BR B0 ,
> +\&.\|.\|.\|,
> +.B B9600
> +one finds the two constants
> +.BR EXTA ,
> +.B EXTB
> +("External A" and "External B").
>  Many systems extend the list with much higher baud rates.
>  .PP
>  The effect of a nonzero \fIduration\fP with
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_tty.2 | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 46294e63f..967b5c4c7 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -77,6 +77,35 @@ The following four ioctls are just like
 .BR TCSETSW ,
 .BR TCSETSF ,
 except that they take a
+.I "struct termios2\ *"
+instead of a
+.IR "struct termios\ *" .
+If struct member
+.B c_cflag
+contains
+.B BOTHER
+then baudrate is stored in struct members
+.B c_ispeed
+and
+.B c_ospeed
+as integer values.
+These ioctls are not supported on all architectures.
+.RS
+.TS
+lb l.
+TCGETS2	\fBstruct termios2 *\fPargp
+TCSETS2	\fBconst struct termios2 *\fPargp
+TCSETSW2	\fBconst struct termios2 *\fPargp
+TCSETSF2	\fBconst struct termios2 *\fPargp
+.TE
+.RE
+.PP
+The following four ioctls are just like
+.BR TCGETS ,
+.BR TCSETS ,
+.BR TCSETSW ,
+.BR TCSETSF ,
+except that they take a
 .I "struct termio\ *"
 instead of a
 .IR "struct termios\ *" .
-- 
2.32.0

Re: [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Michael Kerrisk (man-pages)]

Hello Pali and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael


> ---
>  man2/ioctl_tty.2 | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 46294e63f..967b5c4c7 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -77,6 +77,35 @@ The following four ioctls are just like
>  .BR TCSETSW ,
>  .BR TCSETSF ,
>  except that they take a
> +.I "struct termios2\ *"
> +instead of a
> +.IR "struct termios\ *" .
> +If struct member
> +.B c_cflag
> +contains
> +.B BOTHER
> +then baudrate is stored in struct members
> +.B c_ispeed
> +and
> +.B c_ospeed
> +as integer values.
> +These ioctls are not supported on all architectures.
> +.RS
> +.TS
> +lb l.
> +TCGETS2	\fBstruct termios2 *\fPargp
> +TCSETS2	\fBconst struct termios2 *\fPargp
> +TCSETSW2	\fBconst struct termios2 *\fPargp
> +TCSETSF2	\fBconst struct termios2 *\fPargp
> +.TE
> +.RE
> +.PP
> +The following four ioctls are just like
> +.BR TCGETS ,
> +.BR TCSETS ,
> +.BR TCSETSW ,
> +.BR TCSETSF ,
> +except that they take a
>  .I "struct termio\ *"
>  instead of a
>  .IR "struct termios\ *" .
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Michael Kerrisk (man-pages)]

Hello Pali and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/ioctl_tty.2 | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 46294e63f..967b5c4c7 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -77,6 +77,35 @@ The following four ioctls are just like
>  .BR TCSETSW ,
>  .BR TCSETSF ,
>  except that they take a
> +.I "struct termios2\ *"
> +instead of a
> +.IR "struct termios\ *" .
> +If struct member
> +.B c_cflag
> +contains
> +.B BOTHER
> +then baudrate is stored in struct members
> +.B c_ispeed
> +and
> +.B c_ospeed
> +as integer values.
> +These ioctls are not supported on all architectures.
> +.RS
> +.TS
> +lb l.
> +TCGETS2	\fBstruct termios2 *\fPargp
> +TCSETS2	\fBconst struct termios2 *\fPargp
> +TCSETSW2	\fBconst struct termios2 *\fPargp
> +TCSETSF2	\fBconst struct termios2 *\fPargp
> +.TE
> +.RE
> +.PP
> +The following four ioctls are just like
> +.BR TCGETS ,
> +.BR TCSETS ,
> +.BR TCSETSW ,
> +.BR TCSETSF ,
> +except that they take a
>  .I "struct termio\ *"
>  instead of a
>  .IR "struct termios\ *" .

The Linux man-pages generally try to maintain historical and 
version info (at least back as far as 2.6.0), so I applied
the patch below.

Thanks,

Michael

commit 48a486dddefa20cddbc83610cf582acecf23e2b3 (HEAD -> master)
Author: Michael Kerrisk <mtk.manpages@gmail.com>
Date:   Sun Aug 8 22:54:29 2021 +0200

    ioctl_tty.2: Note kernel version that added TCGETS2, TCSETS2, TCSETSW2, and TCSETSF2
    
    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 9854cfd3f..1d9a6dee1 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -71,7 +71,10 @@ Equivalent to
 Allow the output buffer to drain, discard pending input, and
 set the current serial port settings.
 .PP
-The following four ioctls are just like
+The following four ioctls, added in Linux 2.6.20,
+.\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6
+.\" commit 592ee3a5e5e2a981ef2829a0380093006d045661
+are just like
 .BR TCGETS ,
 .BR TCSETS ,
 .BR TCSETSW ,


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Pali Rohár]

On Sunday 08 August 2021 22:56:55 Michael Kerrisk (man-pages) wrote:
> Hello Pali and Alex,
> 
> On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> > From: Pali Rohár <pali@kernel.org>
> > 
> > Signed-off-by: Pali Rohár <pali@kernel.org>
> > Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> > ---
> >  man2/ioctl_tty.2 | 29 +++++++++++++++++++++++++++++
> >  1 file changed, 29 insertions(+)
> > 
> > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > index 46294e63f..967b5c4c7 100644
> > --- a/man2/ioctl_tty.2
> > +++ b/man2/ioctl_tty.2
> > @@ -77,6 +77,35 @@ The following four ioctls are just like
> >  .BR TCSETSW ,
> >  .BR TCSETSF ,
> >  except that they take a
> > +.I "struct termios2\ *"
> > +instead of a
> > +.IR "struct termios\ *" .
> > +If struct member
> > +.B c_cflag
> > +contains
> > +.B BOTHER
> > +then baudrate is stored in struct members
> > +.B c_ispeed
> > +and
> > +.B c_ospeed
> > +as integer values.
> > +These ioctls are not supported on all architectures.
> > +.RS
> > +.TS
> > +lb l.
> > +TCGETS2	\fBstruct termios2 *\fPargp
> > +TCSETS2	\fBconst struct termios2 *\fPargp
> > +TCSETSW2	\fBconst struct termios2 *\fPargp
> > +TCSETSF2	\fBconst struct termios2 *\fPargp
> > +.TE
> > +.RE
> > +.PP
> > +The following four ioctls are just like
> > +.BR TCGETS ,
> > +.BR TCSETS ,
> > +.BR TCSETSW ,
> > +.BR TCSETSF ,
> > +except that they take a
> >  .I "struct termio\ *"
> >  instead of a
> >  .IR "struct termios\ *" .
> 
> The Linux man-pages generally try to maintain historical and 
> version info (at least back as far as 2.6.0), so I applied
> the patch below.

Hello Michael! That is a good idea. Anyway, these ioctls were not added
for all architectures as for some they are not needed (when version 1
already contains everything what was introduced in version 2).

I collected all details which I found and I know in this email
https://lore.kernel.org/linux-man/20210808210530.ykqrihpfmdabbdl2@pali/
and it is something which should be properly documented. But I do not
how to put these details into structured manpage...

> Thanks,
> 
> Michael
> 
> commit 48a486dddefa20cddbc83610cf582acecf23e2b3 (HEAD -> master)
> Author: Michael Kerrisk <mtk.manpages@gmail.com>
> Date:   Sun Aug 8 22:54:29 2021 +0200
> 
>     ioctl_tty.2: Note kernel version that added TCGETS2, TCSETS2, TCSETSW2, and TCSETSF2
>     
>     Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 9854cfd3f..1d9a6dee1 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -71,7 +71,10 @@ Equivalent to
>  Allow the output buffer to drain, discard pending input, and
>  set the current serial port settings.
>  .PP
> -The following four ioctls are just like
> +The following four ioctls, added in Linux 2.6.20,
> +.\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6
> +.\" commit 592ee3a5e5e2a981ef2829a0380093006d045661
> +are just like
>  .BR TCGETS ,
>  .BR TCSETS ,
>  .BR TCSETSW ,
> 
> 
> -- 
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Michael Kerrisk (man-pages)]

Hello Pali,

>> The Linux man-pages generally try to maintain historical and 
>> version info (at least back as far as 2.6.0), so I applied
>> the patch below.
> 
> Hello Michael! That is a good idea. Anyway, these ioctls were not added
> for all architectures as for some they are not needed (when version 1
> already contains everything what was introduced in version 2).
> 
> I collected all details which I found and I know in this email
> https://lore.kernel.org/linux-man/20210808210530.ykqrihpfmdabbdl2@pali/
> and it is something which should be properly documented. But I do not
> how to put these details into structured manpage...

It's not immediately obvious to me, either, how to do this.
Perhaps you eventually have some more ideas, but in the meantime,
thanks for the improvements so far.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Pali Rohár]

On Sunday 08 August 2021 22:56:55 Michael Kerrisk (man-pages) wrote:
> Hello Pali and Alex,
> 
> On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> > From: Pali Rohár <pali@kernel.org>
> > 
> > Signed-off-by: Pali Rohár <pali@kernel.org>
> > Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> > ---
> >  man2/ioctl_tty.2 | 29 +++++++++++++++++++++++++++++
> >  1 file changed, 29 insertions(+)
> > 
> > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > index 46294e63f..967b5c4c7 100644
> > --- a/man2/ioctl_tty.2
> > +++ b/man2/ioctl_tty.2
> > @@ -77,6 +77,35 @@ The following four ioctls are just like
> >  .BR TCSETSW ,
> >  .BR TCSETSF ,
> >  except that they take a
> > +.I "struct termios2\ *"
> > +instead of a
> > +.IR "struct termios\ *" .
> > +If struct member
> > +.B c_cflag
> > +contains
> > +.B BOTHER
> > +then baudrate is stored in struct members
> > +.B c_ispeed
> > +and
> > +.B c_ospeed
> > +as integer values.
> > +These ioctls are not supported on all architectures.
> > +.RS
> > +.TS
> > +lb l.
> > +TCGETS2	\fBstruct termios2 *\fPargp
> > +TCSETS2	\fBconst struct termios2 *\fPargp
> > +TCSETSW2	\fBconst struct termios2 *\fPargp
> > +TCSETSF2	\fBconst struct termios2 *\fPargp
> > +.TE
> > +.RE
> > +.PP
> > +The following four ioctls are just like
> > +.BR TCGETS ,
> > +.BR TCSETS ,
> > +.BR TCSETSW ,
> > +.BR TCSETSF ,
> > +except that they take a
> >  .I "struct termio\ *"
> >  instead of a
> >  .IR "struct termios\ *" .
> 
> The Linux man-pages generally try to maintain historical and 
> version info (at least back as far as 2.6.0), so I applied
> the patch below.
> 
> Thanks,
> 
> Michael
> 
> commit 48a486dddefa20cddbc83610cf582acecf23e2b3 (HEAD -> master)
> Author: Michael Kerrisk <mtk.manpages@gmail.com>
> Date:   Sun Aug 8 22:54:29 2021 +0200
> 
>     ioctl_tty.2: Note kernel version that added TCGETS2, TCSETS2, TCSETSW2, and TCSETSF2
>     
>     Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 9854cfd3f..1d9a6dee1 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -71,7 +71,10 @@ Equivalent to
>  Allow the output buffer to drain, discard pending input, and
>  set the current serial port settings.
>  .PP
> -The following four ioctls are just like
> +The following four ioctls, added in Linux 2.6.20,
> +.\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6
> +.\" commit 592ee3a5e5e2a981ef2829a0380093006d045661
> +are just like
>  .BR TCGETS ,
>  .BR TCSETS ,
>  .BR TCSETSW ,

Hello Michael! Seems that you applied patches to your tree incorrectly.
Now ioctl TCGETS2 is documented two times, looks like you have applied
my commit two times.

Open 'man ./man2/ioctl_tty.2' and search for TCGETS2.

Re: [PATCH 13/23] ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2

[Michael Kerrisk (man-pages)]

hello Pali,

On Tue, 10 Aug 2021 at 21:11, Pali Rohár <pali@kernel.org> wrote:
>
> Hello Michael! Seems that you applied patches to your tree incorrectly.
> Now ioctl TCGETS2 is documented two times, looks like you have applied
> my commit two times.
>
> Open 'man ./man2/ioctl_tty.2' and search for TCGETS2.

Thanks. I'm not sure how I did that, but it's fixed now.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 14/23] ioctl_tty.2: Update DTR example

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Do not include unused (and incompatible) header file termios.h and include
required header files for puts() and close() functions.

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioctl_tty.2 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 967b5c4c7..519e4606f 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -730,7 +730,8 @@ Insufficient permission.
 Check the condition of DTR on the serial port.
 .PP
 .EX
-#include <termios.h>
+#include <stdio.h>
+#include <unistd.h>
 #include <fcntl.h>
 #include <sys/ioctl.h>
 
-- 
2.32.0

Re: [PATCH 14/23] ioctl_tty.2: Update DTR example

[Michael Kerrisk (man-pages)]

Hello Pali and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> Do not include unused (and incompatible) header file termios.h and include
> required header files for puts() and close() functions.
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael


> ---
>  man2/ioctl_tty.2 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 967b5c4c7..519e4606f 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -730,7 +730,8 @@ Insufficient permission.
>  Check the condition of DTR on the serial port.
>  .PP
>  .EX
> -#include <termios.h>
> +#include <stdio.h>
> +#include <unistd.h>
>  #include <fcntl.h>
>  #include <sys/ioctl.h>
>  
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 15/23] termios.3: Add information how to set baud rate to any other value

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/man3/termios.3 b/man3/termios.3
index b7cdec507..7023025e7 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -968,6 +968,13 @@ Normally, this will disconnect the line.
 for the speeds beyond those defined in POSIX.1 (57600 and above).
 Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero.
 .PP
+Setting the baud rate to a value other than those defined by
+.B Bnnn
+constants is possible via the
+.B TCSETS2
+ioctl; see
+.BR ioctl_tty (2).
+.PP
 .BR cfgetispeed ()
 returns the input baud rate stored in the \fItermios\fP structure.
 .PP
-- 
2.32.0

Re: [PATCH 15/23] termios.3: Add information how to set baud rate to any other value

[Michael Kerrisk (man-pages)]

Hello Pali and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Thanks,

Michael

> ---
>  man3/termios.3 | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index b7cdec507..7023025e7 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -968,6 +968,13 @@ Normally, this will disconnect the line.
>  for the speeds beyond those defined in POSIX.1 (57600 and above).
>  Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero.
>  .PP
> +Setting the baud rate to a value other than those defined by
> +.B Bnnn
> +constants is possible via the
> +.B TCSETS2
> +ioctl; see
> +.BR ioctl_tty (2).
> +.PP
>  .BR cfgetispeed ()
>  returns the input baud rate stored in the \fItermios\fP structure.
>  .PP
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 16/23] man-pages.7: wfix

[Alejandro Colomar]

From: "G. Branden Robinson" <g.branden.robinson@gmail.com>

Saw this while preparing the "switch to \~" change Alex invited.

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/man-pages.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 6cb805343..3819dfd97 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -638,7 +638,7 @@ makes it easier to write tools that parse man page source files.)
 .SS Use semantic newlines
 In the source of a manual page,
 new sentences should be started on new lines,
-and long sentences should split into lines at clause breaks
+and long sentences should be split into lines at clause breaks
 (commas, semicolons, colons, and so on).
 This convention, sometimes known as "semantic newlines",
 makes it easier to see the effect of patches,
-- 
2.32.0

Re: [PATCH 16/23] man-pages.7: wfix

[Michael Kerrisk (man-pages)]

Hello Branden and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> 
> Saw this while preparing the "switch to \~" change Alex invited.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man7/man-pages.7 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man7/man-pages.7 b/man7/man-pages.7
> index 6cb805343..3819dfd97 100644
> --- a/man7/man-pages.7
> +++ b/man7/man-pages.7
> @@ -638,7 +638,7 @@ makes it easier to write tools that parse man page source files.)
>  .SS Use semantic newlines
>  In the source of a manual page,
>  new sentences should be started on new lines,
> -and long sentences should split into lines at clause breaks
> +and long sentences should be split into lines at clause breaks
>  (commas, semicolons, colons, and so on).
>  This convention, sometimes known as "semantic newlines",
>  makes it easier to see the effect of patches,
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 16/23] man-pages.7: wfix

[Alejandro Colomar (man-pages)]

Hi Branden,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> 
> Saw this while preparing the "switch to \~" change Alex invited.

Ping.  You're still invited :-)

Cheers,

Alex

> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>   man7/man-pages.7 | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man7/man-pages.7 b/man7/man-pages.7
> index 6cb805343..3819dfd97 100644
> --- a/man7/man-pages.7
> +++ b/man7/man-pages.7
> @@ -638,7 +638,7 @@ makes it easier to write tools that parse man page source files.)
>   .SS Use semantic newlines
>   In the source of a manual page,
>   new sentences should be started on new lines,
> -and long sentences should split into lines at clause breaks
> +and long sentences should be split into lines at clause breaks
>   (commas, semicolons, colons, and so on).
>   This convention, sometimes known as "semantic newlines",
>   makes it easier to see the effect of patches,
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH 17/23] termios.3: ffix

[Alejandro Colomar]

Format variable parts of words referring to a group of identifiers in italics,
following groff_man(7) recommendations.

Also srcfix surrounding uses of \f escape sequences to use macros

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/man3/termios.3 b/man3/termios.3
index 7023025e7..4fbd34a52 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -960,28 +960,38 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 .ft P
 .fi
 .PP
-The zero baud rate, \fBB0\fP,
+The zero baud rate,
+.BR B0 ,
 is used to terminate the connection.
 If B0 is specified, the modem control lines shall no longer be asserted.
 Normally, this will disconnect the line.
-\fBCBAUDEX\fP is a mask
+.B CBAUDEX
+is a mask
 for the speeds beyond those defined in POSIX.1 (57600 and above).
-Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero.
+Thus,
+.BR B57600 " & " CBAUDEX
+is nonzero.
 .PP
 Setting the baud rate to a value other than those defined by
-.B Bnnn
+.BI B nnn
 constants is possible via the
 .B TCSETS2
 ioctl; see
 .BR ioctl_tty (2).
 .PP
 .BR cfgetispeed ()
-returns the input baud rate stored in the \fItermios\fP structure.
+returns the input baud rate stored in the
+.I termios
+structure.
 .PP
 .BR cfsetispeed ()
-sets the input baud rate stored in the \fItermios\fP structure to
+sets the input baud rate stored in the
+.I termios
+structure to
 .IR speed ,
-which must be specified as one of the \fBBnnn\fP constants listed above for
+which must be specified as one of the
+.BI B nnn
+constants listed above for
 .BR cfsetospeed ().
 If the input baud rate is set to zero, the input baud rate will be
 equal to the output baud rate.
-- 
2.32.0

Re: [PATCH 17/23] termios.3: ffix

[Michael Kerrisk (man-pages)]

Hello Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> Format variable parts of words referring to a group of identifiers in italics,
> following groff_man(7) recommendations.
> 
> Also srcfix surrounding uses of \f escape sequences to use macros
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks for the clean-ups! Patch applied.

Cheers,

Michael

> ---
>  man3/termios.3 | 24 +++++++++++++++++-------
>  1 file changed, 17 insertions(+), 7 deletions(-)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 7023025e7..4fbd34a52 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -960,28 +960,38 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>  .ft P
>  .fi
>  .PP
> -The zero baud rate, \fBB0\fP,
> +The zero baud rate,
> +.BR B0 ,
>  is used to terminate the connection.
>  If B0 is specified, the modem control lines shall no longer be asserted.
>  Normally, this will disconnect the line.
> -\fBCBAUDEX\fP is a mask
> +.B CBAUDEX
> +is a mask
>  for the speeds beyond those defined in POSIX.1 (57600 and above).
> -Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero.
> +Thus,
> +.BR B57600 " & " CBAUDEX
> +is nonzero.
>  .PP
>  Setting the baud rate to a value other than those defined by
> -.B Bnnn
> +.BI B nnn
>  constants is possible via the
>  .B TCSETS2
>  ioctl; see
>  .BR ioctl_tty (2).
>  .PP
>  .BR cfgetispeed ()
> -returns the input baud rate stored in the \fItermios\fP structure.
> +returns the input baud rate stored in the
> +.I termios
> +structure.
>  .PP
>  .BR cfsetispeed ()
> -sets the input baud rate stored in the \fItermios\fP structure to
> +sets the input baud rate stored in the
> +.I termios
> +structure to
>  .IR speed ,
> -which must be specified as one of the \fBBnnn\fP constants listed above for
> +which must be specified as one of the
> +.BI B nnn
> +constants listed above for
>  .BR cfsetospeed ().
>  If the input baud rate is set to zero, the input baud rate will be
>  equal to the output baud rate.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 18/23] termios.3: SPARC architecture has 4 different Bnnn constants

[Alejandro Colomar]

From: Pali Rohár <pali@kernel.org>

SPARC is special, it does not have Bnnn constants for baud rates above
2000000. Instead it defines 4 Bnnn constants with smaller baud rates.

This difference between SPARC and non-SPARC architectures is present in
both glibc API (termios.h) and also kernel ioctl API (asm/termbits.h).

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/termios.3 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/man3/termios.3 b/man3/termios.3
index 4fbd34a52..8c88c25e4 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -953,6 +953,24 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 	B1152000
 	B1500000
 	B2000000
+.ft P
+.fi
+.PP
+These constants are additionally supported on the SPARC architecture:
+.PP
+.nf
+.ft B
+	B76800
+	B153600
+	B307200
+	B614400
+.ft P
+.fi
+.PP
+These constants are additionally supported on non-SPARC architectures:
+.PP
+.nf
+.ft B
 	B2500000
 	B3000000
 	B3500000
@@ -960,6 +978,11 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 .ft P
 .fi
 .PP
+Due to differences between architectures, portable applications should check
+if a particular
+.BI B nnn
+constant is defined prior to using it.
+.PP
 The zero baud rate,
 .BR B0 ,
 is used to terminate the connection.
-- 
2.32.0

Re: [PATCH 18/23] termios.3: SPARC architecture has 4 different Bnnn constants

[Michael Kerrisk (man-pages)]

Hello Pai and Alex

@Pali Thanks so much for these fixes to termios(3) and ioctl_tty(2)!

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Pali Rohár <pali@kernel.org>
> 
> SPARC is special, it does not have Bnnn constants for baud rates above
> 2000000. Instead it defines 4 Bnnn constants with smaller baud rates.
> 
> This difference between SPARC and non-SPARC architectures is present in
> both glibc API (termios.h) and also kernel ioctl API (asm/termbits.h).
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Cheers,

Michael

> ---
>  man3/termios.3 | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 4fbd34a52..8c88c25e4 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -953,6 +953,24 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>  	B1152000
>  	B1500000
>  	B2000000
> +.ft P
> +.fi
> +.PP
> +These constants are additionally supported on the SPARC architecture:
> +.PP
> +.nf
> +.ft B
> +	B76800
> +	B153600
> +	B307200
> +	B614400
> +.ft P
> +.fi
> +.PP
> +These constants are additionally supported on non-SPARC architectures:
> +.PP
> +.nf
> +.ft B
>  	B2500000
>  	B3000000
>  	B3500000
> @@ -960,6 +978,11 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>  .ft P
>  .fi
>  .PP
> +Due to differences between architectures, portable applications should check
> +if a particular
> +.BI B nnn
> +constant is defined prior to using it.
> +.PP
>  The zero baud rate,
>  .BR B0 ,
>  is used to terminate the connection.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 19/23] regex.3: wfix

[Alejandro Colomar]

From: наб <nabijaczleweli@nabijaczleweli.xyz>

"address of regcomp() initialized buffer" ->
"address of regcomp()-initialized buffer"

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/regex.3 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man3/regex.3 b/man3/regex.3
index b6a83271c..368f48d78 100644
--- a/man3/regex.3
+++ b/man3/regex.3
@@ -66,8 +66,8 @@ All regular expression searching must be done via a compiled pattern
 buffer, thus
 .BR regexec ()
 must always be supplied with the address of a
-.BR regcomp ()
-initialized pattern buffer.
+.BR regcomp ()-initialized
+pattern buffer.
 .PP
 .I cflags
 is the
-- 
2.32.0

Re: [PATCH 19/23] regex.3: wfix

[Michael Kerrisk (man-pages)]

Hallo наб and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: наб <nabijaczleweli@nabijaczleweli.xyz>
> 
> "address of regcomp() initialized buffer" ->
> "address of regcomp()-initialized buffer"
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks, applied.

Cheers,

Michael



> ---
>  man3/regex.3 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man3/regex.3 b/man3/regex.3
> index b6a83271c..368f48d78 100644
> --- a/man3/regex.3
> +++ b/man3/regex.3
> @@ -66,8 +66,8 @@ All regular expression searching must be done via a compiled pattern
>  buffer, thus
>  .BR regexec ()
>  must always be supplied with the address of a
> -.BR regcomp ()
> -initialized pattern buffer.
> +.BR regcomp ()-initialized
> +pattern buffer.
>  .PP
>  .I cflags
>  is the
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 20/23] mount_setattr.2: New manual page documenting the mount_setattr() system call

[Alejandro Colomar]

From: Christian Brauner <christian.brauner@ubuntu.com>

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
Cc: Christoph Hellwig <hch@infradead.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/mount_setattr.2 | 1002 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1002 insertions(+)
 create mode 100644 man2/mount_setattr.2

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
new file mode 100644
index 000000000..16881d90d
--- /dev/null
+++ b/man2/mount_setattr.2
@@ -0,0 +1,1002 @@
+.\" Copyright (c) 2021 by Christian Brauner <christian.brauner@ubuntu.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.TH MOUNT_SETATTR 2 2021-03-22 "Linux" "Linux Programmer's Manual"
+.SH NAME
+mount_setattr \- change mount properties of a mount or mount tree
+.SH SYNOPSIS
+.nf
+
+.PP
+.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
+.BR "#include <linux/mount.h>" " /* Definition of struct mount_attr and MOUNT_ATTR_* constants */"
+.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path \
+", unsigned int " flags \
+", struct mount_attr *" attr ", size_t " size );
+.fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR mount_setattr (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+The
+.BR mount_setattr (2)
+system call changes the mount properties of a mount or entire mount tree.
+If
+.I path
+is a relative pathname,
+then it is interpreted relative to the directory referred to by the file
+descriptor
+.IR dfd .
+If
+.I dfd
+is the special value
+.B AT_FDCWD
+then
+.I path
+is taken to be relative to the current working directory of the calling process.
+If
+.I path
+is the empty string and
+.BR AT_EMPTY_PATH
+is specified in
+.I flags
+then the mount properties of the mount identified by
+.I dfd
+are changed.
+.PP
+The
+.BR mount_setattr (2)
+system call uses an extensible structure
+.IR ( "struct mount_attr" )
+to allow for future extensions.
+Any non-flag extensions to
+.BR mount_setattr (2)
+will be implemented as new fields appended to the above structure,
+with a zero value in a new field resulting in the kernel behaving
+as though that extension field was not present.
+Therefore,
+the caller
+.I must
+zero-fill this structure on initialization.
+Please see the "Extensibility" section under
+.B NOTES
+for more details.
+.PP
+The
+.I size
+argument should usually be specified as
+.IR "sizeof(struct mount_attr)" .
+However,
+if the caller does not intend to make use of features that got
+introduced after the initial version of
+.I struct mount_attr
+they are free to pass the size of the initial struct together with the larger
+struct.
+This allows the kernel to not copy later parts of the struct that aren't used
+anyway.
+With each extension that changes the size of
+.I struct mount_attr
+the kernel will expose a define of the form
+.BR MOUNT_ATTR_SIZE_VER<number> .
+For example the macro for the size of the initial version of
+.I struct mount_attr
+is
+.BR MOUNT_ATTR_SIZE_VER0 .
+.PP
+The
+.I flags
+argument can be used to alter the path resolution behavior.
+The supported values are:
+.TP
+.B AT_EMPTY_PATH
+If
+.I path
+is the empty string change the mount properties on
+.I dfd
+itself.
+.TP
+.B AT_RECURSIVE
+Change the mount properties of the entire mount tree.
+.TP
+.B AT_SYMLINK_NOFOLLOW
+Don't follow trailing symlinks.
+.TP
+.B AT_NO_AUTOMOUNT
+Don't trigger automounts.
+.PP
+The
+.I attr
+argument of
+.BR mount_setattr (2)
+is a structure of the following form:
+.PP
+.in +4n
+.EX
+struct mount_attr {
+    __u64 attr_set;    /* Mount properties to set. */
+    __u64 attr_clr;    /* Mount properties to clear. */
+    __u64 propagation; /* Mount propagation type. */
+    __u64 userns_fd;   /* User namespace file descriptor. */
+};
+.EE
+.in
+.PP
+The
+.I attr_set
+and
+.I attr_clr
+members are used to specify the mount properties that are supposed to be set or
+cleared for a mount or mount tree.
+Flags set in
+.I attr_set
+enable a property on a mount or mount tree and flags set in
+.I attr_clr
+remove a property from a mount or mount tree.
+.PP
+When changing mount properties the kernel will first clear the flags specified
+in the
+.I attr_clr
+field and then set the flags specified in the
+.I attr_set
+field:
+.PP
+.in +4n
+.EX
+struct mount_attr attr = {
+    .attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV,
+    .attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID,
+};
+unsigned int current_mnt_flags = mnt->mnt_flags;
+
+/*
+ * Clear all flags set in .attr_clr,
+ * clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV.
+ */
+current_mnt_flags &= ~attr->attr_clr;
+
+/*
+ * Now set all flags set in .attr_set,
+ * applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID.
+ */
+current_mnt_flags |= attr->attr_set;
+
+mnt->mnt_flags = current_mnt_flags;
+.EE
+.in
+.PP
+The effect of this change will be a mount or mount tree that is read-only,
+blocks the execution of set-user-ID and set-group-ID binaries but does allow to
+execute programs and access to devices nodes.
+Multiple changes with the same set of flags requested
+in
+.I attr_clr
+and
+.I attr_set
+are guaranteed to be idempotent after the changes have been applied.
+.PP
+The following mount attributes can be specified in the
+.I attr_set
+or
+.I attr_clr
+fields:
+.TP
+.B MOUNT_ATTR_RDONLY
+If set in
+.I attr_set
+makes the mount read-only and if set in
+.I attr_clr
+removes the read-only setting if set on the mount.
+.TP
+.B MOUNT_ATTR_NOSUID
+If set in
+.I attr_set
+makes the mount not honor set-user-ID and set-group-ID binaries,
+and file capabilities when executing programs.
+If set in
+.I attr_clr
+clears the set-user-ID, set-group-ID,
+and file capability restriction if set on this mount.
+.TP
+.B MOUNT_ATTR_NODEV
+If set in
+.I attr_set
+prevents access to devices on this mount and if set in
+.I attr_clr
+removes the device access restriction if set on this mount.
+.TP
+.BR MOUNT_ATTR_NOEXEC
+If set in
+.I attr_set
+prevents executing programs on this mount and if set in
+.I attr_clr
+removes the restriction to execute programs on this mount.
+.TP
+.BR MOUNT_ATTR_NOSYMFOLLOW
+If set in
+.I attr_set
+prevents following symlinks on this mount and if set in
+.I attr_clr
+removes the restriction to not follow symlinks on this mount.
+.TP
+.B MOUNT_ATTR_NODIRATIME
+If set in
+.I attr_set
+prevents updating access time for directories on this mount and if set in
+.I attr_clr
+removes access time restriction for directories.
+Note that
+.BR MOUNT_ATTR_NODIRATIME
+can be combined with other access time settings and is implied
+by the noatime setting.
+All other access time settings are mutually exclusive.
+.TP
+.BR MOUNT_ATTR__ATIME " - Changing access time settings
+In the new mount api the access time values are an enum starting from 0.
+Even though they are an enum in contrast to the other mount flags such as
+.BR MOUNT_ATTR_NOEXEC
+they are nonetheless passed in
+.I attr_set
+and
+.I attr_clr
+for consistency with
+.BR fsmount (2)
+which introduced this behavior.
+.IP
+Note,
+since access times are an enum,
+not a bitmap,
+users wanting to transition to a different access time setting cannot simply
+specify the access time in
+.I attr_set
+but must also set
+.B MOUNT_ATTR__ATIME
+in the
+.I attr_clr
+field.
+The kernel will verify that
+.BR MOUNT_ATTR__ATIME
+isn't partially set in
+.I attr_clr
+and that
+.I attr_set
+doesn't have any access time bits set if
+.BR MOUNT_ATTR__ATIME
+isn't set in
+.IR attr_clr .
+.RS
+.TP
+.B MOUNT_ATTR_RELATIME
+When a file is accessed via this mount,
+update the file's last access time
+(atime)
+only if the current value of atime is less than or equal to the file's
+last modification time (mtime) or last status change time (ctime).
+.IP
+To enable this access time setting on a mount or mount tree
+.BR MOUNT_ATTR_RELATIME
+must be set in
+.I attr_set
+and
+.BR MOUNT_ATTR__ATIME
+must be set in the
+.I attr_clr
+field.
+.TP
+.BR MOUNT_ATTR_NOATIME
+Do not update access times for (all types of) files on this mount.
+.IP
+To enable this access time setting on a mount or mount tree
+.BR MOUNT_ATTR_NOATIME
+must be set in
+.I attr_set
+and
+.BR MOUNT_ATTR__ATIME
+must be set in the
+.I attr_clr
+field.
+.TP
+.BR MOUNT_ATTR_STRICTATIME
+Always update the last access time (atime) when files are accessed on this
+mount.
+.IP
+To enable this access time setting on a mount or mount tree
+.BR MOUNT_ATTR_STRICTATIME
+must be set in
+.I attr_set
+and
+.BR MOUNT_ATTR__ATIME
+must be set in the
+.I attr_clr
+field.
+.RE
+.TP
+.BR MOUNT_ATTR_IDMAP
+If set in
+.I attr_set
+creates an idmapped mount.
+Since it is not supported to change the idmapping of a mount after it has been
+idmapped,
+it is invalid to specify
+.B MOUNT_ATTR_IDMAP
+in
+.IR attr_clr .
+The idmapping is taken from the user namespace specified in
+.I userns_fd
+and attached to the mount.
+More details can be found in subsequent paragraphs.
+.IP
+Creating an idmapped mount allows to change the ownership of all files located
+under a mount.
+Thus, idmapped mounts make it possible to change ownership in a temporary and
+localized way.
+It is a localized change because ownership changes are restricted to a specific
+mount.
+All other users and locations where the filesystem is exposed are unaffected.
+And it is a temporary change because ownership changes are tied to the lifetime
+of the mount.
+.IP
+Whenever callers interact with the filesystem through an idmapped mount the
+idmapping of the mount will be applied to user and group IDs associated with
+filesystem objects.
+This encompasses the user and group IDs associated with inodes and also
+the following
+.BR xattr (7)
+keys:
+.RS
+.RS
+.IP \(bu 2
+.IR security.capability
+whenever filesystem
+.BR capabilities (7)
+are stored or returned in the
+.I VFS_CAP_REVISION_3
+format which stores a rootid alongside the capabilities.
+.IP \(bu 2
+.I system.posix_acl_access
+and
+.I system.posix_acl_default
+whenever user IDs or group IDs are stored in
+.BR ACL_USER
+and
+.BR ACL_GROUP
+entries.
+.RE
+.RE
+.IP
+The following conditions must be met in order to create an idmapped mount:
+.RS
+.RS
+.IP \(bu 2
+The caller must have
+.I CAP_SYS_ADMIN
+in the initial user namespace.
+.IP \(bu 2
+The filesystem must be mounted in the initial user namespace.
+.IP \(bu
+The underlying filesystem must support idmapped mounts.
+Currently
+.BR xfs (5),
+.BR ext4 (5)
+and
+.BR fat
+filesystems support idmapped mounts with more filesystems being actively worked
+on.
+.IP \(bu
+The mount must not already be idmapped.
+This also implies that the idmapping of a mount cannot be altered.
+.IP \(bu
+The mount must be a detached/anonymous mount,
+i.e.,
+it must have been created by calling
+.BR open_tree (2)
+with the
+.I OPEN_TREE_CLONE
+flag and it must not already have been visible in the filesystem.
+.RE
+.RE
+.IP
+Idmappings can be created for user IDs, group IDs, and project IDs.
+An idmapping is essentially a mapping of a range of user or group IDs into
+another or the same range of user or group IDs.
+Idmappings are usually written as three numbers either separated by white space
+or a full stop.
+The first two numbers specify the starting user or group ID in each of the two
+user namespaces.
+The third number specifies the range of the idmapping.
+For example, a mapping for user IDs such as 1000:1001:1 would indicate that
+user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its
+ancestor user namespace.
+Since the map range is 1 only user ID 1000 is mapped.
+It is possible to specify up to 340 idmappings for each idmapping type.
+If any user IDs or group IDs are not mapped all files owned by that unmapped
+user or group ID will appear as being owned by the overflow user ID or overflow
+group ID respectively.
+Further details and instructions for setting up idmappings can be found in the
+.BR user_namespaces (7)
+man page.
+.IP
+In the common case the user namespace passed in
+.I userns_fd
+together with
+.BR MOUNT_ATTR_IDMAP
+in
+.I attr_set
+to create an idmapped mount will be the user namespace of a container.
+In other scenarios it will be a dedicated user namespace associated with a
+user's login session as is the case for portable home directories in
+.BR systemd-homed.service (8) ).
+It is also perfectly fine to create a dedicated user namespace for the sake of
+idmapping a mount.
+.IP
+Idmapped mounts can be useful in the following and a variety of other
+scenarios:
+.RS
+.RS
+.IP \(bu 2
+sharing files between multiple users or multiple machines especially in
+complex scenarios.
+For example,
+idmapped mounts are used to implement portable home directories in
+.BR systemd-homed.service (8)
+where they allow users to move their home directory to an external storage
+device and use it on multiple computers where they are assigned different user IDs
+and group IDs.
+This effectively makes it possible to assign random user IDs and group IDs at login time.
+.IP \(bu
+sharing files from the host with unprivileged containers.
+This allows user to avoid having to change ownership permanently through
+.BR chown (2) .
+.IP \(bu
+idmapping a container's root filesystem.
+Users don't need to change ownership
+permanently through
+.BR chown (2) .
+Especially for large root filesystems using
+.BR chown (2)
+can be prohibitively expensive.
+.IP \(bu
+sharing files between containers with non-overlapping
+idmappings.
+.IP \(bu
+implementing discretionary access (DAC) permission checking for fileystems
+lacking a concept of ownership.
+.IP \(bu
+efficiently change ownership on a per-mount basis.
+In contrast to
+.BR chown (2)
+changing ownership of large sets of files is instantenous with idmapped mounts.
+This is especially useful when ownership of an entire root filesystem of a
+virtual machine or container is to be changed as we've mentioned above.
+With idmapped mounts a single
+.BR mount_setattr (2)
+system call will be sufficient to change the ownership of all files.
+.IP \(bu
+taking the current ownership into account.
+Idmappings specify precisely what a user or group ID is supposed to be
+mapped to.
+This contrasts with the
+.BR chown (2)
+system call which cannot by itself take the current ownership of the files it
+changes into account.
+It simply changes the ownership to the specified user ID and group ID.
+.IP \(bu
+locally and temporarily restricted ownership changes.
+Idmapped mounts allow to change ownership locally,
+restricting it to specific mounts,
+and temporarily as the ownership changes only apply as long as the mount exists.
+In contrast,
+changing ownership via the
+.BR chown (2)
+system call changes the ownership globally and permanently.
+.RE
+.RE
+.PP
+The
+.I propagation
+field is used to specify the propagation type of the mount or mount tree.
+Mount propagation options are mutually exclusive,
+i.e.,
+the propagation values behave like an enum.
+The supported mount propagation settings are:
+.TP
+.B MS_PRIVATE
+Turn all mounts into private mounts.
+Mount and unmount events do not propagate into or out of this mount point.
+.TP
+.B MS_SHARED
+Turn all mounts into shared mounts.
+Mount points share events with members of a peer group.
+Mount and unmount events immediately under this mount point
+will propagate to the other mount points that are members of the peer group.
+Propagation here means that the same mount or unmount will automatically occur
+under all of the other mount points in the peer group.
+Conversely,
+mount and unmount events that take place under peer mount points will propagate
+to this mount point.
+.TP
+.B MS_SLAVE
+Turn all mounts into dependent mounts.
+Mount and unmount events propagate into this mount point from a shared peer
+group.
+Mount and unmount events under this mount point do not propagate to any peer.
+.TP
+.B MS_UNBINDABLE
+This is like a private mount,
+and in addition this mount can't be bind mounted.
+Attempts to bind mount this mount will fail.
+When a recursive bind mount is performed on a directory subtree,
+any bind mounts within the subtree are automatically pruned
+(i.e., not replicated)
+when replicating that subtree to produce the target subtree.
+.PP
+.SH RETURN VALUE
+On success,
+.BR mount_setattr (2)
+returns zero.
+On error,
+\-1 is returned and
+.I errno
+is set to indicate the cause of the error.
+.SH ERRORS
+.TP
+.B EBADF
+.I dfd
+is not a valid file descriptor.
+.TP
+.B EBADF
+.I userns_fd
+is not a valid file descriptor.
+.TP
+.B EBUSY
+The caller tried to change the mount to
+.BR MOUNT_ATTR_RDONLY
+but the mount still has files open for writing.
+.TP
+.B EINVAL
+The path specified via the
+.I dfd
+and
+.I path
+arguments to
+.BR mount_setattr (2)
+isn't a mountpoint.
+.TP
+.B EINVAL
+An unsupported value was set in
+.I flags.
+.TP
+.B EINVAL
+An unsupported value was specified in the
+.I attr_set
+field of
+.IR mount_attr .
+.TP
+.B EINVAL
+An unsupported value was specified in the
+.I attr_clr
+field of
+.IR mount_attr .
+.TP
+.B EINVAL
+An unsupported value was specified in the
+.I propagation
+field of
+.IR mount_attr .
+.TP
+.B EINVAL
+More than one of
+.BR MS_SHARED,
+.BR MS_SLAVE,
+.BR MS_PRIVATE,
+or
+.BR MS_UNBINDABLE
+was set in
+.I propagation
+field of
+.IR mount_attr .
+.TP
+.B EINVAL
+An access time setting was specified in the
+.I attr_set
+field without
+.BR MOUNT_ATTR__ATIME
+being set in the
+.I attr_clr
+field.
+.TP
+.B EINVAL
+.BR MOUNT_ATTR_IDMAP
+was specified in
+.IR attr_clr .
+.TP
+.B EINVAL
+A file descriptor value was specified in
+.I userns_fd
+which exceeds
+.BR INT_MAX .
+.TP
+.B EINVAL
+A valid file descriptor value was specified in
+.I userns_fd
+but the file descriptor wasn't a namespace file descriptor or did not refer to
+a user namespace.
+.TP
+.B EINVAL
+The underlying filesystem does not support idmapped mounts.
+.TP
+.B EINVAL
+The mount to idmap is not a detached/anonymous mount,
+i.e.,
+the mount is already visible in the filesystem.
+.TP
+.B EINVAL
+A partial access time setting was specified in
+.I attr_clr
+instead of
+.BR MOUNT_ATTR__ATIME
+being set.
+.TP
+.B EINVAL
+The mount is located outside the caller's mount namespace.
+.TP
+.B EINVAL
+The underlying filesystem is mounted in a user namespace.
+.TP
+.B ENOENT
+A pathname was empty or had a nonexistent component.
+.TP
+.B ENOMEM
+When changing mount propagation to
+.BR MS_SHARED
+a new peer group id needs to be allocated for all mounts without a peer group
+id set.
+Allocation of this peer group id has failed.
+.TP
+.B ENOSPC
+When changing mount propagation to
+.BR MS_SHARED
+a new peer group id needs to be allocated for all mounts without a peer group
+id set.
+Allocation of this peer group id can fail.
+Note that technically further error codes are possible that are specific to the
+id allocation implementation used.
+.TP
+.B EPERM
+One of the mounts had at least one of
+.BR MOUNT_ATTR_NOATIME,
+.BR MOUNT_ATTR_NODEV,
+.BR MOUNT_ATTR_NODIRATIME,
+.BR MOUNT_ATTR_NOEXEC,
+.BR MOUNT_ATTR_NOSUID,
+or
+.BR MOUNT_ATTR_RDONLY
+set and the flag is locked.
+Mount attributes become locked on a mount if:
+.RS
+.IP \(bu 2
+a new mount or mount tree is created causing mount propagation across user
+namespaces.
+The kernel will lock the aforementioned flags to protect these sensitive
+properties from being altered.
+.IP \(bu
+a new mount and user namespace pair is created.
+This happens for example when specifying
+.BR CLONE_NEWUSER | CLONE_NEWNS
+in
+.BR unshare (2),
+.BR clone (2),
+or
+.BR clone3 (2) .
+The aformentioned flags become locked to protect user namespaces from altering
+sensitive mount properties.
+.RE
+.TP
+.B EPERM
+A valid file descriptor value was specified in
+.I userns_fd
+but the file descriptor refers to the initial user namespace.
+.TP
+.B EPERM
+An already idmapped mount was supposed to be idmapped.
+.TP
+.B EPERM
+The caller does not have
+.I CAP_SYS_ADMIN
+in the initial user namespace.
+.SH VERSIONS
+.BR mount_setattr (2)
+first appeared in Linux 5.12.
+.\" commit 7d6beb71da3cc033649d641e1e608713b8220290
+.\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
+.\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
+.SH CONFORMING TO
+.BR mount_setattr (2)
+is Linux specific.
+.SH NOTES
+.SS Extensibility
+In order to allow for future extensibility,
+.BR mount_setattr (2)
+along with other system calls such as
+.BR openat2 (2)
+and
+.BR clone3 (2)
+requires the user-space application to specify the size of the
+.I mount_attr
+structure that it is passing.
+By providing this information, it is possible for
+.BR mount_setattr (2)
+to provide both forwards- and backwards-compatibility, with
+.I size
+acting as an implicit version number.
+(Because new extension fields will always
+be appended, the structure size will always increase.)
+This extensibility design is very similar to other system calls such as
+.BR perf_setattr (2),
+.BR perf_event_open (2),
+.BR clone3 (2)
+and
+.BR openat2 (2) .
+.PP
+Let
+.I usize
+be the size of the structure as specified by the user-space application,
+and let
+.I ksize
+be the size of the structure which the kernel supports,
+then there are three cases to consider:
+.RS
+.IP \(bu 2
+If
+.IR ksize
+equals
+.IR usize ,
+then there is no version mismatch and
+.I attr
+can be used verbatim.
+.IP \(bu
+If
+.IR ksize
+is larger than
+.IR usize ,
+then there are some extension fields that the kernel supports which the
+user-space application is unaware of.
+Because a zero value in any added extension field signifies a no-op,
+the kernel treats all of the extension fields not provided by the user-space
+application as having zero values.
+This provides backwards-compatibility.
+.IP \(bu
+If
+.IR ksize
+is smaller than
+.IR usize ,
+then there are some extension fields which the user-space application is aware
+of but which the kernel does not support.
+Because any extension field must have its zero values signify a no-op,
+the kernel can safely ignore the unsupported extension fields if they are
+all zero.
+If any unsupported extension fields are non-zero, then \-1 is returned and
+.I errno
+is set to
+.BR E2BIG .
+This provides forwards-compatibility.
+.RE
+.PP
+Because the definition of
+.I struct mount_attr
+may change in the future
+(with new fields being added when system headers are updated),
+user-space applications should zero-fill
+.I struct mount_attr
+to ensure that recompiling the program with new headers will not result in
+spurious errors at runtime.
+The simplest way is to use a designated initializer:
+.PP
+.in +4n
+.EX
+struct mount_attr attr = {
+    .attr_set = MOUNT_ATTR_RDONLY,
+    .attr_clr = MOUNT_ATTR_NODEV
+};
+.EE
+.in
+.PP
+or explicitly using
+.BR memset (3)
+or similar functions:
+.PP
+.in +4n
+.EX
+struct mount_attr attr;
+memset(&attr, 0, sizeof(attr));
+attr.attr_set = MOUNT_ATTR_RDONLY;
+attr.attr_clr = MOUNT_ATTR_NODEV;
+.EE
+.in
+.PP
+A user-space application that wishes to determine which extensions the running
+kernel supports can do so by conducting a binary search on
+.IR size
+with a structure which has every byte nonzero
+(to find the largest value which doesn't produce an error of
+.BR E2BIG ) .
+.SH EXAMPLES
+.EX
+/*
+ * This program allows the caller to create a new detached mount and set
+ * various properties on it.
+ */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <getopt.h>
+#include <linux/mount.h>
+#include <linux/types.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+static inline int mount_setattr(int dfd,
+                                const char *path,
+                                unsigned int flags,
+                                struct mount_attr *attr,
+                                size_t size)
+{
+    return syscall(SYS_mount_setattr, dfd, path,
+                   flags, attr, size);
+}
+
+static inline int open_tree(int dfd, const char *filename,
+                            unsigned int flags)
+{
+    return syscall(SYS_open_tree, dfd, filename, flags);
+}
+
+static inline int move_mount(int from_dfd,
+                             const char *from_pathname,
+                             int to_dfd,
+                             const char *to_pathname,
+                             unsigned int flags)
+{
+    return syscall(SYS_move_mount, from_dfd,
+                   from_pathname, to_dfd, to_pathname, flags);
+}
+
+static const struct option longopts[] = {
+    {"map-mount",       required_argument,  NULL,  'a'},
+    {"recursive",       no_argument,        NULL,  'b'},
+    {"read-only",       no_argument,        NULL,  'c'},
+    {"block-setid",     no_argument,        NULL,  'd'},
+    {"block-devices",   no_argument,        NULL,  'e'},
+    {"block-exec",      no_argument,        NULL,  'f'},
+    {"no-access-time",  no_argument,        NULL,  'g'},
+    { NULL,             0,                  NULL,   0 },
+};
+
+#define exit_log(format, ...)                   \\
+    ({                                          \\
+        fprintf(stderr, format, ##__VA_ARGS__); \\
+        exit(EXIT_FAILURE);                     \\
+    })
+
+int main(int argc, char *argv[])
+{
+    int fd_userns = \-EBADF, index = 0;
+    bool recursive = false;
+    struct mount_attr *attr = &(struct mount_attr){};
+    const char *source, *target;
+    int fd_tree, new_argc, ret;
+    char *const *new_argv;
+
+    while ((ret = getopt_long_only(argc, argv, "",
+                                  longopts, &index)) != \-1) {
+        switch (ret) {
+        case 'a':
+            fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
+            if (fd_userns == \-1)
+                exit_log("%m - Failed top open %s\en", optarg);
+            break;
+        case 'b':
+            recursive = true;
+            break;
+        case 'c':
+            attr->attr_set |= MOUNT_ATTR_RDONLY;
+            break;
+        case 'd':
+            attr->attr_set |= MOUNT_ATTR_NOSUID;
+            break;
+        case 'e':
+            attr->attr_set |= MOUNT_ATTR_NODEV;
+            break;
+        case 'f':
+            attr->attr_set |= MOUNT_ATTR_NOEXEC;
+            break;
+        case 'g':
+            attr->attr_set |= MOUNT_ATTR_NOATIME;
+            attr->attr_clr |= MOUNT_ATTR__ATIME;
+            break;
+        default:
+            exit_log("Invalid argument specified");
+        }
+    }
+
+    new_argv = &argv[optind];
+    new_argc = argc \- optind;
+    if (new_argc < 2)
+        exit_log("Missing source or target mountpoint\en");
+    source = new_argv[0];
+    target = new_argv[1];
+
+    fd_tree = open_tree(\-EBADF, source,
+                        OPEN_TREE_CLONE |
+                        OPEN_TREE_CLOEXEC |
+                        AT_EMPTY_PATH |
+                        (recursive ? AT_RECURSIVE : 0));
+    if (fd_tree == \-1)
+        exit_log("%m - Failed to open %s\en", source);
+
+    if (fd_userns >= 0) {
+        attr->attr_set  |= MOUNT_ATTR_IDMAP;
+        attr->userns_fd = fd_userns;
+    }
+    ret = mount_setattr(fd_tree, "",
+                        AT_EMPTY_PATH |
+                        (recursive ? AT_RECURSIVE : 0),
+                        attr, sizeof(struct mount_attr));
+    if (ret == \-1)
+        exit_log("%m - Failed to change mount attributes\en");
+    close(fd_userns);
+
+    ret = move_mount(fd_tree, "", \-EBADF, target,
+                     MOVE_MOUNT_F_EMPTY_PATH);
+    if (ret == \-1)
+        exit_log("%m - Failed to attach mount to %s\en", target);
+    close(fd_tree);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
+.fi
+.SH SEE ALSO
+.BR capabilities (7),
+.BR clone (2),
+.BR clone3 (2),
+.BR ext4 (5),
+.BR mount (2),
+.BR mount_namespaces (7),
+.BR newuidmap (1),
+.BR newgidmap (1),
+.BR proc (5),
+.BR unshare (2),
+.BR user_namespaces (7),
+.BR xattr (7),
+.BR xfs (5)
-- 
2.32.0

Re: [PATCH 20/23] mount_setattr.2: New manual page documenting the mount_setattr() system call

[Michael Kerrisk (man-pages)]

Hello Christian and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> From: Christian Brauner <christian.brauner@ubuntu.com>
> 
> Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
> Cc: Christoph Hellwig <hch@infradead.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied. Ive also applied Alex's follow-up edits,
and done a substantial amount of (minor) editing of my own.

@Christian
This really is a very nice manual page. But, I still have a number 
of questions. I will post these in a separate mail. 

Thanks,

Michael

> ---
>  man2/mount_setattr.2 | 1002 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 1002 insertions(+)
>  create mode 100644 man2/mount_setattr.2
> 
> diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
> new file mode 100644
> index 000000000..16881d90d
> --- /dev/null
> +++ b/man2/mount_setattr.2
> @@ -0,0 +1,1002 @@
> +.\" Copyright (c) 2021 by Christian Brauner <christian.brauner@ubuntu.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.TH MOUNT_SETATTR 2 2021-03-22 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +mount_setattr \- change mount properties of a mount or mount tree
> +.SH SYNOPSIS
> +.nf
> +
> +.PP
> +.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> +.BR "#include <linux/mount.h>" " /* Definition of struct mount_attr and MOUNT_ATTR_* constants */"
> +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
> +.B #include <unistd.h>
> +.PP
> +.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path \
> +", unsigned int " flags \
> +", struct mount_attr *" attr ", size_t " size );
> +.fi
> +.PP
> +.IR Note :
> +glibc provides no wrapper for
> +.BR mount_setattr (),
> +necessitating the use of
> +.BR syscall (2).
> +.SH DESCRIPTION
> +The
> +.BR mount_setattr (2)
> +system call changes the mount properties of a mount or entire mount tree.
> +If
> +.I path
> +is a relative pathname,
> +then it is interpreted relative to the directory referred to by the file
> +descriptor
> +.IR dfd .
> +If
> +.I dfd
> +is the special value
> +.B AT_FDCWD
> +then
> +.I path
> +is taken to be relative to the current working directory of the calling process.
> +If
> +.I path
> +is the empty string and
> +.BR AT_EMPTY_PATH
> +is specified in
> +.I flags
> +then the mount properties of the mount identified by
> +.I dfd
> +are changed.
> +.PP
> +The
> +.BR mount_setattr (2)
> +system call uses an extensible structure
> +.IR ( "struct mount_attr" )
> +to allow for future extensions.
> +Any non-flag extensions to
> +.BR mount_setattr (2)
> +will be implemented as new fields appended to the above structure,
> +with a zero value in a new field resulting in the kernel behaving
> +as though that extension field was not present.
> +Therefore,
> +the caller
> +.I must
> +zero-fill this structure on initialization.
> +Please see the "Extensibility" section under
> +.B NOTES
> +for more details.
> +.PP
> +The
> +.I size
> +argument should usually be specified as
> +.IR "sizeof(struct mount_attr)" .
> +However,
> +if the caller does not intend to make use of features that got
> +introduced after the initial version of
> +.I struct mount_attr
> +they are free to pass the size of the initial struct together with the larger
> +struct.
> +This allows the kernel to not copy later parts of the struct that aren't used
> +anyway.
> +With each extension that changes the size of
> +.I struct mount_attr
> +the kernel will expose a define of the form
> +.BR MOUNT_ATTR_SIZE_VER<number> .
> +For example the macro for the size of the initial version of
> +.I struct mount_attr
> +is
> +.BR MOUNT_ATTR_SIZE_VER0 .
> +.PP
> +The
> +.I flags
> +argument can be used to alter the path resolution behavior.
> +The supported values are:
> +.TP
> +.B AT_EMPTY_PATH
> +If
> +.I path
> +is the empty string change the mount properties on
> +.I dfd
> +itself.
> +.TP
> +.B AT_RECURSIVE
> +Change the mount properties of the entire mount tree.
> +.TP
> +.B AT_SYMLINK_NOFOLLOW
> +Don't follow trailing symlinks.
> +.TP
> +.B AT_NO_AUTOMOUNT
> +Don't trigger automounts.
> +.PP
> +The
> +.I attr
> +argument of
> +.BR mount_setattr (2)
> +is a structure of the following form:
> +.PP
> +.in +4n
> +.EX
> +struct mount_attr {
> +    __u64 attr_set;    /* Mount properties to set. */
> +    __u64 attr_clr;    /* Mount properties to clear. */
> +    __u64 propagation; /* Mount propagation type. */
> +    __u64 userns_fd;   /* User namespace file descriptor. */
> +};
> +.EE
> +.in
> +.PP
> +The
> +.I attr_set
> +and
> +.I attr_clr
> +members are used to specify the mount properties that are supposed to be set or
> +cleared for a mount or mount tree.
> +Flags set in
> +.I attr_set
> +enable a property on a mount or mount tree and flags set in
> +.I attr_clr
> +remove a property from a mount or mount tree.
> +.PP
> +When changing mount properties the kernel will first clear the flags specified
> +in the
> +.I attr_clr
> +field and then set the flags specified in the
> +.I attr_set
> +field:
> +.PP
> +.in +4n
> +.EX
> +struct mount_attr attr = {
> +    .attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV,
> +    .attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID,
> +};
> +unsigned int current_mnt_flags = mnt->mnt_flags;
> +
> +/*
> + * Clear all flags set in .attr_clr,
> + * clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV.
> + */
> +current_mnt_flags &= ~attr->attr_clr;
> +
> +/*
> + * Now set all flags set in .attr_set,
> + * applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID.
> + */
> +current_mnt_flags |= attr->attr_set;
> +
> +mnt->mnt_flags = current_mnt_flags;
> +.EE
> +.in
> +.PP
> +The effect of this change will be a mount or mount tree that is read-only,
> +blocks the execution of set-user-ID and set-group-ID binaries but does allow to
> +execute programs and access to devices nodes.
> +Multiple changes with the same set of flags requested
> +in
> +.I attr_clr
> +and
> +.I attr_set
> +are guaranteed to be idempotent after the changes have been applied.
> +.PP
> +The following mount attributes can be specified in the
> +.I attr_set
> +or
> +.I attr_clr
> +fields:
> +.TP
> +.B MOUNT_ATTR_RDONLY
> +If set in
> +.I attr_set
> +makes the mount read-only and if set in
> +.I attr_clr
> +removes the read-only setting if set on the mount.
> +.TP
> +.B MOUNT_ATTR_NOSUID
> +If set in
> +.I attr_set
> +makes the mount not honor set-user-ID and set-group-ID binaries,
> +and file capabilities when executing programs.
> +If set in
> +.I attr_clr
> +clears the set-user-ID, set-group-ID,
> +and file capability restriction if set on this mount.
> +.TP
> +.B MOUNT_ATTR_NODEV
> +If set in
> +.I attr_set
> +prevents access to devices on this mount and if set in
> +.I attr_clr
> +removes the device access restriction if set on this mount.
> +.TP
> +.BR MOUNT_ATTR_NOEXEC
> +If set in
> +.I attr_set
> +prevents executing programs on this mount and if set in
> +.I attr_clr
> +removes the restriction to execute programs on this mount.
> +.TP
> +.BR MOUNT_ATTR_NOSYMFOLLOW
> +If set in
> +.I attr_set
> +prevents following symlinks on this mount and if set in
> +.I attr_clr
> +removes the restriction to not follow symlinks on this mount.
> +.TP
> +.B MOUNT_ATTR_NODIRATIME
> +If set in
> +.I attr_set
> +prevents updating access time for directories on this mount and if set in
> +.I attr_clr
> +removes access time restriction for directories.
> +Note that
> +.BR MOUNT_ATTR_NODIRATIME
> +can be combined with other access time settings and is implied
> +by the noatime setting.
> +All other access time settings are mutually exclusive.
> +.TP
> +.BR MOUNT_ATTR__ATIME " - Changing access time settings
> +In the new mount api the access time values are an enum starting from 0.
> +Even though they are an enum in contrast to the other mount flags such as
> +.BR MOUNT_ATTR_NOEXEC
> +they are nonetheless passed in
> +.I attr_set
> +and
> +.I attr_clr
> +for consistency with
> +.BR fsmount (2)
> +which introduced this behavior.
> +.IP
> +Note,
> +since access times are an enum,
> +not a bitmap,
> +users wanting to transition to a different access time setting cannot simply
> +specify the access time in
> +.I attr_set
> +but must also set
> +.B MOUNT_ATTR__ATIME
> +in the
> +.I attr_clr
> +field.
> +The kernel will verify that
> +.BR MOUNT_ATTR__ATIME
> +isn't partially set in
> +.I attr_clr
> +and that
> +.I attr_set
> +doesn't have any access time bits set if
> +.BR MOUNT_ATTR__ATIME
> +isn't set in
> +.IR attr_clr .
> +.RS
> +.TP
> +.B MOUNT_ATTR_RELATIME
> +When a file is accessed via this mount,
> +update the file's last access time
> +(atime)
> +only if the current value of atime is less than or equal to the file's
> +last modification time (mtime) or last status change time (ctime).
> +.IP
> +To enable this access time setting on a mount or mount tree
> +.BR MOUNT_ATTR_RELATIME
> +must be set in
> +.I attr_set
> +and
> +.BR MOUNT_ATTR__ATIME
> +must be set in the
> +.I attr_clr
> +field.
> +.TP
> +.BR MOUNT_ATTR_NOATIME
> +Do not update access times for (all types of) files on this mount.
> +.IP
> +To enable this access time setting on a mount or mount tree
> +.BR MOUNT_ATTR_NOATIME
> +must be set in
> +.I attr_set
> +and
> +.BR MOUNT_ATTR__ATIME
> +must be set in the
> +.I attr_clr
> +field.
> +.TP
> +.BR MOUNT_ATTR_STRICTATIME
> +Always update the last access time (atime) when files are accessed on this
> +mount.
> +.IP
> +To enable this access time setting on a mount or mount tree
> +.BR MOUNT_ATTR_STRICTATIME
> +must be set in
> +.I attr_set
> +and
> +.BR MOUNT_ATTR__ATIME
> +must be set in the
> +.I attr_clr
> +field.
> +.RE
> +.TP
> +.BR MOUNT_ATTR_IDMAP
> +If set in
> +.I attr_set
> +creates an idmapped mount.
> +Since it is not supported to change the idmapping of a mount after it has been
> +idmapped,
> +it is invalid to specify
> +.B MOUNT_ATTR_IDMAP
> +in
> +.IR attr_clr .
> +The idmapping is taken from the user namespace specified in
> +.I userns_fd
> +and attached to the mount.
> +More details can be found in subsequent paragraphs.
> +.IP
> +Creating an idmapped mount allows to change the ownership of all files located
> +under a mount.
> +Thus, idmapped mounts make it possible to change ownership in a temporary and
> +localized way.
> +It is a localized change because ownership changes are restricted to a specific
> +mount.
> +All other users and locations where the filesystem is exposed are unaffected.
> +And it is a temporary change because ownership changes are tied to the lifetime
> +of the mount.
> +.IP
> +Whenever callers interact with the filesystem through an idmapped mount the
> +idmapping of the mount will be applied to user and group IDs associated with
> +filesystem objects.
> +This encompasses the user and group IDs associated with inodes and also
> +the following
> +.BR xattr (7)
> +keys:
> +.RS
> +.RS
> +.IP \(bu 2
> +.IR security.capability
> +whenever filesystem
> +.BR capabilities (7)
> +are stored or returned in the
> +.I VFS_CAP_REVISION_3
> +format which stores a rootid alongside the capabilities.
> +.IP \(bu 2
> +.I system.posix_acl_access
> +and
> +.I system.posix_acl_default
> +whenever user IDs or group IDs are stored in
> +.BR ACL_USER
> +and
> +.BR ACL_GROUP
> +entries.
> +.RE
> +.RE
> +.IP
> +The following conditions must be met in order to create an idmapped mount:
> +.RS
> +.RS
> +.IP \(bu 2
> +The caller must have
> +.I CAP_SYS_ADMIN
> +in the initial user namespace.
> +.IP \(bu 2
> +The filesystem must be mounted in the initial user namespace.
> +.IP \(bu
> +The underlying filesystem must support idmapped mounts.
> +Currently
> +.BR xfs (5),
> +.BR ext4 (5)
> +and
> +.BR fat
> +filesystems support idmapped mounts with more filesystems being actively worked
> +on.
> +.IP \(bu
> +The mount must not already be idmapped.
> +This also implies that the idmapping of a mount cannot be altered.
> +.IP \(bu
> +The mount must be a detached/anonymous mount,
> +i.e.,
> +it must have been created by calling
> +.BR open_tree (2)
> +with the
> +.I OPEN_TREE_CLONE
> +flag and it must not already have been visible in the filesystem.
> +.RE
> +.RE
> +.IP
> +Idmappings can be created for user IDs, group IDs, and project IDs.
> +An idmapping is essentially a mapping of a range of user or group IDs into
> +another or the same range of user or group IDs.
> +Idmappings are usually written as three numbers either separated by white space
> +or a full stop.
> +The first two numbers specify the starting user or group ID in each of the two
> +user namespaces.
> +The third number specifies the range of the idmapping.
> +For example, a mapping for user IDs such as 1000:1001:1 would indicate that
> +user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its
> +ancestor user namespace.
> +Since the map range is 1 only user ID 1000 is mapped.
> +It is possible to specify up to 340 idmappings for each idmapping type.
> +If any user IDs or group IDs are not mapped all files owned by that unmapped
> +user or group ID will appear as being owned by the overflow user ID or overflow
> +group ID respectively.
> +Further details and instructions for setting up idmappings can be found in the
> +.BR user_namespaces (7)
> +man page.
> +.IP
> +In the common case the user namespace passed in
> +.I userns_fd
> +together with
> +.BR MOUNT_ATTR_IDMAP
> +in
> +.I attr_set
> +to create an idmapped mount will be the user namespace of a container.
> +In other scenarios it will be a dedicated user namespace associated with a
> +user's login session as is the case for portable home directories in
> +.BR systemd-homed.service (8) ).
> +It is also perfectly fine to create a dedicated user namespace for the sake of
> +idmapping a mount.
> +.IP
> +Idmapped mounts can be useful in the following and a variety of other
> +scenarios:
> +.RS
> +.RS
> +.IP \(bu 2
> +sharing files between multiple users or multiple machines especially in
> +complex scenarios.
> +For example,
> +idmapped mounts are used to implement portable home directories in
> +.BR systemd-homed.service (8)
> +where they allow users to move their home directory to an external storage
> +device and use it on multiple computers where they are assigned different user IDs
> +and group IDs.
> +This effectively makes it possible to assign random user IDs and group IDs at login time.
> +.IP \(bu
> +sharing files from the host with unprivileged containers.
> +This allows user to avoid having to change ownership permanently through
> +.BR chown (2) .
> +.IP \(bu
> +idmapping a container's root filesystem.
> +Users don't need to change ownership
> +permanently through
> +.BR chown (2) .
> +Especially for large root filesystems using
> +.BR chown (2)
> +can be prohibitively expensive.
> +.IP \(bu
> +sharing files between containers with non-overlapping
> +idmappings.
> +.IP \(bu
> +implementing discretionary access (DAC) permission checking for fileystems
> +lacking a concept of ownership.
> +.IP \(bu
> +efficiently change ownership on a per-mount basis.
> +In contrast to
> +.BR chown (2)
> +changing ownership of large sets of files is instantenous with idmapped mounts.
> +This is especially useful when ownership of an entire root filesystem of a
> +virtual machine or container is to be changed as we've mentioned above.
> +With idmapped mounts a single
> +.BR mount_setattr (2)
> +system call will be sufficient to change the ownership of all files.
> +.IP \(bu
> +taking the current ownership into account.
> +Idmappings specify precisely what a user or group ID is supposed to be
> +mapped to.
> +This contrasts with the
> +.BR chown (2)
> +system call which cannot by itself take the current ownership of the files it
> +changes into account.
> +It simply changes the ownership to the specified user ID and group ID.
> +.IP \(bu
> +locally and temporarily restricted ownership changes.
> +Idmapped mounts allow to change ownership locally,
> +restricting it to specific mounts,
> +and temporarily as the ownership changes only apply as long as the mount exists.
> +In contrast,
> +changing ownership via the
> +.BR chown (2)
> +system call changes the ownership globally and permanently.
> +.RE
> +.RE
> +.PP
> +The
> +.I propagation
> +field is used to specify the propagation type of the mount or mount tree.
> +Mount propagation options are mutually exclusive,
> +i.e.,
> +the propagation values behave like an enum.
> +The supported mount propagation settings are:
> +.TP
> +.B MS_PRIVATE
> +Turn all mounts into private mounts.
> +Mount and unmount events do not propagate into or out of this mount point.
> +.TP
> +.B MS_SHARED
> +Turn all mounts into shared mounts.
> +Mount points share events with members of a peer group.
> +Mount and unmount events immediately under this mount point
> +will propagate to the other mount points that are members of the peer group.
> +Propagation here means that the same mount or unmount will automatically occur
> +under all of the other mount points in the peer group.
> +Conversely,
> +mount and unmount events that take place under peer mount points will propagate
> +to this mount point.
> +.TP
> +.B MS_SLAVE
> +Turn all mounts into dependent mounts.
> +Mount and unmount events propagate into this mount point from a shared peer
> +group.
> +Mount and unmount events under this mount point do not propagate to any peer.
> +.TP
> +.B MS_UNBINDABLE
> +This is like a private mount,
> +and in addition this mount can't be bind mounted.
> +Attempts to bind mount this mount will fail.
> +When a recursive bind mount is performed on a directory subtree,
> +any bind mounts within the subtree are automatically pruned
> +(i.e., not replicated)
> +when replicating that subtree to produce the target subtree.
> +.PP
> +.SH RETURN VALUE
> +On success,
> +.BR mount_setattr (2)
> +returns zero.
> +On error,
> +\-1 is returned and
> +.I errno
> +is set to indicate the cause of the error.
> +.SH ERRORS
> +.TP
> +.B EBADF
> +.I dfd
> +is not a valid file descriptor.
> +.TP
> +.B EBADF
> +.I userns_fd
> +is not a valid file descriptor.
> +.TP
> +.B EBUSY
> +The caller tried to change the mount to
> +.BR MOUNT_ATTR_RDONLY
> +but the mount still has files open for writing.
> +.TP
> +.B EINVAL
> +The path specified via the
> +.I dfd
> +and
> +.I path
> +arguments to
> +.BR mount_setattr (2)
> +isn't a mountpoint.
> +.TP
> +.B EINVAL
> +An unsupported value was set in
> +.I flags.
> +.TP
> +.B EINVAL
> +An unsupported value was specified in the
> +.I attr_set
> +field of
> +.IR mount_attr .
> +.TP
> +.B EINVAL
> +An unsupported value was specified in the
> +.I attr_clr
> +field of
> +.IR mount_attr .
> +.TP
> +.B EINVAL
> +An unsupported value was specified in the
> +.I propagation
> +field of
> +.IR mount_attr .
> +.TP
> +.B EINVAL
> +More than one of
> +.BR MS_SHARED,
> +.BR MS_SLAVE,
> +.BR MS_PRIVATE,
> +or
> +.BR MS_UNBINDABLE
> +was set in
> +.I propagation
> +field of
> +.IR mount_attr .
> +.TP
> +.B EINVAL
> +An access time setting was specified in the
> +.I attr_set
> +field without
> +.BR MOUNT_ATTR__ATIME
> +being set in the
> +.I attr_clr
> +field.
> +.TP
> +.B EINVAL
> +.BR MOUNT_ATTR_IDMAP
> +was specified in
> +.IR attr_clr .
> +.TP
> +.B EINVAL
> +A file descriptor value was specified in
> +.I userns_fd
> +which exceeds
> +.BR INT_MAX .
> +.TP
> +.B EINVAL
> +A valid file descriptor value was specified in
> +.I userns_fd
> +but the file descriptor wasn't a namespace file descriptor or did not refer to
> +a user namespace.
> +.TP
> +.B EINVAL
> +The underlying filesystem does not support idmapped mounts.
> +.TP
> +.B EINVAL
> +The mount to idmap is not a detached/anonymous mount,
> +i.e.,
> +the mount is already visible in the filesystem.
> +.TP
> +.B EINVAL
> +A partial access time setting was specified in
> +.I attr_clr
> +instead of
> +.BR MOUNT_ATTR__ATIME
> +being set.
> +.TP
> +.B EINVAL
> +The mount is located outside the caller's mount namespace.
> +.TP
> +.B EINVAL
> +The underlying filesystem is mounted in a user namespace.
> +.TP
> +.B ENOENT
> +A pathname was empty or had a nonexistent component.
> +.TP
> +.B ENOMEM
> +When changing mount propagation to
> +.BR MS_SHARED
> +a new peer group id needs to be allocated for all mounts without a peer group
> +id set.
> +Allocation of this peer group id has failed.
> +.TP
> +.B ENOSPC
> +When changing mount propagation to
> +.BR MS_SHARED
> +a new peer group id needs to be allocated for all mounts without a peer group
> +id set.
> +Allocation of this peer group id can fail.
> +Note that technically further error codes are possible that are specific to the
> +id allocation implementation used.
> +.TP
> +.B EPERM
> +One of the mounts had at least one of
> +.BR MOUNT_ATTR_NOATIME,
> +.BR MOUNT_ATTR_NODEV,
> +.BR MOUNT_ATTR_NODIRATIME,
> +.BR MOUNT_ATTR_NOEXEC,
> +.BR MOUNT_ATTR_NOSUID,
> +or
> +.BR MOUNT_ATTR_RDONLY
> +set and the flag is locked.
> +Mount attributes become locked on a mount if:
> +.RS
> +.IP \(bu 2
> +a new mount or mount tree is created causing mount propagation across user
> +namespaces.
> +The kernel will lock the aforementioned flags to protect these sensitive
> +properties from being altered.
> +.IP \(bu
> +a new mount and user namespace pair is created.
> +This happens for example when specifying
> +.BR CLONE_NEWUSER | CLONE_NEWNS
> +in
> +.BR unshare (2),
> +.BR clone (2),
> +or
> +.BR clone3 (2) .
> +The aformentioned flags become locked to protect user namespaces from altering
> +sensitive mount properties.
> +.RE
> +.TP
> +.B EPERM
> +A valid file descriptor value was specified in
> +.I userns_fd
> +but the file descriptor refers to the initial user namespace.
> +.TP
> +.B EPERM
> +An already idmapped mount was supposed to be idmapped.
> +.TP
> +.B EPERM
> +The caller does not have
> +.I CAP_SYS_ADMIN
> +in the initial user namespace.
> +.SH VERSIONS
> +.BR mount_setattr (2)
> +first appeared in Linux 5.12.
> +.\" commit 7d6beb71da3cc033649d641e1e608713b8220290
> +.\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
> +.\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
> +.SH CONFORMING TO
> +.BR mount_setattr (2)
> +is Linux specific.
> +.SH NOTES
> +.SS Extensibility
> +In order to allow for future extensibility,
> +.BR mount_setattr (2)
> +along with other system calls such as
> +.BR openat2 (2)
> +and
> +.BR clone3 (2)
> +requires the user-space application to specify the size of the
> +.I mount_attr
> +structure that it is passing.
> +By providing this information, it is possible for
> +.BR mount_setattr (2)
> +to provide both forwards- and backwards-compatibility, with
> +.I size
> +acting as an implicit version number.
> +(Because new extension fields will always
> +be appended, the structure size will always increase.)
> +This extensibility design is very similar to other system calls such as
> +.BR perf_setattr (2),
> +.BR perf_event_open (2),
> +.BR clone3 (2)
> +and
> +.BR openat2 (2) .
> +.PP
> +Let
> +.I usize
> +be the size of the structure as specified by the user-space application,
> +and let
> +.I ksize
> +be the size of the structure which the kernel supports,
> +then there are three cases to consider:
> +.RS
> +.IP \(bu 2
> +If
> +.IR ksize
> +equals
> +.IR usize ,
> +then there is no version mismatch and
> +.I attr
> +can be used verbatim.
> +.IP \(bu
> +If
> +.IR ksize
> +is larger than
> +.IR usize ,
> +then there are some extension fields that the kernel supports which the
> +user-space application is unaware of.
> +Because a zero value in any added extension field signifies a no-op,
> +the kernel treats all of the extension fields not provided by the user-space
> +application as having zero values.
> +This provides backwards-compatibility.
> +.IP \(bu
> +If
> +.IR ksize
> +is smaller than
> +.IR usize ,
> +then there are some extension fields which the user-space application is aware
> +of but which the kernel does not support.
> +Because any extension field must have its zero values signify a no-op,
> +the kernel can safely ignore the unsupported extension fields if they are
> +all zero.
> +If any unsupported extension fields are non-zero, then \-1 is returned and
> +.I errno
> +is set to
> +.BR E2BIG .
> +This provides forwards-compatibility.
> +.RE
> +.PP
> +Because the definition of
> +.I struct mount_attr
> +may change in the future
> +(with new fields being added when system headers are updated),
> +user-space applications should zero-fill
> +.I struct mount_attr
> +to ensure that recompiling the program with new headers will not result in
> +spurious errors at runtime.
> +The simplest way is to use a designated initializer:
> +.PP
> +.in +4n
> +.EX
> +struct mount_attr attr = {
> +    .attr_set = MOUNT_ATTR_RDONLY,
> +    .attr_clr = MOUNT_ATTR_NODEV
> +};
> +.EE
> +.in
> +.PP
> +or explicitly using
> +.BR memset (3)
> +or similar functions:
> +.PP
> +.in +4n
> +.EX
> +struct mount_attr attr;
> +memset(&attr, 0, sizeof(attr));
> +attr.attr_set = MOUNT_ATTR_RDONLY;
> +attr.attr_clr = MOUNT_ATTR_NODEV;
> +.EE
> +.in
> +.PP
> +A user-space application that wishes to determine which extensions the running
> +kernel supports can do so by conducting a binary search on
> +.IR size
> +with a structure which has every byte nonzero
> +(to find the largest value which doesn't produce an error of
> +.BR E2BIG ) .
> +.SH EXAMPLES
> +.EX
> +/*
> + * This program allows the caller to create a new detached mount and set
> + * various properties on it.
> + */
> +#define _GNU_SOURCE
> +#include <errno.h>
> +#include <fcntl.h>
> +#include <getopt.h>
> +#include <linux/mount.h>
> +#include <linux/types.h>
> +#include <stdbool.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +
> +static inline int mount_setattr(int dfd,
> +                                const char *path,
> +                                unsigned int flags,
> +                                struct mount_attr *attr,
> +                                size_t size)
> +{
> +    return syscall(SYS_mount_setattr, dfd, path,
> +                   flags, attr, size);
> +}
> +
> +static inline int open_tree(int dfd, const char *filename,
> +                            unsigned int flags)
> +{
> +    return syscall(SYS_open_tree, dfd, filename, flags);
> +}
> +
> +static inline int move_mount(int from_dfd,
> +                             const char *from_pathname,
> +                             int to_dfd,
> +                             const char *to_pathname,
> +                             unsigned int flags)
> +{
> +    return syscall(SYS_move_mount, from_dfd,
> +                   from_pathname, to_dfd, to_pathname, flags);
> +}
> +
> +static const struct option longopts[] = {
> +    {"map-mount",       required_argument,  NULL,  'a'},
> +    {"recursive",       no_argument,        NULL,  'b'},
> +    {"read-only",       no_argument,        NULL,  'c'},
> +    {"block-setid",     no_argument,        NULL,  'd'},
> +    {"block-devices",   no_argument,        NULL,  'e'},
> +    {"block-exec",      no_argument,        NULL,  'f'},
> +    {"no-access-time",  no_argument,        NULL,  'g'},
> +    { NULL,             0,                  NULL,   0 },
> +};
> +
> +#define exit_log(format, ...)                   \\
> +    ({                                          \\
> +        fprintf(stderr, format, ##__VA_ARGS__); \\
> +        exit(EXIT_FAILURE);                     \\
> +    })
> +
> +int main(int argc, char *argv[])
> +{
> +    int fd_userns = \-EBADF, index = 0;
> +    bool recursive = false;
> +    struct mount_attr *attr = &(struct mount_attr){};
> +    const char *source, *target;
> +    int fd_tree, new_argc, ret;
> +    char *const *new_argv;
> +
> +    while ((ret = getopt_long_only(argc, argv, "",
> +                                  longopts, &index)) != \-1) {
> +        switch (ret) {
> +        case 'a':
> +            fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
> +            if (fd_userns == \-1)
> +                exit_log("%m - Failed top open %s\en", optarg);
> +            break;
> +        case 'b':
> +            recursive = true;
> +            break;
> +        case 'c':
> +            attr->attr_set |= MOUNT_ATTR_RDONLY;
> +            break;
> +        case 'd':
> +            attr->attr_set |= MOUNT_ATTR_NOSUID;
> +            break;
> +        case 'e':
> +            attr->attr_set |= MOUNT_ATTR_NODEV;
> +            break;
> +        case 'f':
> +            attr->attr_set |= MOUNT_ATTR_NOEXEC;
> +            break;
> +        case 'g':
> +            attr->attr_set |= MOUNT_ATTR_NOATIME;
> +            attr->attr_clr |= MOUNT_ATTR__ATIME;
> +            break;
> +        default:
> +            exit_log("Invalid argument specified");
> +        }
> +    }
> +
> +    new_argv = &argv[optind];
> +    new_argc = argc \- optind;
> +    if (new_argc < 2)
> +        exit_log("Missing source or target mountpoint\en");
> +    source = new_argv[0];
> +    target = new_argv[1];
> +
> +    fd_tree = open_tree(\-EBADF, source,
> +                        OPEN_TREE_CLONE |
> +                        OPEN_TREE_CLOEXEC |
> +                        AT_EMPTY_PATH |
> +                        (recursive ? AT_RECURSIVE : 0));
> +    if (fd_tree == \-1)
> +        exit_log("%m - Failed to open %s\en", source);
> +
> +    if (fd_userns >= 0) {
> +        attr->attr_set  |= MOUNT_ATTR_IDMAP;
> +        attr->userns_fd = fd_userns;
> +    }
> +    ret = mount_setattr(fd_tree, "",
> +                        AT_EMPTY_PATH |
> +                        (recursive ? AT_RECURSIVE : 0),
> +                        attr, sizeof(struct mount_attr));
> +    if (ret == \-1)
> +        exit_log("%m - Failed to change mount attributes\en");
> +    close(fd_userns);
> +
> +    ret = move_mount(fd_tree, "", \-EBADF, target,
> +                     MOVE_MOUNT_F_EMPTY_PATH);
> +    if (ret == \-1)
> +        exit_log("%m - Failed to attach mount to %s\en", target);
> +    close(fd_tree);
> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
> +.fi
> +.SH SEE ALSO
> +.BR capabilities (7),
> +.BR clone (2),
> +.BR clone3 (2),
> +.BR ext4 (5),
> +.BR mount (2),
> +.BR mount_namespaces (7),
> +.BR newuidmap (1),
> +.BR newgidmap (1),
> +.BR proc (5),
> +.BR unshare (2),
> +.BR user_namespaces (7),
> +.BR xattr (7),
> +.BR xfs (5)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 21/23] mount_setattr.2: Minor tweaks to Chirstian's patch

[Alejandro Colomar]

- Fix SYNOPSIS to fit in 78 columns

  Also, we don't show when an include is included for a specific type,
  unless that header is included _only_ for the type,
  or there might be confusion (e.g., termios).
  Instead, that type should be documented in system_data_types(7),
  with a link page mount_attr-struct(3).

- Fix references to mount_setattr().  See man-pages(7):

       Any reference to the subject of the current manual page should be writ‐
       ten with the name in bold followed by a pair of  parentheses  in  Roman
       (normal)  font.   For  example, in the fcntl(2) man page, references to
       the subject of the page would be written as:  fcntl().   The  preferred
       way to write this in the source file is:

           .BR fcntl ()

- Fix line breaks according to semantic newline rules (and add some commas)
- Fix wrong usage of .IR when .RI should have been used
- Fix formatting of variable part in FOO<number>:
  - Make italic the variable part (as groff_man(7) recommends)
  - Remove <>
  - Use syntax recommended by G. Branden Robinson (groff)

- Fix unnecessary uses of .BR or .IR when .B or .I would suffice
- Fix formatting of punctuation

  In some cases, it was in italics or bold, and it should always be in roman.

- Use uppercase to begin text, even in bullet points, since those were
  multi-sentence.

- Simplify usage of .RS/.RE in combination with .IP
- s/fat/FAT/ as fs(7) does
- Slightly reword some sentences for consistency
- Use Linux-specific for consistency with other pages (in VERSIONS)
- EXAMPLES: Place the return type in a line of its own (as in other pages)
- Fix alignment of code
- Replace unnecessary use of the GNU extension ({}) by do {} while (0)

  In that case, there was no return value (moreover, it's a noreturn).

- Break complex declaration lines into a line for each variable

  The variables were being initialized, some to non-zero values,
  so for clarity, a line for each one seems more appropriate.

- Add const to pointers when possible
- s/\\/\e/
- Remove unmatched groff commands

Cc: Christian Brauner <brauner@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/mount_setattr.2 | 446 ++++++++++++++++++++++---------------------
 1 file changed, 225 insertions(+), 221 deletions(-)

diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
index 16881d90d..70ab4592e 100644
--- a/man2/mount_setattr.2
+++ b/man2/mount_setattr.2
@@ -30,13 +30,13 @@ mount_setattr \- change mount properties of a mount or mount tree
 
 .PP
 .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
-.BR "#include <linux/mount.h>" " /* Definition of struct mount_attr and MOUNT_ATTR_* constants */"
+.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path \
-", unsigned int " flags \
-", struct mount_attr *" attr ", size_t " size );
+.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path ,
+.BI "            unsigned int " flags ", struct mount_attr *" attr \
+", size_t " size );
 .fi
 .PP
 .IR Note :
@@ -46,13 +46,13 @@ necessitating the use of
 .BR syscall (2).
 .SH DESCRIPTION
 The
-.BR mount_setattr (2)
+.BR mount_setattr ()
 system call changes the mount properties of a mount or entire mount tree.
 If
 .I path
 is a relative pathname,
-then it is interpreted relative to the directory referred to by the file
-descriptor
+then it is interpreted relative to
+the directory referred to by the file descriptor
 .IR dfd .
 If
 .I dfd
@@ -60,24 +60,25 @@ is the special value
 .B AT_FDCWD
 then
 .I path
-is taken to be relative to the current working directory of the calling process.
+is interpreted relative to
+the current working directory of the calling process.
 If
 .I path
 is the empty string and
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
 is specified in
-.I flags
+.IR flags ,
 then the mount properties of the mount identified by
 .I dfd
 are changed.
 .PP
 The
-.BR mount_setattr (2)
+.BR mount_setattr ()
 system call uses an extensible structure
-.IR ( "struct mount_attr" )
+.RI ( "struct mount_attr" )
 to allow for future extensions.
 Any non-flag extensions to
-.BR mount_setattr (2)
+.BR mount_setattr ()
 will be implemented as new fields appended to the above structure,
 with a zero value in a new field resulting in the kernel behaving
 as though that extension field was not present.
@@ -94,17 +95,18 @@ The
 argument should usually be specified as
 .IR "sizeof(struct mount_attr)" .
 However,
-if the caller does not intend to make use of features that got
-introduced after the initial version of
+if the caller does not intend to make use of features that
+got introduced after the initial version of
 .I struct mount_attr
-they are free to pass the size of the initial struct together with the larger
-struct.
-This allows the kernel to not copy later parts of the struct that aren't used
-anyway.
+they are free to pass
+the size of the initial struct together with the larger struct.
+This allows the kernel to not copy later parts of the struct
+that aren't used anyway.
 With each extension that changes the size of
 .I struct mount_attr
 the kernel will expose a define of the form
-.BR MOUNT_ATTR_SIZE_VER<number> .
+.BI MOUNT_ATTR_SIZE_VER number\c
+\&.
 For example the macro for the size of the initial version of
 .I struct mount_attr
 is
@@ -118,7 +120,8 @@ The supported values are:
 .B AT_EMPTY_PATH
 If
 .I path
-is the empty string change the mount properties on
+is the empty string,
+change the mount properties on
 .I dfd
 itself.
 .TP
@@ -134,7 +137,7 @@ Don't trigger automounts.
 The
 .I attr
 argument of
-.BR mount_setattr (2)
+.BR mount_setattr ()
 is a structure of the following form:
 .PP
 .in +4n
@@ -152,18 +155,21 @@ The
 .I attr_set
 and
 .I attr_clr
-members are used to specify the mount properties that are supposed to be set or
-cleared for a mount or mount tree.
+members are used to specify the mount properties that
+are supposed to be set or cleared for a mount or mount tree.
 Flags set in
 .I attr_set
-enable a property on a mount or mount tree and flags set in
+enable a property on a mount or mount tree,
+and flags set in
 .I attr_clr
 remove a property from a mount or mount tree.
 .PP
-When changing mount properties the kernel will first clear the flags specified
+When changing mount properties,
+the kernel will first clear the flags specified
 in the
 .I attr_clr
-field and then set the flags specified in the
+field,
+and then set the flags specified in the
 .I attr_set
 field:
 .PP
@@ -192,8 +198,8 @@ mnt->mnt_flags = current_mnt_flags;
 .in
 .PP
 The effect of this change will be a mount or mount tree that is read-only,
-blocks the execution of set-user-ID and set-group-ID binaries but does allow to
-execute programs and access to devices nodes.
+blocks the execution of set-user-ID and set-group-ID binaries,
+but does allow to execute programs and access to devices nodes.
 Multiple changes with the same set of flags requested
 in
 .I attr_clr
@@ -210,7 +216,8 @@ fields:
 .B MOUNT_ATTR_RDONLY
 If set in
 .I attr_set
-makes the mount read-only and if set in
+makes the mount read-only,
+and if set in
 .I attr_clr
 removes the read-only setting if set on the mount.
 .TP
@@ -227,46 +234,50 @@ and file capability restriction if set on this mount.
 .B MOUNT_ATTR_NODEV
 If set in
 .I attr_set
-prevents access to devices on this mount and if set in
+prevents access to devices on this mount,
+and if set in
 .I attr_clr
-removes the device access restriction if set on this mount.
+removes the restriction that prevented accesing devices on this mount.
 .TP
-.BR MOUNT_ATTR_NOEXEC
+.B MOUNT_ATTR_NOEXEC
 If set in
 .I attr_set
-prevents executing programs on this mount and if set in
+prevents executing programs on this mount,
+and if set in
 .I attr_clr
-removes the restriction to execute programs on this mount.
+removes the restriction that prevented executing programs on this mount.
 .TP
-.BR MOUNT_ATTR_NOSYMFOLLOW
+.B MOUNT_ATTR_NOSYMFOLLOW
 If set in
 .I attr_set
-prevents following symlinks on this mount and if set in
+prevents following symlinks on this mount,
+and if set in
 .I attr_clr
-removes the restriction to not follow symlinks on this mount.
+removes the restriction that prevented following symlinks on this mount.
 .TP
 .B MOUNT_ATTR_NODIRATIME
 If set in
 .I attr_set
-prevents updating access time for directories on this mount and if set in
+prevents updating access time for directories on this mount,
+and if set in
 .I attr_clr
-removes access time restriction for directories.
+removes the restriction that prevented updating access time for directories.
 Note that
-.BR MOUNT_ATTR_NODIRATIME
-can be combined with other access time settings and is implied
-by the noatime setting.
+.B MOUNT_ATTR_NODIRATIME
+can be combined with other access time settings
+and is implied by the noatime setting.
 All other access time settings are mutually exclusive.
 .TP
 .BR MOUNT_ATTR__ATIME " - Changing access time settings
-In the new mount api the access time values are an enum starting from 0.
+In the new mount API the access time values are an enum starting from 0.
 Even though they are an enum in contrast to the other mount flags such as
-.BR MOUNT_ATTR_NOEXEC
+.BR MOUNT_ATTR_NOEXEC ,
 they are nonetheless passed in
 .I attr_set
 and
 .I attr_clr
 for consistency with
-.BR fsmount (2)
+.BR fsmount (2),
 which introduced this behavior.
 .IP
 Note,
@@ -281,68 +292,67 @@ in the
 .I attr_clr
 field.
 The kernel will verify that
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 isn't partially set in
-.I attr_clr
+.IR attr_clr ,
 and that
 .I attr_set
 doesn't have any access time bits set if
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 isn't set in
 .IR attr_clr .
 .RS
 .TP
 .B MOUNT_ATTR_RELATIME
 When a file is accessed via this mount,
-update the file's last access time
-(atime)
-only if the current value of atime is less than or equal to the file's
-last modification time (mtime) or last status change time (ctime).
+update the file's last access time (atime)
+only if the current value of atime is less than or equal to
+the file's last modification time (mtime) or last status change time (ctime).
 .IP
-To enable this access time setting on a mount or mount tree
-.BR MOUNT_ATTR_RELATIME
+To enable this access time setting on a mount or mount tree,
+.B MOUNT_ATTR_RELATIME
 must be set in
 .I attr_set
 and
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 must be set in the
 .I attr_clr
 field.
 .TP
-.BR MOUNT_ATTR_NOATIME
+.B MOUNT_ATTR_NOATIME
 Do not update access times for (all types of) files on this mount.
 .IP
-To enable this access time setting on a mount or mount tree
-.BR MOUNT_ATTR_NOATIME
+To enable this access time setting on a mount or mount tree,
+.B MOUNT_ATTR_NOATIME
 must be set in
 .I attr_set
 and
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 must be set in the
 .I attr_clr
 field.
 .TP
-.BR MOUNT_ATTR_STRICTATIME
-Always update the last access time (atime) when files are accessed on this
-mount.
+.B MOUNT_ATTR_STRICTATIME
+Always update the last access time (atime)
+when files are accessed on this mount.
 .IP
-To enable this access time setting on a mount or mount tree
-.BR MOUNT_ATTR_STRICTATIME
+To enable this access time setting on a mount or mount tree,
+.B MOUNT_ATTR_STRICTATIME
 must be set in
 .I attr_set
 and
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 must be set in the
 .I attr_clr
 field.
 .RE
 .TP
-.BR MOUNT_ATTR_IDMAP
+.B MOUNT_ATTR_IDMAP
 If set in
 .I attr_set
 creates an idmapped mount.
-Since it is not supported to change the idmapping of a mount after it has been
-idmapped,
+Since it is not supported to
+change the idmapping of a mount after it has been idmapped,
 it is invalid to specify
 .B MOUNT_ATTR_IDMAP
 in
@@ -350,54 +360,51 @@ in
 The idmapping is taken from the user namespace specified in
 .I userns_fd
 and attached to the mount.
-More details can be found in subsequent paragraphs.
 .IP
-Creating an idmapped mount allows to change the ownership of all files located
-under a mount.
-Thus, idmapped mounts make it possible to change ownership in a temporary and
-localized way.
-It is a localized change because ownership changes are restricted to a specific
-mount.
+Creating an idmapped mount allows to
+change the ownership of all files located under a mount.
+Thus, idmapped mounts make it possible to
+change ownership in a temporary and localized way.
+It is a localized change because
+ownership changes are restricted to a specific mount.
 All other users and locations where the filesystem is exposed are unaffected.
-And it is a temporary change because ownership changes are tied to the lifetime
-of the mount.
+And it is a temporary change because
+ownership changes are tied to the lifetime of the mount.
 .IP
-Whenever callers interact with the filesystem through an idmapped mount the
-idmapping of the mount will be applied to user and group IDs associated with
-filesystem objects.
-This encompasses the user and group IDs associated with inodes and also
-the following
+Whenever callers interact with the filesystem through an idmapped mount,
+the idmapping of the mount will be applied to
+user and group IDs associated with filesystem objects.
+This encompasses the user and group IDs associated with inodes
+and also the following
 .BR xattr (7)
 keys:
 .RS
-.RS
-.IP \(bu 2
-.IR security.capability
+.IP \(bu
+.IR security.capability ,
 whenever filesystem
 .BR capabilities (7)
 are stored or returned in the
 .I VFS_CAP_REVISION_3
-format which stores a rootid alongside the capabilities.
-.IP \(bu 2
+format,
+which stores a rootid alongside the capabilities.
+.IP \(bu
 .I system.posix_acl_access
 and
-.I system.posix_acl_default
+.IR system.posix_acl_default ,
 whenever user IDs or group IDs are stored in
-.BR ACL_USER
-and
-.BR ACL_GROUP
+.B ACL_USER
+or
+.B ACL_GROUP
 entries.
 .RE
-.RE
 .IP
 The following conditions must be met in order to create an idmapped mount:
 .RS
-.RS
-.IP \(bu 2
+.IP \(bu
 The caller must have
 .I CAP_SYS_ADMIN
 in the initial user namespace.
-.IP \(bu 2
+.IP \(bu
 The filesystem must be mounted in the initial user namespace.
 .IP \(bu
 The underlying filesystem must support idmapped mounts.
@@ -405,9 +412,9 @@ Currently
 .BR xfs (5),
 .BR ext4 (5)
 and
-.BR fat
-filesystems support idmapped mounts with more filesystems being actively worked
-on.
+.B FAT
+filesystems support idmapped mounts
+with more filesystems being actively worked on.
 .IP \(bu
 The mount must not already be idmapped.
 This also implies that the idmapping of a mount cannot be altered.
@@ -420,24 +427,24 @@ with the
 .I OPEN_TREE_CLONE
 flag and it must not already have been visible in the filesystem.
 .RE
-.RE
 .IP
 Idmappings can be created for user IDs, group IDs, and project IDs.
 An idmapping is essentially a mapping of a range of user or group IDs into
 another or the same range of user or group IDs.
-Idmappings are usually written as three numbers either separated by white space
-or a full stop.
-The first two numbers specify the starting user or group ID in each of the two
-user namespaces.
+Idmappings are usually written as three numbers
+either separated by white space or a full stop.
+The first two numbers specify the starting user or group ID
+in each of the two user namespaces.
 The third number specifies the range of the idmapping.
 For example, a mapping for user IDs such as 1000:1001:1 would indicate that
-user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its
-ancestor user namespace.
-Since the map range is 1 only user ID 1000 is mapped.
+user ID 1000 in the caller's user namespace is mapped to
+user ID 1001 in its ancestor user namespace.
+Since the map range is 1,
+only user ID 1000 is mapped.
 It is possible to specify up to 340 idmappings for each idmapping type.
-If any user IDs or group IDs are not mapped all files owned by that unmapped
-user or group ID will appear as being owned by the overflow user ID or overflow
-group ID respectively.
+If any user IDs or group IDs are not mapped,
+all files owned by that unmapped user or group ID will appear as
+being owned by the overflow user ID or overflow group ID respectively.
 Further details and instructions for setting up idmappings can be found in the
 .BR user_namespaces (7)
 man page.
@@ -445,69 +452,70 @@ man page.
 In the common case the user namespace passed in
 .I userns_fd
 together with
-.BR MOUNT_ATTR_IDMAP
+.B MOUNT_ATTR_IDMAP
 in
 .I attr_set
 to create an idmapped mount will be the user namespace of a container.
-In other scenarios it will be a dedicated user namespace associated with a
-user's login session as is the case for portable home directories in
+In other scenarios it will be a dedicated user namespace associated with
+a user's login session as is the case for portable home directories in
 .BR systemd-homed.service (8) ).
-It is also perfectly fine to create a dedicated user namespace for the sake of
-idmapping a mount.
+It is also perfectly fine to create a dedicated user namespace
+for the sake of idmapping a mount.
 .IP
-Idmapped mounts can be useful in the following and a variety of other
-scenarios:
+Idmapped mounts can be useful in the following
+and a variety of other scenarios:
 .RS
-.RS
-.IP \(bu 2
-sharing files between multiple users or multiple machines especially in
-complex scenarios.
+.IP \(bu
+Sharing files between multiple users or multiple machines,
+especially in complex scenarios.
 For example,
 idmapped mounts are used to implement portable home directories in
 .BR systemd-homed.service (8)
-where they allow users to move their home directory to an external storage
-device and use it on multiple computers where they are assigned different user IDs
-and group IDs.
-This effectively makes it possible to assign random user IDs and group IDs at login time.
+where they allow users to move their home directory
+to an external storage device
+and use it on multiple computers
+where they are assigned different user IDs and group IDs.
+This effectively makes it possible to
+assign random user IDs and group IDs at login time.
 .IP \(bu
-sharing files from the host with unprivileged containers.
-This allows user to avoid having to change ownership permanently through
+Sharing files from the host with unprivileged containers.
+This allows a user to avoid having to change ownership permanently through
 .BR chown (2) .
 .IP \(bu
-idmapping a container's root filesystem.
-Users don't need to change ownership
-permanently through
+Idmapping a container's root filesystem.
+Users don't need to change ownership permanently through
 .BR chown (2) .
-Especially for large root filesystems using
+Especially for large root filesystems, using
 .BR chown (2)
 can be prohibitively expensive.
 .IP \(bu
-sharing files between containers with non-overlapping
-idmappings.
+Sharing files between containers with non-overlapping idmappings.
 .IP \(bu
-implementing discretionary access (DAC) permission checking for fileystems
-lacking a concept of ownership.
+Implementing discretionary access (DAC) permission checking
+for fileystems lacking a concept of ownership.
 .IP \(bu
-efficiently change ownership on a per-mount basis.
+Efficiently change ownership on a per-mount basis.
 In contrast to
-.BR chown (2)
+.BR chown (2),
 changing ownership of large sets of files is instantenous with idmapped mounts.
-This is especially useful when ownership of an entire root filesystem of a
-virtual machine or container is to be changed as we've mentioned above.
-With idmapped mounts a single
-.BR mount_setattr (2)
+This is especially useful when ownership of
+an entire root filesystem of a virtual machine or container
+is to be changed as we've mentioned above.
+With idmapped mounts,
+a single
+.BR mount_setattr ()
 system call will be sufficient to change the ownership of all files.
 .IP \(bu
-taking the current ownership into account.
-Idmappings specify precisely what a user or group ID is supposed to be
-mapped to.
+Taking the current ownership into account.
+Idmappings specify precisely
+what a user or group ID is supposed to be mapped to.
 This contrasts with the
 .BR chown (2)
-system call which cannot by itself take the current ownership of the files it
-changes into account.
+system call which cannot by itself
+take the current ownership of the files it changes into account.
 It simply changes the ownership to the specified user ID and group ID.
 .IP \(bu
-locally and temporarily restricted ownership changes.
+Locally and temporarily restricted ownership changes.
 Idmapped mounts allow to change ownership locally,
 restricting it to specific mounts,
 and temporarily as the ownership changes only apply as long as the mount exists.
@@ -516,7 +524,6 @@ changing ownership via the
 .BR chown (2)
 system call changes the ownership globally and permanently.
 .RE
-.RE
 .PP
 The
 .I propagation
@@ -538,13 +545,13 @@ will propagate to the other mount points that are members of the peer group.
 Propagation here means that the same mount or unmount will automatically occur
 under all of the other mount points in the peer group.
 Conversely,
-mount and unmount events that take place under peer mount points will propagate
-to this mount point.
+mount and unmount events that take place under peer mount points
+will propagate to this mount point.
 .TP
 .B MS_SLAVE
 Turn all mounts into dependent mounts.
-Mount and unmount events propagate into this mount point from a shared peer
-group.
+Mount and unmount events propagate into this mount point
+from a shared peer group.
 Mount and unmount events under this mount point do not propagate to any peer.
 .TP
 .B MS_UNBINDABLE
@@ -558,7 +565,7 @@ when replicating that subtree to produce the target subtree.
 .PP
 .SH RETURN VALUE
 On success,
-.BR mount_setattr (2)
+.BR mount_setattr ()
 returns zero.
 On error,
 \-1 is returned and
@@ -576,8 +583,8 @@ is not a valid file descriptor.
 .TP
 .B EBUSY
 The caller tried to change the mount to
-.BR MOUNT_ATTR_RDONLY
-but the mount still has files open for writing.
+.B MOUNT_ATTR_RDONLY
+but the mount still holds files open for writing.
 .TP
 .B EINVAL
 The path specified via the
@@ -585,7 +592,7 @@ The path specified via the
 and
 .I path
 arguments to
-.BR mount_setattr (2)
+.BR mount_setattr ()
 isn't a mountpoint.
 .TP
 .B EINVAL
@@ -612,11 +619,11 @@ field of
 .TP
 .B EINVAL
 More than one of
-.BR MS_SHARED,
-.BR MS_SLAVE,
-.BR MS_PRIVATE,
+.BR MS_SHARED ,
+.BR MS_SLAVE ,
+.BR MS_PRIVATE ,
 or
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
 was set in
 .I propagation
 field of
@@ -626,13 +633,13 @@ field of
 An access time setting was specified in the
 .I attr_set
 field without
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 being set in the
 .I attr_clr
 field.
 .TP
 .B EINVAL
-.BR MOUNT_ATTR_IDMAP
+.B MOUNT_ATTR_IDMAP
 was specified in
 .IR attr_clr .
 .TP
@@ -645,8 +652,8 @@ which exceeds
 .B EINVAL
 A valid file descriptor value was specified in
 .I userns_fd
-but the file descriptor wasn't a namespace file descriptor or did not refer to
-a user namespace.
+but the file descriptor wasn't a namespace file descriptor
+or did not refer to a user namespace.
 .TP
 .B EINVAL
 The underlying filesystem does not support idmapped mounts.
@@ -660,7 +667,7 @@ the mount is already visible in the filesystem.
 A partial access time setting was specified in
 .I attr_clr
 instead of
-.BR MOUNT_ATTR__ATIME
+.B MOUNT_ATTR__ATIME
 being set.
 .TP
 .B EINVAL
@@ -674,14 +681,14 @@ A pathname was empty or had a nonexistent component.
 .TP
 .B ENOMEM
 When changing mount propagation to
-.BR MS_SHARED
+.B MS_SHARED
 a new peer group id needs to be allocated for all mounts without a peer group
 id set.
 Allocation of this peer group id has failed.
 .TP
 .B ENOSPC
 When changing mount propagation to
-.BR MS_SHARED
+.B MS_SHARED
 a new peer group id needs to be allocated for all mounts without a peer group
 id set.
 Allocation of this peer group id can fail.
@@ -690,25 +697,25 @@ id allocation implementation used.
 .TP
 .B EPERM
 One of the mounts had at least one of
-.BR MOUNT_ATTR_NOATIME,
-.BR MOUNT_ATTR_NODEV,
-.BR MOUNT_ATTR_NODIRATIME,
-.BR MOUNT_ATTR_NOEXEC,
-.BR MOUNT_ATTR_NOSUID,
+.BR MOUNT_ATTR_NOATIME ,
+.BR MOUNT_ATTR_NODEV ,
+.BR MOUNT_ATTR_NODIRATIME ,
+.BR MOUNT_ATTR_NOEXEC ,
+.BR MOUNT_ATTR_NOSUID ,
 or
-.BR MOUNT_ATTR_RDONLY
+.B MOUNT_ATTR_RDONLY
 set and the flag is locked.
 Mount attributes become locked on a mount if:
 .RS
-.IP \(bu 2
-a new mount or mount tree is created causing mount propagation across user
+.IP \(bu
+A new mount or mount tree is created causing mount propagation across user
 namespaces.
 The kernel will lock the aforementioned flags to protect these sensitive
 properties from being altered.
 .IP \(bu
-a new mount and user namespace pair is created.
+A new mount and user namespace pair is created.
 This happens for example when specifying
-.BR CLONE_NEWUSER | CLONE_NEWNS
+.B CLONE_NEWUSER | CLONE_NEWNS
 in
 .BR unshare (2),
 .BR clone (2),
@@ -731,18 +738,18 @@ The caller does not have
 .I CAP_SYS_ADMIN
 in the initial user namespace.
 .SH VERSIONS
-.BR mount_setattr (2)
+.BR mount_setattr ()
 first appeared in Linux 5.12.
 .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
 .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
 .SH CONFORMING TO
-.BR mount_setattr (2)
-is Linux specific.
+.BR mount_setattr ()
+is Linux-specific.
 .SH NOTES
 .SS Extensibility
 In order to allow for future extensibility,
-.BR mount_setattr (2)
+.BR mount_setattr ()
 along with other system calls such as
 .BR openat2 (2)
 and
@@ -751,7 +758,7 @@ requires the user-space application to specify the size of the
 .I mount_attr
 structure that it is passing.
 By providing this information, it is possible for
-.BR mount_setattr (2)
+.BR mount_setattr ()
 to provide both forwards- and backwards-compatibility, with
 .I size
 acting as an implicit version number.
@@ -771,10 +778,9 @@ and let
 .I ksize
 be the size of the structure which the kernel supports,
 then there are three cases to consider:
-.RS
-.IP \(bu 2
+.IP \(bu
 If
-.IR ksize
+.I ksize
 equals
 .IR usize ,
 then there is no version mismatch and
@@ -782,31 +788,32 @@ then there is no version mismatch and
 can be used verbatim.
 .IP \(bu
 If
-.IR ksize
+.I ksize
 is larger than
 .IR usize ,
-then there are some extension fields that the kernel supports which the
-user-space application is unaware of.
+then there are some extension fields that the kernel supports
+which the user-space application is unaware of.
 Because a zero value in any added extension field signifies a no-op,
-the kernel treats all of the extension fields not provided by the user-space
-application as having zero values.
+the kernel treats all of the extension fields
+not provided by the user-space application
+as having zero values.
 This provides backwards-compatibility.
 .IP \(bu
 If
-.IR ksize
+.I ksize
 is smaller than
 .IR usize ,
 then there are some extension fields which the user-space application is aware
 of but which the kernel does not support.
 Because any extension field must have its zero values signify a no-op,
-the kernel can safely ignore the unsupported extension fields if they are
-all zero.
-If any unsupported extension fields are non-zero, then \-1 is returned and
+the kernel can safely ignore the unsupported extension fields
+if they are all zero.
+If any unsupported extension fields are non-zero,
+then \-1 is returned and
 .I errno
 is set to
 .BR E2BIG .
 This provides forwards-compatibility.
-.RE
 .PP
 Because the definition of
 .I struct mount_attr
@@ -842,7 +849,7 @@ attr.attr_clr = MOUNT_ATTR_NODEV;
 .PP
 A user-space application that wishes to determine which extensions the running
 kernel supports can do so by conducting a binary search on
-.IR size
+.I size
 with a structure which has every byte nonzero
 (to find the largest value which doesn't produce an error of
 .BR E2BIG ) .
@@ -865,30 +872,26 @@ with a structure which has every byte nonzero
 #include <sys/syscall.h>
 #include <unistd.h>
 
-static inline int mount_setattr(int dfd,
-                                const char *path,
-                                unsigned int flags,
-                                struct mount_attr *attr,
-                                size_t size)
+static inline int
+mount_setattr(int dfd, const char *path, unsigned int flags,
+              struct mount_attr *attr, size_t size)
 {
-    return syscall(SYS_mount_setattr, dfd, path,
-                   flags, attr, size);
+    return syscall(SYS_mount_setattr, dfd, path, flags, attr, size);
 }
 
-static inline int open_tree(int dfd, const char *filename,
+static inline int
+open_tree(int dfd, const char *filename,
                             unsigned int flags)
 {
     return syscall(SYS_open_tree, dfd, filename, flags);
 }
 
-static inline int move_mount(int from_dfd,
-                             const char *from_pathname,
-                             int to_dfd,
-                             const char *to_pathname,
-                             unsigned int flags)
+static inline int
+move_mount(int from_dfd, const char *from_pathname,
+           int to_dfd, const char *to_pathname, unsigned int flags)
 {
-    return syscall(SYS_move_mount, from_dfd,
-                   from_pathname, to_dfd, to_pathname, flags);
+    return syscall(SYS_move_mount, from_dfd, from_pathname,
+                   to_dfd, to_pathname, flags);
 }
 
 static const struct option longopts[] = {
@@ -902,23 +905,25 @@ static const struct option longopts[] = {
     { NULL,             0,                  NULL,   0 },
 };
 
-#define exit_log(format, ...)                   \\
-    ({                                          \\
-        fprintf(stderr, format, ##__VA_ARGS__); \\
-        exit(EXIT_FAILURE);                     \\
-    })
+#define exit_log(format, ...)  do           \e
+{                                           \e
+    fprintf(stderr, format, ##__VA_ARGS__); \e
+    exit(EXIT_FAILURE);                     \e
+} while (0)
 
-int main(int argc, char *argv[])
+int
+main(int argc, char *argv[])
 {
-    int fd_userns = \-EBADF, index = 0;
+    int fd_userns = \-EBADF;
+    int index = 0;
     bool recursive = false;
     struct mount_attr *attr = &(struct mount_attr){};
     const char *source, *target;
     int fd_tree, new_argc, ret;
-    char *const *new_argv;
+    const char *const *new_argv;
 
     while ((ret = getopt_long_only(argc, argv, "",
-                                  longopts, &index)) != \-1) {
+                                   longopts, &index)) != \-1) {
         switch (ret) {
         case 'a':
             fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
@@ -985,7 +990,6 @@ int main(int argc, char *argv[])
     exit(EXIT_SUCCESS);
 }
 .EE
-.fi
 .SH SEE ALSO
 .BR capabilities (7),
 .BR clone (2),
-- 
2.32.0

Re: [PATCH 21/23] mount_setattr.2: Minor tweaks to Chirstian's patch

[Michael Kerrisk (man-pages)]

Hello Alex,

All of the below looks good, with one small detail noted below.
I've applied this patch (after fixing the typo in the subject line).

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> - Fix SYNOPSIS to fit in 78 columns
> 
>   Also, we don't show when an include is included for a specific type,
>   unless that header is included _only_ for the type,
>   or there might be confusion (e.g., termios).
>   Instead, that type should be documented in system_data_types(7),
>   with a link page mount_attr-struct(3).
> 
> - Fix references to mount_setattr().  See man-pages(7):
> 
>        Any reference to the subject of the current manual page should be writ‐
>        ten with the name in bold followed by a pair of  parentheses  in  Roman
>        (normal)  font.   For  example, in the fcntl(2) man page, references to
>        the subject of the page would be written as:  fcntl().   The  preferred
>        way to write this in the source file is:
> 
>            .BR fcntl ()
> 
> - Fix line breaks according to semantic newline rules (and add some commas)
> - Fix wrong usage of .IR when .RI should have been used
> - Fix formatting of variable part in FOO<number>:
>   - Make italic the variable part (as groff_man(7) recommends)
>   - Remove <>
>   - Use syntax recommended by G. Branden Robinson (groff)
> 
> - Fix unnecessary uses of .BR or .IR when .B or .I would suffice
> - Fix formatting of punctuation
> 
>   In some cases, it was in italics or bold, and it should always be in roman.
> 
> - Use uppercase to begin text, even in bullet points, since those were
>   multi-sentence.
> 
> - Simplify usage of .RS/.RE in combination with .IP
> - s/fat/FAT/ as fs(7) does
> - Slightly reword some sentences for consistency
> - Use Linux-specific for consistency with other pages (in VERSIONS)
> - EXAMPLES: Place the return type in a line of its own (as in other pages)
> - Fix alignment of code
> - Replace unnecessary use of the GNU extension ({}) by do {} while (0)
> 
>   In that case, there was no return value (moreover, it's a noreturn).
> 
> - Break complex declaration lines into a line for each variable
> 
>   The variables were being initialized, some to non-zero values,
>   so for clarity, a line for each one seems more appropriate.
> 
> - Add const to pointers when possible

One of those changes resulted in compiler warnings with cc -Wall;
I reverted that change.

> - s/\\/\e/
> - Remove unmatched groff commands
> 
> Cc: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Cheers,

Michael

> ---
>  man2/mount_setattr.2 | 446 ++++++++++++++++++++++---------------------
>  1 file changed, 225 insertions(+), 221 deletions(-)
> 
> diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
> index 16881d90d..70ab4592e 100644
> --- a/man2/mount_setattr.2
> +++ b/man2/mount_setattr.2
> @@ -30,13 +30,13 @@ mount_setattr \- change mount properties of a mount or mount tree
>  
>  .PP
>  .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> -.BR "#include <linux/mount.h>" " /* Definition of struct mount_attr and MOUNT_ATTR_* constants */"
> +.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
>  .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
>  .B #include <unistd.h>
>  .PP
> -.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path \
> -", unsigned int " flags \
> -", struct mount_attr *" attr ", size_t " size );
> +.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path ,
> +.BI "            unsigned int " flags ", struct mount_attr *" attr \
> +", size_t " size );
>  .fi
>  .PP
>  .IR Note :
> @@ -46,13 +46,13 @@ necessitating the use of
>  .BR syscall (2).
>  .SH DESCRIPTION
>  The
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  system call changes the mount properties of a mount or entire mount tree.
>  If
>  .I path
>  is a relative pathname,
> -then it is interpreted relative to the directory referred to by the file
> -descriptor
> +then it is interpreted relative to
> +the directory referred to by the file descriptor
>  .IR dfd .
>  If
>  .I dfd
> @@ -60,24 +60,25 @@ is the special value
>  .B AT_FDCWD
>  then
>  .I path
> -is taken to be relative to the current working directory of the calling process.
> +is interpreted relative to
> +the current working directory of the calling process.
>  If
>  .I path
>  is the empty string and
> -.BR AT_EMPTY_PATH
> +.B AT_EMPTY_PATH
>  is specified in
> -.I flags
> +.IR flags ,
>  then the mount properties of the mount identified by
>  .I dfd
>  are changed.
>  .PP
>  The
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  system call uses an extensible structure
> -.IR ( "struct mount_attr" )
> +.RI ( "struct mount_attr" )
>  to allow for future extensions.
>  Any non-flag extensions to
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  will be implemented as new fields appended to the above structure,
>  with a zero value in a new field resulting in the kernel behaving
>  as though that extension field was not present.
> @@ -94,17 +95,18 @@ The
>  argument should usually be specified as
>  .IR "sizeof(struct mount_attr)" .
>  However,
> -if the caller does not intend to make use of features that got
> -introduced after the initial version of
> +if the caller does not intend to make use of features that
> +got introduced after the initial version of
>  .I struct mount_attr
> -they are free to pass the size of the initial struct together with the larger
> -struct.
> -This allows the kernel to not copy later parts of the struct that aren't used
> -anyway.
> +they are free to pass
> +the size of the initial struct together with the larger struct.
> +This allows the kernel to not copy later parts of the struct
> +that aren't used anyway.
>  With each extension that changes the size of
>  .I struct mount_attr
>  the kernel will expose a define of the form
> -.BR MOUNT_ATTR_SIZE_VER<number> .
> +.BI MOUNT_ATTR_SIZE_VER number\c
> +\&.
>  For example the macro for the size of the initial version of
>  .I struct mount_attr
>  is
> @@ -118,7 +120,8 @@ The supported values are:
>  .B AT_EMPTY_PATH
>  If
>  .I path
> -is the empty string change the mount properties on
> +is the empty string,
> +change the mount properties on
>  .I dfd
>  itself.
>  .TP
> @@ -134,7 +137,7 @@ Don't trigger automounts.
>  The
>  .I attr
>  argument of
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  is a structure of the following form:
>  .PP
>  .in +4n
> @@ -152,18 +155,21 @@ The
>  .I attr_set
>  and
>  .I attr_clr
> -members are used to specify the mount properties that are supposed to be set or
> -cleared for a mount or mount tree.
> +members are used to specify the mount properties that
> +are supposed to be set or cleared for a mount or mount tree.
>  Flags set in
>  .I attr_set
> -enable a property on a mount or mount tree and flags set in
> +enable a property on a mount or mount tree,
> +and flags set in
>  .I attr_clr
>  remove a property from a mount or mount tree.
>  .PP
> -When changing mount properties the kernel will first clear the flags specified
> +When changing mount properties,
> +the kernel will first clear the flags specified
>  in the
>  .I attr_clr
> -field and then set the flags specified in the
> +field,
> +and then set the flags specified in the
>  .I attr_set
>  field:
>  .PP
> @@ -192,8 +198,8 @@ mnt->mnt_flags = current_mnt_flags;
>  .in
>  .PP
>  The effect of this change will be a mount or mount tree that is read-only,
> -blocks the execution of set-user-ID and set-group-ID binaries but does allow to
> -execute programs and access to devices nodes.
> +blocks the execution of set-user-ID and set-group-ID binaries,
> +but does allow to execute programs and access to devices nodes.
>  Multiple changes with the same set of flags requested
>  in
>  .I attr_clr
> @@ -210,7 +216,8 @@ fields:
>  .B MOUNT_ATTR_RDONLY
>  If set in
>  .I attr_set
> -makes the mount read-only and if set in
> +makes the mount read-only,
> +and if set in
>  .I attr_clr
>  removes the read-only setting if set on the mount.
>  .TP
> @@ -227,46 +234,50 @@ and file capability restriction if set on this mount.
>  .B MOUNT_ATTR_NODEV
>  If set in
>  .I attr_set
> -prevents access to devices on this mount and if set in
> +prevents access to devices on this mount,
> +and if set in
>  .I attr_clr
> -removes the device access restriction if set on this mount.
> +removes the restriction that prevented accesing devices on this mount.
>  .TP
> -.BR MOUNT_ATTR_NOEXEC
> +.B MOUNT_ATTR_NOEXEC
>  If set in
>  .I attr_set
> -prevents executing programs on this mount and if set in
> +prevents executing programs on this mount,
> +and if set in
>  .I attr_clr
> -removes the restriction to execute programs on this mount.
> +removes the restriction that prevented executing programs on this mount.
>  .TP
> -.BR MOUNT_ATTR_NOSYMFOLLOW
> +.B MOUNT_ATTR_NOSYMFOLLOW
>  If set in
>  .I attr_set
> -prevents following symlinks on this mount and if set in
> +prevents following symlinks on this mount,
> +and if set in
>  .I attr_clr
> -removes the restriction to not follow symlinks on this mount.
> +removes the restriction that prevented following symlinks on this mount.
>  .TP
>  .B MOUNT_ATTR_NODIRATIME
>  If set in
>  .I attr_set
> -prevents updating access time for directories on this mount and if set in
> +prevents updating access time for directories on this mount,
> +and if set in
>  .I attr_clr
> -removes access time restriction for directories.
> +removes the restriction that prevented updating access time for directories.
>  Note that
> -.BR MOUNT_ATTR_NODIRATIME
> -can be combined with other access time settings and is implied
> -by the noatime setting.
> +.B MOUNT_ATTR_NODIRATIME
> +can be combined with other access time settings
> +and is implied by the noatime setting.
>  All other access time settings are mutually exclusive.
>  .TP
>  .BR MOUNT_ATTR__ATIME " - Changing access time settings
> -In the new mount api the access time values are an enum starting from 0.
> +In the new mount API the access time values are an enum starting from 0.
>  Even though they are an enum in contrast to the other mount flags such as
> -.BR MOUNT_ATTR_NOEXEC
> +.BR MOUNT_ATTR_NOEXEC ,
>  they are nonetheless passed in
>  .I attr_set
>  and
>  .I attr_clr
>  for consistency with
> -.BR fsmount (2)
> +.BR fsmount (2),
>  which introduced this behavior.
>  .IP
>  Note,
> @@ -281,68 +292,67 @@ in the
>  .I attr_clr
>  field.
>  The kernel will verify that
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  isn't partially set in
> -.I attr_clr
> +.IR attr_clr ,
>  and that
>  .I attr_set
>  doesn't have any access time bits set if
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  isn't set in
>  .IR attr_clr .
>  .RS
>  .TP
>  .B MOUNT_ATTR_RELATIME
>  When a file is accessed via this mount,
> -update the file's last access time
> -(atime)
> -only if the current value of atime is less than or equal to the file's
> -last modification time (mtime) or last status change time (ctime).
> +update the file's last access time (atime)
> +only if the current value of atime is less than or equal to
> +the file's last modification time (mtime) or last status change time (ctime).
>  .IP
> -To enable this access time setting on a mount or mount tree
> -.BR MOUNT_ATTR_RELATIME
> +To enable this access time setting on a mount or mount tree,
> +.B MOUNT_ATTR_RELATIME
>  must be set in
>  .I attr_set
>  and
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  must be set in the
>  .I attr_clr
>  field.
>  .TP
> -.BR MOUNT_ATTR_NOATIME
> +.B MOUNT_ATTR_NOATIME
>  Do not update access times for (all types of) files on this mount.
>  .IP
> -To enable this access time setting on a mount or mount tree
> -.BR MOUNT_ATTR_NOATIME
> +To enable this access time setting on a mount or mount tree,
> +.B MOUNT_ATTR_NOATIME
>  must be set in
>  .I attr_set
>  and
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  must be set in the
>  .I attr_clr
>  field.
>  .TP
> -.BR MOUNT_ATTR_STRICTATIME
> -Always update the last access time (atime) when files are accessed on this
> -mount.
> +.B MOUNT_ATTR_STRICTATIME
> +Always update the last access time (atime)
> +when files are accessed on this mount.
>  .IP
> -To enable this access time setting on a mount or mount tree
> -.BR MOUNT_ATTR_STRICTATIME
> +To enable this access time setting on a mount or mount tree,
> +.B MOUNT_ATTR_STRICTATIME
>  must be set in
>  .I attr_set
>  and
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  must be set in the
>  .I attr_clr
>  field.
>  .RE
>  .TP
> -.BR MOUNT_ATTR_IDMAP
> +.B MOUNT_ATTR_IDMAP
>  If set in
>  .I attr_set
>  creates an idmapped mount.
> -Since it is not supported to change the idmapping of a mount after it has been
> -idmapped,
> +Since it is not supported to
> +change the idmapping of a mount after it has been idmapped,
>  it is invalid to specify
>  .B MOUNT_ATTR_IDMAP
>  in
> @@ -350,54 +360,51 @@ in
>  The idmapping is taken from the user namespace specified in
>  .I userns_fd
>  and attached to the mount.
> -More details can be found in subsequent paragraphs.
>  .IP
> -Creating an idmapped mount allows to change the ownership of all files located
> -under a mount.
> -Thus, idmapped mounts make it possible to change ownership in a temporary and
> -localized way.
> -It is a localized change because ownership changes are restricted to a specific
> -mount.
> +Creating an idmapped mount allows to
> +change the ownership of all files located under a mount.
> +Thus, idmapped mounts make it possible to
> +change ownership in a temporary and localized way.
> +It is a localized change because
> +ownership changes are restricted to a specific mount.
>  All other users and locations where the filesystem is exposed are unaffected.
> -And it is a temporary change because ownership changes are tied to the lifetime
> -of the mount.
> +And it is a temporary change because
> +ownership changes are tied to the lifetime of the mount.
>  .IP
> -Whenever callers interact with the filesystem through an idmapped mount the
> -idmapping of the mount will be applied to user and group IDs associated with
> -filesystem objects.
> -This encompasses the user and group IDs associated with inodes and also
> -the following
> +Whenever callers interact with the filesystem through an idmapped mount,
> +the idmapping of the mount will be applied to
> +user and group IDs associated with filesystem objects.
> +This encompasses the user and group IDs associated with inodes
> +and also the following
>  .BR xattr (7)
>  keys:
>  .RS
> -.RS
> -.IP \(bu 2
> -.IR security.capability
> +.IP \(bu
> +.IR security.capability ,
>  whenever filesystem
>  .BR capabilities (7)
>  are stored or returned in the
>  .I VFS_CAP_REVISION_3
> -format which stores a rootid alongside the capabilities.
> -.IP \(bu 2
> +format,
> +which stores a rootid alongside the capabilities.
> +.IP \(bu
>  .I system.posix_acl_access
>  and
> -.I system.posix_acl_default
> +.IR system.posix_acl_default ,
>  whenever user IDs or group IDs are stored in
> -.BR ACL_USER
> -and
> -.BR ACL_GROUP
> +.B ACL_USER
> +or
> +.B ACL_GROUP
>  entries.
>  .RE
> -.RE
>  .IP
>  The following conditions must be met in order to create an idmapped mount:
>  .RS
> -.RS
> -.IP \(bu 2
> +.IP \(bu
>  The caller must have
>  .I CAP_SYS_ADMIN
>  in the initial user namespace.
> -.IP \(bu 2
> +.IP \(bu
>  The filesystem must be mounted in the initial user namespace.
>  .IP \(bu
>  The underlying filesystem must support idmapped mounts.
> @@ -405,9 +412,9 @@ Currently
>  .BR xfs (5),
>  .BR ext4 (5)
>  and
> -.BR fat
> -filesystems support idmapped mounts with more filesystems being actively worked
> -on.
> +.B FAT
> +filesystems support idmapped mounts
> +with more filesystems being actively worked on.
>  .IP \(bu
>  The mount must not already be idmapped.
>  This also implies that the idmapping of a mount cannot be altered.
> @@ -420,24 +427,24 @@ with the
>  .I OPEN_TREE_CLONE
>  flag and it must not already have been visible in the filesystem.
>  .RE
> -.RE
>  .IP
>  Idmappings can be created for user IDs, group IDs, and project IDs.
>  An idmapping is essentially a mapping of a range of user or group IDs into
>  another or the same range of user or group IDs.
> -Idmappings are usually written as three numbers either separated by white space
> -or a full stop.
> -The first two numbers specify the starting user or group ID in each of the two
> -user namespaces.
> +Idmappings are usually written as three numbers
> +either separated by white space or a full stop.
> +The first two numbers specify the starting user or group ID
> +in each of the two user namespaces.
>  The third number specifies the range of the idmapping.
>  For example, a mapping for user IDs such as 1000:1001:1 would indicate that
> -user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its
> -ancestor user namespace.
> -Since the map range is 1 only user ID 1000 is mapped.
> +user ID 1000 in the caller's user namespace is mapped to
> +user ID 1001 in its ancestor user namespace.
> +Since the map range is 1,
> +only user ID 1000 is mapped.
>  It is possible to specify up to 340 idmappings for each idmapping type.
> -If any user IDs or group IDs are not mapped all files owned by that unmapped
> -user or group ID will appear as being owned by the overflow user ID or overflow
> -group ID respectively.
> +If any user IDs or group IDs are not mapped,
> +all files owned by that unmapped user or group ID will appear as
> +being owned by the overflow user ID or overflow group ID respectively.
>  Further details and instructions for setting up idmappings can be found in the
>  .BR user_namespaces (7)
>  man page.
> @@ -445,69 +452,70 @@ man page.
>  In the common case the user namespace passed in
>  .I userns_fd
>  together with
> -.BR MOUNT_ATTR_IDMAP
> +.B MOUNT_ATTR_IDMAP
>  in
>  .I attr_set
>  to create an idmapped mount will be the user namespace of a container.
> -In other scenarios it will be a dedicated user namespace associated with a
> -user's login session as is the case for portable home directories in
> +In other scenarios it will be a dedicated user namespace associated with
> +a user's login session as is the case for portable home directories in
>  .BR systemd-homed.service (8) ).
> -It is also perfectly fine to create a dedicated user namespace for the sake of
> -idmapping a mount.
> +It is also perfectly fine to create a dedicated user namespace
> +for the sake of idmapping a mount.
>  .IP
> -Idmapped mounts can be useful in the following and a variety of other
> -scenarios:
> +Idmapped mounts can be useful in the following
> +and a variety of other scenarios:
>  .RS
> -.RS
> -.IP \(bu 2
> -sharing files between multiple users or multiple machines especially in
> -complex scenarios.
> +.IP \(bu
> +Sharing files between multiple users or multiple machines,
> +especially in complex scenarios.
>  For example,
>  idmapped mounts are used to implement portable home directories in
>  .BR systemd-homed.service (8)
> -where they allow users to move their home directory to an external storage
> -device and use it on multiple computers where they are assigned different user IDs
> -and group IDs.
> -This effectively makes it possible to assign random user IDs and group IDs at login time.
> +where they allow users to move their home directory
> +to an external storage device
> +and use it on multiple computers
> +where they are assigned different user IDs and group IDs.
> +This effectively makes it possible to
> +assign random user IDs and group IDs at login time.
>  .IP \(bu
> -sharing files from the host with unprivileged containers.
> -This allows user to avoid having to change ownership permanently through
> +Sharing files from the host with unprivileged containers.
> +This allows a user to avoid having to change ownership permanently through
>  .BR chown (2) .
>  .IP \(bu
> -idmapping a container's root filesystem.
> -Users don't need to change ownership
> -permanently through
> +Idmapping a container's root filesystem.
> +Users don't need to change ownership permanently through
>  .BR chown (2) .
> -Especially for large root filesystems using
> +Especially for large root filesystems, using
>  .BR chown (2)
>  can be prohibitively expensive.
>  .IP \(bu
> -sharing files between containers with non-overlapping
> -idmappings.
> +Sharing files between containers with non-overlapping idmappings.
>  .IP \(bu
> -implementing discretionary access (DAC) permission checking for fileystems
> -lacking a concept of ownership.
> +Implementing discretionary access (DAC) permission checking
> +for fileystems lacking a concept of ownership.
>  .IP \(bu
> -efficiently change ownership on a per-mount basis.
> +Efficiently change ownership on a per-mount basis.
>  In contrast to
> -.BR chown (2)
> +.BR chown (2),
>  changing ownership of large sets of files is instantenous with idmapped mounts.
> -This is especially useful when ownership of an entire root filesystem of a
> -virtual machine or container is to be changed as we've mentioned above.
> -With idmapped mounts a single
> -.BR mount_setattr (2)
> +This is especially useful when ownership of
> +an entire root filesystem of a virtual machine or container
> +is to be changed as we've mentioned above.
> +With idmapped mounts,
> +a single
> +.BR mount_setattr ()
>  system call will be sufficient to change the ownership of all files.
>  .IP \(bu
> -taking the current ownership into account.
> -Idmappings specify precisely what a user or group ID is supposed to be
> -mapped to.
> +Taking the current ownership into account.
> +Idmappings specify precisely
> +what a user or group ID is supposed to be mapped to.
>  This contrasts with the
>  .BR chown (2)
> -system call which cannot by itself take the current ownership of the files it
> -changes into account.
> +system call which cannot by itself
> +take the current ownership of the files it changes into account.
>  It simply changes the ownership to the specified user ID and group ID.
>  .IP \(bu
> -locally and temporarily restricted ownership changes.
> +Locally and temporarily restricted ownership changes.
>  Idmapped mounts allow to change ownership locally,
>  restricting it to specific mounts,
>  and temporarily as the ownership changes only apply as long as the mount exists.
> @@ -516,7 +524,6 @@ changing ownership via the
>  .BR chown (2)
>  system call changes the ownership globally and permanently.
>  .RE
> -.RE
>  .PP
>  The
>  .I propagation
> @@ -538,13 +545,13 @@ will propagate to the other mount points that are members of the peer group.
>  Propagation here means that the same mount or unmount will automatically occur
>  under all of the other mount points in the peer group.
>  Conversely,
> -mount and unmount events that take place under peer mount points will propagate
> -to this mount point.
> +mount and unmount events that take place under peer mount points
> +will propagate to this mount point.
>  .TP
>  .B MS_SLAVE
>  Turn all mounts into dependent mounts.
> -Mount and unmount events propagate into this mount point from a shared peer
> -group.
> +Mount and unmount events propagate into this mount point
> +from a shared peer group.
>  Mount and unmount events under this mount point do not propagate to any peer.
>  .TP
>  .B MS_UNBINDABLE
> @@ -558,7 +565,7 @@ when replicating that subtree to produce the target subtree.
>  .PP
>  .SH RETURN VALUE
>  On success,
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  returns zero.
>  On error,
>  \-1 is returned and
> @@ -576,8 +583,8 @@ is not a valid file descriptor.
>  .TP
>  .B EBUSY
>  The caller tried to change the mount to
> -.BR MOUNT_ATTR_RDONLY
> -but the mount still has files open for writing.
> +.B MOUNT_ATTR_RDONLY
> +but the mount still holds files open for writing.
>  .TP
>  .B EINVAL
>  The path specified via the
> @@ -585,7 +592,7 @@ The path specified via the
>  and
>  .I path
>  arguments to
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  isn't a mountpoint.
>  .TP
>  .B EINVAL
> @@ -612,11 +619,11 @@ field of
>  .TP
>  .B EINVAL
>  More than one of
> -.BR MS_SHARED,
> -.BR MS_SLAVE,
> -.BR MS_PRIVATE,
> +.BR MS_SHARED ,
> +.BR MS_SLAVE ,
> +.BR MS_PRIVATE ,
>  or
> -.BR MS_UNBINDABLE
> +.B MS_UNBINDABLE
>  was set in
>  .I propagation
>  field of
> @@ -626,13 +633,13 @@ field of
>  An access time setting was specified in the
>  .I attr_set
>  field without
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  being set in the
>  .I attr_clr
>  field.
>  .TP
>  .B EINVAL
> -.BR MOUNT_ATTR_IDMAP
> +.B MOUNT_ATTR_IDMAP
>  was specified in
>  .IR attr_clr .
>  .TP
> @@ -645,8 +652,8 @@ which exceeds
>  .B EINVAL
>  A valid file descriptor value was specified in
>  .I userns_fd
> -but the file descriptor wasn't a namespace file descriptor or did not refer to
> -a user namespace.
> +but the file descriptor wasn't a namespace file descriptor
> +or did not refer to a user namespace.
>  .TP
>  .B EINVAL
>  The underlying filesystem does not support idmapped mounts.
> @@ -660,7 +667,7 @@ the mount is already visible in the filesystem.
>  A partial access time setting was specified in
>  .I attr_clr
>  instead of
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  being set.
>  .TP
>  .B EINVAL
> @@ -674,14 +681,14 @@ A pathname was empty or had a nonexistent component.
>  .TP
>  .B ENOMEM
>  When changing mount propagation to
> -.BR MS_SHARED
> +.B MS_SHARED
>  a new peer group id needs to be allocated for all mounts without a peer group
>  id set.
>  Allocation of this peer group id has failed.
>  .TP
>  .B ENOSPC
>  When changing mount propagation to
> -.BR MS_SHARED
> +.B MS_SHARED
>  a new peer group id needs to be allocated for all mounts without a peer group
>  id set.
>  Allocation of this peer group id can fail.
> @@ -690,25 +697,25 @@ id allocation implementation used.
>  .TP
>  .B EPERM
>  One of the mounts had at least one of
> -.BR MOUNT_ATTR_NOATIME,
> -.BR MOUNT_ATTR_NODEV,
> -.BR MOUNT_ATTR_NODIRATIME,
> -.BR MOUNT_ATTR_NOEXEC,
> -.BR MOUNT_ATTR_NOSUID,
> +.BR MOUNT_ATTR_NOATIME ,
> +.BR MOUNT_ATTR_NODEV ,
> +.BR MOUNT_ATTR_NODIRATIME ,
> +.BR MOUNT_ATTR_NOEXEC ,
> +.BR MOUNT_ATTR_NOSUID ,
>  or
> -.BR MOUNT_ATTR_RDONLY
> +.B MOUNT_ATTR_RDONLY
>  set and the flag is locked.
>  Mount attributes become locked on a mount if:
>  .RS
> -.IP \(bu 2
> -a new mount or mount tree is created causing mount propagation across user
> +.IP \(bu
> +A new mount or mount tree is created causing mount propagation across user
>  namespaces.
>  The kernel will lock the aforementioned flags to protect these sensitive
>  properties from being altered.
>  .IP \(bu
> -a new mount and user namespace pair is created.
> +A new mount and user namespace pair is created.
>  This happens for example when specifying
> -.BR CLONE_NEWUSER | CLONE_NEWNS
> +.B CLONE_NEWUSER | CLONE_NEWNS
>  in
>  .BR unshare (2),
>  .BR clone (2),
> @@ -731,18 +738,18 @@ The caller does not have
>  .I CAP_SYS_ADMIN
>  in the initial user namespace.
>  .SH VERSIONS
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  first appeared in Linux 5.12.
>  .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
>  .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
>  .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
>  .SH CONFORMING TO
> -.BR mount_setattr (2)
> -is Linux specific.
> +.BR mount_setattr ()
> +is Linux-specific.
>  .SH NOTES
>  .SS Extensibility
>  In order to allow for future extensibility,
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  along with other system calls such as
>  .BR openat2 (2)
>  and
> @@ -751,7 +758,7 @@ requires the user-space application to specify the size of the
>  .I mount_attr
>  structure that it is passing.
>  By providing this information, it is possible for
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  to provide both forwards- and backwards-compatibility, with
>  .I size
>  acting as an implicit version number.
> @@ -771,10 +778,9 @@ and let
>  .I ksize
>  be the size of the structure which the kernel supports,
>  then there are three cases to consider:
> -.RS
> -.IP \(bu 2
> +.IP \(bu
>  If
> -.IR ksize
> +.I ksize
>  equals
>  .IR usize ,
>  then there is no version mismatch and
> @@ -782,31 +788,32 @@ then there is no version mismatch and
>  can be used verbatim.
>  .IP \(bu
>  If
> -.IR ksize
> +.I ksize
>  is larger than
>  .IR usize ,
> -then there are some extension fields that the kernel supports which the
> -user-space application is unaware of.
> +then there are some extension fields that the kernel supports
> +which the user-space application is unaware of.
>  Because a zero value in any added extension field signifies a no-op,
> -the kernel treats all of the extension fields not provided by the user-space
> -application as having zero values.
> +the kernel treats all of the extension fields
> +not provided by the user-space application
> +as having zero values.
>  This provides backwards-compatibility.
>  .IP \(bu
>  If
> -.IR ksize
> +.I ksize
>  is smaller than
>  .IR usize ,
>  then there are some extension fields which the user-space application is aware
>  of but which the kernel does not support.
>  Because any extension field must have its zero values signify a no-op,
> -the kernel can safely ignore the unsupported extension fields if they are
> -all zero.
> -If any unsupported extension fields are non-zero, then \-1 is returned and
> +the kernel can safely ignore the unsupported extension fields
> +if they are all zero.
> +If any unsupported extension fields are non-zero,
> +then \-1 is returned and
>  .I errno
>  is set to
>  .BR E2BIG .
>  This provides forwards-compatibility.
> -.RE
>  .PP
>  Because the definition of
>  .I struct mount_attr
> @@ -842,7 +849,7 @@ attr.attr_clr = MOUNT_ATTR_NODEV;
>  .PP
>  A user-space application that wishes to determine which extensions the running
>  kernel supports can do so by conducting a binary search on
> -.IR size
> +.I size
>  with a structure which has every byte nonzero
>  (to find the largest value which doesn't produce an error of
>  .BR E2BIG ) .
> @@ -865,30 +872,26 @@ with a structure which has every byte nonzero
>  #include <sys/syscall.h>
>  #include <unistd.h>
>  
> -static inline int mount_setattr(int dfd,
> -                                const char *path,
> -                                unsigned int flags,
> -                                struct mount_attr *attr,
> -                                size_t size)
> +static inline int
> +mount_setattr(int dfd, const char *path, unsigned int flags,
> +              struct mount_attr *attr, size_t size)
>  {
> -    return syscall(SYS_mount_setattr, dfd, path,
> -                   flags, attr, size);
> +    return syscall(SYS_mount_setattr, dfd, path, flags, attr, size);
>  }
>  
> -static inline int open_tree(int dfd, const char *filename,
> +static inline int
> +open_tree(int dfd, const char *filename,
>                              unsigned int flags)
>  {
>      return syscall(SYS_open_tree, dfd, filename, flags);
>  }
>  
> -static inline int move_mount(int from_dfd,
> -                             const char *from_pathname,
> -                             int to_dfd,
> -                             const char *to_pathname,
> -                             unsigned int flags)
> +static inline int
> +move_mount(int from_dfd, const char *from_pathname,
> +           int to_dfd, const char *to_pathname, unsigned int flags)
>  {
> -    return syscall(SYS_move_mount, from_dfd,
> -                   from_pathname, to_dfd, to_pathname, flags);
> +    return syscall(SYS_move_mount, from_dfd, from_pathname,
> +                   to_dfd, to_pathname, flags);
>  }
>  
>  static const struct option longopts[] = {
> @@ -902,23 +905,25 @@ static const struct option longopts[] = {
>      { NULL,             0,                  NULL,   0 },
>  };
>  
> -#define exit_log(format, ...)                   \\
> -    ({                                          \\
> -        fprintf(stderr, format, ##__VA_ARGS__); \\
> -        exit(EXIT_FAILURE);                     \\
> -    })
> +#define exit_log(format, ...)  do           \e
> +{                                           \e
> +    fprintf(stderr, format, ##__VA_ARGS__); \e
> +    exit(EXIT_FAILURE);                     \e
> +} while (0)
>  
> -int main(int argc, char *argv[])
> +int
> +main(int argc, char *argv[])
>  {
> -    int fd_userns = \-EBADF, index = 0;
> +    int fd_userns = \-EBADF;
> +    int index = 0;
>      bool recursive = false;
>      struct mount_attr *attr = &(struct mount_attr){};
>      const char *source, *target;
>      int fd_tree, new_argc, ret;
> -    char *const *new_argv;
> +    const char *const *new_argv;
>  
>      while ((ret = getopt_long_only(argc, argv, "",
> -                                  longopts, &index)) != \-1) {
> +                                   longopts, &index)) != \-1) {
>          switch (ret) {
>          case 'a':
>              fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
> @@ -985,7 +990,6 @@ int main(int argc, char *argv[])
>      exit(EXIT_SUCCESS);
>  }
>  .EE
> -.fi
>  .SH SEE ALSO
>  .BR capabilities (7),
>  .BR clone (2),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 22/23] ldd.1: Fix example command

[Alejandro Colomar]

Emanuele Torre via linux-man@:

[
I was reading the man page for ldd(1)[1]; and I read this in the first
paragraph of the DECRIPTION section:

 ldd prints the shared objects (shared libraries) required by each
 program or shared object specified on the command line.  An
 example of its use and output (using sed(1) to trim leading white
 space for readability in this page) is the following:

     $ ldd /bin/ls | sed 's/^ */    /'
         linux-vdso.so.1 (0x00007ffcc3563000)
         libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000)
         libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000)
         libc.so.6 => /lib64/libc.so.6 (0x00007f87e4e92000)
         libpcre.so.1 => /lib64/libpcre.so.1 (0x00007f87e4c22000)
         libdl.so.2 => /lib64/libdl.so.2 (0x00007f87e4a1e000)
         /lib64/ld-linux-x86-64.so.2 (0x00005574bf12e000)
         libattr.so.1 => /lib64/libattr.so.1 (0x00007f87e4817000)
         libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000)

This is a little confusing though since that sed(1) command does not
seem to work. (and also potentially misleading for someone who is trying
figure out how to parse ldd(1)'s output.)

ldd(1) prepends a TAB character (0x09) to each line, not spaces:

 $ ldd /bin/ls | xxd | head -1
 00000000: 096c 696e 7578 2d76 6473 6f2e 736f 2e31  .linux-vdso.so.1

I read ldd(1)'s source code[2] (it is part of glibc) and it seems to be
a bash script that tries to use different rtld programs ( ld.so(8) )
from an RTLDLIST.

Those, on my system, are:

 * /usr/lib/ld-linux.so.2
 * /usr/lib64/ld-linux-x86-64.so.2
 * /usr/libx32/ld-linux-x32.so.2

And they all seem to also be part of glibc.

I have tried to follow the git history of glibc to see when the switch
from spaces to the TAB character occured, but, to me, it seems like
glibc.git/elf/rtld.c has always used '\t'; at since
6a76c115150318eae5d02eca76f2fc03be7bd029[3] (358th commit since glibc
started using the git repository repository - Nov 18th 1995): before
that commit there are not any results for `git grep '\\t'` in the elf
directory and I did not investigate further.

Still, at the time of that commit, glibc did not seem to have an ldd(1)
utility.

Perhaps the man page is old and its original author was using and
documenting an ldd(1) utility that was not part of glibc when he was
writing it.

Anyhow, since I think that sed(1) command will not work on any system
that uses, at least, the most recent version of glibc (because lld(1)
and the ld.so(8) programs it depends on are all part of glibc), I think
that that example should be changed to avoid confusions.

The output format of ldd(1) does not seem to be clearly defined, so I
think this would be a good option:

 $ ldd /bin/ls | sed 's/^[[:space:]]*/    /'

NB: ^\s* should also work on most GNU/Linux systems, but \s is
    non-standard or documented so I don not suggest using it in the man
    page.

Another option could be to remove "the pipe to sed(1)" part and the note
in parentheses that explains why it was used by the original author.

Cheers.
 emanuele6

[1]: https://man7.org/linux/man-pages/man1/ldd.1.html
[2]: https://sourceware.org/git/?p=glibc.git;a=blob;f=elf/ldd.bash.in;h=ba736464ac5e4a9390b1b6a39595035238250232;hb=5188a9d0265cc6f7235a8af1d31ab02e4a24853d
[3]: https://sourceware.org/git/?p=glibc.git;a=commit;h=6a76c115150318eae5d02eca76f2fc03be7bd029

///////

 $ uname -a
 Linux t420 5.10.54-1-lts #1 SMP Wed, 28 Jul 2021 15:05:20 +0000
x86_64 GNU/Linux
 $ pacman -Qo ldd
 /usr/bin/ldd is owned by glibc 2.33-5
 $ pacman -Qo /usr/share/man/man1/ldd.1.gz
 /usr/share/man/man1/ldd.1.gz is owned by man-pages 5.12-2
 $ pacman -Qo /usr/lib/ld-linux.so.2
 /usr/lib/ld-linux.so.2 is owned by lib32-glibc 2.33-5
 $ pacman -Qo /usr/lib64/ld-linux-x86-64.so.2
 /usr/lib/ld-linux-x86-64.so.2 is owned by glibc 2.33-5
 $ pacman -F /usr/libx32/ld-linux-x32.so.2 || echo not available on arch linux.
 not available on arch linux.
]

Reported-by: EmanueleTorre <torreemanuele6@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man1/ldd.1 | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/man1/ldd.1 b/man1/ldd.1
index ed1ab3c05..8bb1410d5 100644
--- a/man1/ldd.1
+++ b/man1/ldd.1
@@ -23,14 +23,11 @@ ldd \- print shared object dependencies
 prints the shared objects (shared libraries) required by each program or
 shared object specified on the command line.
 An example of its use and output
-(using
-.BR sed (1)
-to trim leading white space for readability in this page)
 is the following:
 .PP
 .in +4n
 .EX
-$ \fBldd /bin/ls | sed \(aqs/^ */    /\(aq\fP
+$ \fBldd /bin/ls\fP
     linux\-vdso.so.1 (0x00007ffcc3563000)
     libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000)
     libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000)
-- 
2.32.0

Re: [PATCH 22/23] ldd.1: Fix example command

[Michael Kerrisk (man-pages)]

Hi Emanuele and Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> Emanuele Torre via linux-man@:
> 
> [
> I was reading the man page for ldd(1)[1]; and I read this in the first
> paragraph of the DECRIPTION section:
> 
>  ldd prints the shared objects (shared libraries) required by each
>  program or shared object specified on the command line.  An
>  example of its use and output (using sed(1) to trim leading white
>  space for readability in this page) is the following:
> 
>      $ ldd /bin/ls | sed 's/^ */    /'
>          linux-vdso.so.1 (0x00007ffcc3563000)
>          libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000)
>          libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000)
>          libc.so.6 => /lib64/libc.so.6 (0x00007f87e4e92000)
>          libpcre.so.1 => /lib64/libpcre.so.1 (0x00007f87e4c22000)
>          libdl.so.2 => /lib64/libdl.so.2 (0x00007f87e4a1e000)
>          /lib64/ld-linux-x86-64.so.2 (0x00005574bf12e000)
>          libattr.so.1 => /lib64/libattr.so.1 (0x00007f87e4817000)
>          libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000)
> 
> This is a little confusing though since that sed(1) command does not
> seem to work. (and also potentially misleading for someone who is trying
> figure out how to parse ldd(1)'s output.)
> 
> ldd(1) prepends a TAB character (0x09) to each line, not spaces:
> 
>  $ ldd /bin/ls | xxd | head -1
>  00000000: 096c 696e 7578 2d76 6473 6f2e 736f 2e31  .linux-vdso.so.1
> 
> I read ldd(1)'s source code[2] (it is part of glibc) and it seems to be
> a bash script that tries to use different rtld programs ( ld.so(8) )
> from an RTLDLIST.
> 
> Those, on my system, are:
> 
>  * /usr/lib/ld-linux.so.2
>  * /usr/lib64/ld-linux-x86-64.so.2
>  * /usr/libx32/ld-linux-x32.so.2
> 
> And they all seem to also be part of glibc.
> 
> I have tried to follow the git history of glibc to see when the switch
> from spaces to the TAB character occured, but, to me, it seems like
> glibc.git/elf/rtld.c has always used '\t'; at since
> 6a76c115150318eae5d02eca76f2fc03be7bd029[3] (358th commit since glibc
> started using the git repository repository - Nov 18th 1995): before
> that commit there are not any results for `git grep '\\t'` in the elf
> directory and I did not investigate further.
> 
> Still, at the time of that commit, glibc did not seem to have an ldd(1)
> utility.
> 
> Perhaps the man page is old and its original author was using and
> documenting an ldd(1) utility that was not part of glibc when he was
> writing it.
> 
> Anyhow, since I think that sed(1) command will not work on any system
> that uses, at least, the most recent version of glibc (because lld(1)
> and the ld.so(8) programs it depends on are all part of glibc), I think
> that that example should be changed to avoid confusions.
> 
> The output format of ldd(1) does not seem to be clearly defined, so I
> think this would be a good option:
> 
>  $ ldd /bin/ls | sed 's/^[[:space:]]*/    /'
> 
> NB: ^\s* should also work on most GNU/Linux systems, but \s is
>     non-standard or documented so I don not suggest using it in the man
>     page.
> 
> Another option could be to remove "the pipe to sed(1)" part and the note
> in parentheses that explains why it was used by the original author.
> 
> Cheers.
>  emanuele6
> 
> [1]: https://man7.org/linux/man-pages/man1/ldd.1.html
> [2]: https://sourceware.org/git/?p=glibc.git;a=blob;f=elf/ldd.bash.in;h=ba736464ac5e4a9390b1b6a39595035238250232;hb=5188a9d0265cc6f7235a8af1d31ab02e4a24853d
> [3]: https://sourceware.org/git/?p=glibc.git;a=commit;h=6a76c115150318eae5d02eca76f2fc03be7bd029
> 
> ///////
> 
>  $ uname -a
>  Linux t420 5.10.54-1-lts #1 SMP Wed, 28 Jul 2021 15:05:20 +0000
> x86_64 GNU/Linux
>  $ pacman -Qo ldd
>  /usr/bin/ldd is owned by glibc 2.33-5
>  $ pacman -Qo /usr/share/man/man1/ldd.1.gz
>  /usr/share/man/man1/ldd.1.gz is owned by man-pages 5.12-2
>  $ pacman -Qo /usr/lib/ld-linux.so.2
>  /usr/lib/ld-linux.so.2 is owned by lib32-glibc 2.33-5
>  $ pacman -Qo /usr/lib64/ld-linux-x86-64.so.2
>  /usr/lib/ld-linux-x86-64.so.2 is owned by glibc 2.33-5
>  $ pacman -F /usr/libx32/ld-linux-x32.so.2 || echo not available on arch linux.
>  not available on arch linux.
> ]
> 
> Reported-by: EmanueleTorre <torreemanuele6@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Emanuele, thanks for all of the details.
Alex, thanks for the patch.

Applied.

Cheers,

Michael

> ---
>  man1/ldd.1 | 5 +----
>  1 file changed, 1 insertion(+), 4 deletions(-)
> 
> diff --git a/man1/ldd.1 b/man1/ldd.1
> index ed1ab3c05..8bb1410d5 100644
> --- a/man1/ldd.1
> +++ b/man1/ldd.1
> @@ -23,14 +23,11 @@ ldd \- print shared object dependencies
>  prints the shared objects (shared libraries) required by each program or
>  shared object specified on the command line.
>  An example of its use and output
> -(using
> -.BR sed (1)
> -to trim leading white space for readability in this page)
>  is the following:
>  .PP
>  .in +4n
>  .EX
> -$ \fBldd /bin/ls | sed \(aqs/^ */    /\(aq\fP
> +$ \fBldd /bin/ls\fP
>      linux\-vdso.so.1 (0x00007ffcc3563000)
>      libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000)
>      libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 23/23] close_range.2: Glibc added a wrapper recently

[Alejandro Colomar]

Fixes: c2356ba085ed4f748b81c0ceeba1811b4a549e1c
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/close_range.2 | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/man2/close_range.2 b/man2/close_range.2
index ca84dc448..0bb5de436 100644
--- a/man2/close_range.2
+++ b/man2/close_range.2
@@ -33,9 +33,6 @@ close_range \- close all file descriptors in a given range
 .BI "int close_range(unsigned int " first ", unsigned int " last ,
 .BI "                unsigned int " flags );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 The
 .BR close_range ()
@@ -100,8 +97,6 @@ Library support was added in glibc in version 2.34.
 .BR close_range ()
 is a nonstandard function that is also present on FreeBSD.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
 .SS Closing all open file descriptors
 .\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de
 To avoid blindly closing file descriptors
-- 
2.32.0

Re: [PATCH 23/23] close_range.2: Glibc added a wrapper recently

[Michael Kerrisk (man-pages)]

Hi Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> Fixes: c2356ba085ed4f748b81c0ceeba1811b4a549e1c
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Applied.

Cheers,

Michael

> ---
>  man2/close_range.2 | 5 -----
>  1 file changed, 5 deletions(-)
> 
> diff --git a/man2/close_range.2 b/man2/close_range.2
> index ca84dc448..0bb5de436 100644
> --- a/man2/close_range.2
> +++ b/man2/close_range.2
> @@ -33,9 +33,6 @@ close_range \- close all file descriptors in a given range
>  .BI "int close_range(unsigned int " first ", unsigned int " last ,
>  .BI "                unsigned int " flags );
>  .fi
> -.PP
> -.IR Note :
> -There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
>  The
>  .BR close_range ()
> @@ -100,8 +97,6 @@ Library support was added in glibc in version 2.34.
>  .BR close_range ()
>  is a nonstandard function that is also present on FreeBSD.
>  .SH NOTES
> -Glibc does not provide a wrapper for this system call; call it using
> -.BR syscall (2).
>  .SS Closing all open file descriptors
>  .\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de
>  To avoid blindly closing file descriptors
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 00/23] More patches from others

[Michael Kerrisk (man-pages)]

Hello Alex,

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> 
> Hello, Michael!
> 
> Here's another patch set with patches from others,
> and a few small fixes of mine.

I think I've dealt with all of these now.
Most patches merged, but Mike Rapoport's
memfd_secret() page still needs some work from Mike.

Again, thanks for taking care of all of these patches!

Cheers,

Michael


> Alejandro Colomar (7):
>   sigaction.2: Apply minor tweaks to Peter's patch
>   futex.2: Minor tweaks to Kurt's patch
>   getopt.3: Minor tweak to James's patch
>   termios.3: ffix
>   mount_setattr.2: Minor tweaks to Chirstian's patch
>   ldd.1: Fix example command
>   close_range.2: Glibc added a wrapper recently
> 
> Christian Brauner (1):
>   mount_setattr.2: New manual page documenting the mount_setattr()
>     system call
> 
> G. Branden Robinson (1):
>   man-pages.7: wfix
> 
> James O. D. Hunt (1):
>   getopt.3: Further clarification of optstring
> 
> Kurt Kanzenbach (1):
>   futex.2: Document FUTEX_LOCK_PI2
> 
> Michael Weiß (1):
>   namespaces.7: ffix
> 
> Mike Rapoport (1):
>   man2: new page describing memfd_secret() system call
> 
> Pali Rohár (6):
>   termios.3: Document missing baudrate constants
>   termios.3: Use bold style for Bnn and EXTn macro constants
>   ioctl_tty.2: Document ioctls: TCGETS2, TCSETS2, TCSETSW2, TCSETSF2
>   ioctl_tty.2: Update DTR example
>   termios.3: Add information how to set baud rate to any other value
>   termios.3: SPARC architecture has 4 different Bnnn constants
> 
> Peter Collingbourne (1):
>   sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection
>     protocol
> 
> Štěpán Němec (1):
>   unix.7: tfix
> 
> наб (2):
>   pipe.7: also mention writev(2) in atomicity section
>   regex.3: wfix
> 
>  man1/ldd.1           |    5 +-
>  man2/close_range.2   |    5 -
>  man2/futex.2         |  111 +++--
>  man2/ioctl_tty.2     |   32 +-
>  man2/memfd_secret.2  |  146 ++++++
>  man2/mount_setattr.2 | 1006 ++++++++++++++++++++++++++++++++++++++++++
>  man2/sigaction.2     |  133 ++++++
>  man3/getopt.3        |   10 +-
>  man3/regex.3         |    4 +-
>  man3/termios.3       |   74 +++-
>  man7/man-pages.7     |    2 +-
>  man7/namespaces.7    |    3 +-
>  man7/pipe.7          |    2 +
>  man7/unix.7          |    2 +-
>  14 files changed, 1478 insertions(+), 57 deletions(-)
>  create mode 100644 man2/memfd_secret.2
>  create mode 100644 man2/mount_setattr.2
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/