[patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[Craig Ringer]

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

The attached 4-patch series adds information to the mount namespaces
and pid namespaces documentation to help users discover how to access
important related information.

1. Elaborate on /proc/[pid]/root and x-ref it
2. Mention /proc/$pid/status NSpid in pid_namespaces
3. Mention pid namespaces /proc/[pid]/root/proc
4. Additional namespaces related x-refs

1): Mention /proc/[pid]/root in mount_namespaces(7) to help people
discover how to access the file system tree seen by a process in
another mount namespace. In the proc (5) entry for it, warn about the
possibly-confusing semantics of readlink() vs following the path in
the vfs layer.

  Adding because I found it difficult to figure out how to access the
file system seen by another process in a disjoint chroot in a
non-ancestor mount namespace.

2): Mention the /proc/[pid]/status NSpid field and related fields in
pid_namespaces (7) to help people discover how to map process IDs
between a parent namespace and any child namespace(s) the process is
in.

  Adding because I found it difficult to discover how to map pids
between namespaces.

3): Mention how /proc/[pid]/root/proc behaves when [pid] is in a
different pid namespace. It's useful to know that you can see another
process's view of procfs via its /proc/[pid]/root link.

4): Some minor cross-references and see-alsos that would've helped me
during unrelated past efforts.

[-- Attachment #2: v1-0001-Elaborate-on-proc-pid-root-and-x-ref-it.patch --]
[-- Type: text/x-patch, Size: 3872 bytes --]

From f99c68f1535dea4f1d926d5a91b1b772557743de Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.ringer@2ndquadrant.com>
Date: Mon, 14 Mar 2022 13:35:38 +0800
Subject: [PATCH v1 1/4] Elaborate on /proc/[pid]/root and x-ref it

Mention /proc/[pid]/{root,cwd,exe,fds} in mount_namespaces (7)
to help users understand how to access the file system tree of
a process in different mount namespace and possibly-disjoint
chroot.

In proc (5) provide a little more detail on how links like
/proc/[pid]/root behave when read with readlink (2) vs when
resolved via kernel vfs layer path lookup. It can be quite confusing
that "readlink /proc/$pid/root" prints "/" so
"ls $(readlink /proc/$pid/root)" has the same result as "ls /" but
"ls /proc/$pid/root/" actually lists the target pid's root.

Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
---
 man5/proc.5             | 29 ++++++++++++++++++++++++++++-
 man7/mount_namespaces.7 | 14 ++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/man5/proc.5 b/man5/proc.5
index c6684620e..2eed160e2 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -658,6 +658,12 @@ are not available if the main thread has already terminated
 (typically by calling
 .BR pthread_exit (3)).
 .IP
+If the process is in a chroot and/or a different mount namespace, reading the
+symlink path will return the executable path relative to the process's root.
+Opening the path within the kernel vfs layer will yield the actual executable
+contents even if  the path does may not exist within the currently active mount
+namespace.
+.IP
 Permission to dereference or read
 .RB ( readlink (2))
 this symbolic link is governed by a ptrace access mode
@@ -1830,7 +1836,8 @@ and
 .IP
 Note however that this file is not merely a symbolic link.
 It provides the same view of the filesystem (including namespaces and the
-set of per-process mounts) as the process itself.
+set of per-process mounts) as the process itself
+if dereferenced via the kernel vfs layer.
 An example illustrates this point.
 In one terminal, we start a shell in new user and mount namespaces,
 and in that shell we create some new mounts:
@@ -1866,6 +1873,26 @@ sh2# \fBls /usr | wc \-l\fP                  # /usr in initial NS
 .EE
 .in
 .IP
+If the target process is in a different mount namespace
+and has a different root, following the
+.B /proc/[pid]/root
+link directly will resolve paths relative to the target
+process's root. But
+.BR readlink (2)
+will return the root path as seen from within the target process's mount
+namespace. Tools that canonicalize paths or resolve symbolic links in
+user-space will not be able to see the target process's root. So
+.B ls $(realpath /proc/[pid]/root)
+will expand to
+.B ls /
+and print the root of the invoking shell, but
+.B ls /proc/[pid]/root/
+will list the contents of
+.B /
+as seen by [pid]. See
+.BR mount_namespaces (7)
+for details.
+.IP
 .\" The following was still true as at kernel 2.6.13
 In a multithreaded process, the contents of the
 .I /proc/[pid]/root
diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
index 7725b341f..98bfd864c 100644
--- a/man7/mount_namespaces.7
+++ b/man7/mount_namespaces.7
@@ -75,6 +75,20 @@ and
 in either mount namespace will not (by default) affect the
 mount list seen in the other namespace
 (but see the following discussion of shared subtrees).
+.PP
+The pseudo-symlinks
+.IR /proc/[pid]/exe ,
+.IR /proc/[pid]/root ,
+.IR /proc/[pid]/fds ,
+and
+.IR /proc/[pid]/cwd
+provide views into the mount namespace of
+.IR [pid]
+from outside that namespace.
+These links provide a way to access the mount namespace seen by another process
+- even if its root is disjoint from the current process's root. See
+.BR proc (5)
+for details and caveats.
 .\"
 .SH SHARED SUBTREES
 After the implementation of mount namespaces was completed,
-- 
2.34.1


[-- Attachment #3: v1-0002-Mention-proc-pid-status-NSpid-in-pid_namespaces.patch --]
[-- Type: text/x-patch, Size: 2534 bytes --]

From 4dd9d464c6e34c75e9456745b6cf71fd0360db44 Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.ringer@2ndquadrant.com>
Date: Mon, 14 Mar 2022 13:49:19 +0800
Subject: [PATCH v1 2/4] Mention /proc/$pid/status NSpid in pid_namespaces

The pid_namespaces (7) documentation did not explain how to map
a process ID from a parent namespace to the corresponding pid in
a child namespace.

Mention the /proc/$pid/status NSpid field and related fields
in pid_namespaces (7) and add a cross-reference to the details
in proc (5).

Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
---
 man5/proc.5           |  4 +++-
 man7/pid_namespaces.7 | 20 ++++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/man5/proc.5 b/man5/proc.5
index 2eed160e2..5180b4b30 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -2602,7 +2602,9 @@ followed by the value in successively nested inner namespaces.
 .IR NSpid
 Thread ID in each of the PID namespaces of which
 .I [pid]
-is a member.
+is a member. This field provides a mapping between parent and child pids
+for processes in nested
+.BR pid_namespaces (7).
 The fields are ordered as for
 .IR NStgid .
 (Since Linux 4.1.)
diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7
index f99b9abbc..f74b7fccd 100644
--- a/man7/pid_namespaces.7
+++ b/man7/pid_namespaces.7
@@ -355,6 +355,14 @@ yields the process ID of the caller in the PID namespace of the procfs mount
 (i.e., the PID namespace of the process that mounted the procfs).
 This can be useful for introspection purposes,
 when a process wants to discover its PID in other namespaces.
+.PP
+Every process has a mapping of parent-to-child process IDs in
+the
+.B NSpid
+field of its
+.B /proc/$childpid/status
+file. Only pids visible in the pid namespace the procfs is mounted with and any
+child namespaces will be shown.
 .\"
 .\" ============================================================
 .\"
@@ -379,6 +387,18 @@ capability inside the user namespace that owns the PID namespace.
 This makes it possible to determine the PID that is allocated
 to the next process that is created inside this PID namespace.
 .\"
+.TP
+.BR /proc/$pid/status
+The
+.B NStgid, NSpid, NSpgid and NSsid
+.NS
+fields of this file map the process ID and other pid-namespaced attributes of
+.BR $pid
+between the current pid namespace any any child namespaces
+the process is a member of. See
+.BR proc (5)
+for details.
+.\"
 .\" ============================================================
 .\"
 .SS Miscellaneous
-- 
2.34.1


[-- Attachment #4: v1-0003-Mention-pid-namespaces-proc-pid-root-proc.patch --]
[-- Type: text/x-patch, Size: 1788 bytes --]

From a2cba8f544167fdaefaa9936c21226a3704d6b73 Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.ringer@2ndquadrant.com>
Date: Mon, 14 Mar 2022 13:35:38 +0800
Subject: [PATCH v1 3/4] Mention pid namespaces /proc/[pid]/root/proc

Add a note in pid_namespaces (7) to explain that
/proc/$pid/root/proc can be used to see the procfs
seen by $pid within its pid namespace.

Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
---
 man5/proc.5           |  8 ++++++++
 man7/pid_namespaces.7 | 10 ++++++++++
 2 files changed, 18 insertions(+)

diff --git a/man5/proc.5 b/man5/proc.5
index 5180b4b30..87445fd55 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -1893,6 +1893,14 @@ as seen by [pid]. See
 .BR mount_namespaces (7)
 for details.
 .IP
+If the target process is in a different pid namespace and has
+.B /proc
+mounted within a mount namespace,
+.B /proc/[pid]/root/proc
+will contain the procfs tree as seen by [pid]. See
+.BR pid_namespaces (7)
+for details.
+.IP
 .\" The following was still true as at kernel 2.6.13
 In a multithreaded process, the contents of the
 .I /proc/[pid]/root
diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7
index f74b7fccd..52a40f544 100644
--- a/man7/pid_namespaces.7
+++ b/man7/pid_namespaces.7
@@ -356,6 +356,16 @@ yields the process ID of the caller in the PID namespace of the procfs mount
 This can be useful for introspection purposes,
 when a process wants to discover its PID in other namespaces.
 .PP
+Processes in parent mount namespaces can see a child process's view
+of its namespace in
+.B /proc/$childpid/root/proc
+if the child process process has
+.B /proc
+mounted within the child namespace.
+See
+.BR proc (5)
+for details.
+.PP
 Every process has a mapping of parent-to-child process IDs in
 the
 .B NSpid
-- 
2.34.1


[-- Attachment #5: v1-0004-Additional-namespaces-related-x-refs.patch --]
[-- Type: text/x-patch, Size: 1806 bytes --]

From 336113bc0d2ea66d44a9f1fb7dee06b04e1cb8da Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.ringer@2ndquadrant.com>
Date: Mon, 14 Mar 2022 13:52:28 +0800
Subject: [PATCH v1 4/4] Additional namespaces related x-refs

Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
---
 man5/proc.5             | 9 +++++++++
 man7/mount_namespaces.7 | 1 +
 man7/pid_namespaces.7   | 2 ++
 3 files changed, 12 insertions(+)

diff --git a/man5/proc.5 b/man5/proc.5
index 87445fd55..dbc064996 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -1539,6 +1539,10 @@ process's mount namespace (see
 The format of this file is documented in
 .BR fstab (5).
 .IP
+.BR /proc/[pid]/mountinfo
+provides more detail than
+.BR /proc/[pid]/mounts "."
+.IP
 Since kernel version 2.6.15, this file is pollable:
 after opening the file for reading, a change in this file
 (i.e., a filesystem mount or unmount) causes
@@ -2099,6 +2103,11 @@ This is used by
 It is defined in the kernel source file
 .IR fs/proc/array.c "."
 .IP
+The newer
+.B /proc/[pid]/status
+provides more details and is easier to use than
+.B /proc/[pid]/stat "."
+.IP
 The fields, in order, with their proper
 .BR scanf (3)
 format specifiers, are listed below.
diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
index 98bfd864c..d206d4bc1 100644
--- a/man7/mount_namespaces.7
+++ b/man7/mount_namespaces.7
@@ -1344,6 +1344,7 @@ See
 .BR pivot_root (2).
 .SH SEE ALSO
 .BR unshare (1),
+.BR nsenter (1),
 .BR clone (2),
 .BR mount (2),
 .BR mount_setattr (2),
diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7
index 52a40f544..f202feedc 100644
--- a/man7/pid_namespaces.7
+++ b/man7/pid_namespaces.7
@@ -436,3 +436,5 @@ See
 .BR namespaces (7),
 .BR user_namespaces (7),
 .BR switch_root (8)
+.BR nsenter (1)
+.BR unshare(1)
-- 
2.34.1

Re: [patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[Alejandro Colomar (man-pages)]

Hi Craig,

On 3/14/22 07:10, Craig Ringer wrote:
> The attached 4-patch series adds information to the mount namespaces
> and pid namespaces documentation to help users discover how to access
> important related information.
> 
> 1. Elaborate on /proc/[pid]/root and x-ref it
> 2. Mention /proc/$pid/status NSpid in pid_namespaces
> 3. Mention pid namespaces /proc/[pid]/root/proc
> 4. Additional namespaces related x-refs
> 
> 1): Mention /proc/[pid]/root in mount_namespaces(7) to help people
> discover how to access the file system tree seen by a process in
> another mount namespace. In the proc (5) entry for it, warn about the
> possibly-confusing semantics of readlink() vs following the path in
> the vfs layer.
> 
>   Adding because I found it difficult to figure out how to access the
> file system seen by another process in a disjoint chroot in a
> non-ancestor mount namespace.
> 
> 2): Mention the /proc/[pid]/status NSpid field and related fields in
> pid_namespaces (7) to help people discover how to map process IDs
> between a parent namespace and any child namespace(s) the process is
> in.
> 
>   Adding because I found it difficult to discover how to map pids
> between namespaces.
> 
> 3): Mention how /proc/[pid]/root/proc behaves when [pid] is in a
> different pid namespace. It's useful to know that you can see another
> process's view of procfs via its /proc/[pid]/root link.
> 
> 4): Some minor cross-references and see-alsos that would've helped me
> during unrelated past efforts.

PATCH 1/4:

> Subject: [PATCH v1 1/4] Elaborate on /proc/[pid]/root and x-ref it

Please mention the modified page(s) in the Subject line.
See <https://www.kernel.org/doc/man-pages/patches.html>.

Also, per the same documentation, please send the patches inline (or
inline + attached if your mailer is likely to break the patches) if you
can, since it's easier for us to review and work with them.

> 
> Mention /proc/[pid]/{root,cwd,exe,fds} in mount_namespaces (7)
> to help users understand how to access the file system tree of
> a process in different mount namespace and possibly-disjoint
> chroot.
> 
> In proc (5) provide a little more detail on how links like
> /proc/[pid]/root behave when read with readlink (2) vs when
> resolved via kernel vfs layer path lookup. It can be quite confusing
> that "readlink /proc/$pid/root" prints "/" so
> "ls $(readlink /proc/$pid/root)" has the same result as "ls /" but
> "ls /proc/$pid/root/" actually lists the target pid's root.
> 
> Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
> ---
>  man5/proc.5             | 29 ++++++++++++++++++++++++++++-
>  man7/mount_namespaces.7 | 14 ++++++++++++++
>  2 files changed, 42 insertions(+), 1 deletion(-)
> 
> diff --git a/man5/proc.5 b/man5/proc.5
> index c6684620e..2eed160e2 100644
> --- a/man5/proc.5
> +++ b/man5/proc.5
> @@ -658,6 +658,12 @@ are not available if the main thread has already terminated
>  (typically by calling
>  .BR pthread_exit (3)).
>  .IP
> +If the process is in a chroot and/or a different mount namespace, reading the

Please use semantic newlines
(i.e., break after that comma, instead of just before col 80).
See man-pages(7):

STYLE GUIDE
       [...]
   Use semantic newlines
       In the source of a manual page, new sentences  should  be
       started on new lines, long sentences should be split into
       lines  at  clause breaks (commas, semicolons, colons, and
       so on), and long clauses should be split at phrase bound‐
       aries.  This convention,  sometimes  known  as  "semantic
       newlines",  makes it easier to see the effect of patches,
       which often operate at the level of individual sentences,
       clauses, or phrases.

> +symlink path will return the executable path relative to the process's root.
> +Opening the path within the kernel vfs layer will yield the actual executable
> +contents even if  the path does may not exist within the currently active mount
> +namespace.
> +.IP
>  Permission to dereference or read
>  .RB ( readlink (2))
>  this symbolic link is governed by a ptrace access mode
> @@ -1830,7 +1836,8 @@ and
>  .IP
>  Note however that this file is not merely a symbolic link.
>  It provides the same view of the filesystem (including namespaces and the
> -set of per-process mounts) as the process itself.
> +set of per-process mounts) as the process itself
> +if dereferenced via the kernel vfs layer.
>  An example illustrates this point.
>  In one terminal, we start a shell in new user and mount namespaces,
>  and in that shell we create some new mounts:
> @@ -1866,6 +1873,26 @@ sh2# \fBls /usr | wc \-l\fP                  # /usr in initial NS
>  .EE
>  .in
>  .IP
> +If the target process is in a different mount namespace
> +and has a different root, following the
> +.B /proc/[pid]/root
> +link directly will resolve paths relative to the target
> +process's root. But
> +.BR readlink (2)
> +will return the root path as seen from within the target process's mount
> +namespace. Tools that canonicalize paths or resolve symbolic links in

Always start sentences after '.' in a new line.
That's already covered by "semantic newlines" (see above),
but it's especially important in this case because
groff(1) prints (at least) 2 spaces after '.' normally,
but if you write it this way it doesn't.

BTW, Branden,
I CCd you because I didn't find this documented in groff(7),
or at least I couldn't find it.
I tried /\.[^ [a-z]] and also keywords like period, point or dot,
but no luck.
Is it documented anywhere?

> +user-space will not be able to see the target process's root. So
> +.B ls $(realpath /proc/[pid]/root)

Commands should use italics (.I) instead of bold (.B).
See man-pages(7):

[
STYLE GUIDE
       [...]
   Formatting conventions (general)
       [...]
       Complete commands should, if long, be written as  an  in‐
       dented  line  on  their own, with a blank line before and
       after the command, for example

           man 7 man-pages

       If the command is short, then it can be  included  inline
       in  the  text,  in italic format, for example, man 7 man-
       pages.  In this case, it may be worth  using  nonbreaking
       spaces  (\~)  at suitable places in the command.  Command
       options should be written in italics (e.g., -l).
]

Variable text inside running italics should be in roman.
So instead of writing [pid], you should use:
.IR "ls $(realpath /proc/" pid /root)

See groff_man_style(7):

[
Description
       [...]
   Font style macros
       [...]
       .I [text]
              Set text in italics.  If the macro is given no ar‐
              guments, the text of the next input line is set in
              italics.

              Use italics for file and path names, for  environ‐
              ment  variables, for C data types, for enumeration
              or  preprocessor  constants  in  C,  for  variable
              (user-determined) portions of syntax synopses, for
              the first occurrence (only) of a technical concept
              being  introduced,  for  names  of journals and of
              literary works longer than an  article,  and  any‐
              where  a  parameter  requiring  replacement by the
              user is encountered.  An exception involves  vari‐
              able  text  in a context that is already marked up
              in italics, such as file or path names with  vari‐
              able components; in such cases, follow the conven‐
              tion  of  mathematical typography: set the file or
              path name in italics as usual but  use  roman  for
              the  variable  part  (see  .IR and .RI below), and
              italics again in running roman text when referring
              to the variable material.
]

> +will expand to
> +.B ls /
> +and print the root of the invoking shell, but
> +.B ls /proc/[pid]/root/
> +will list the contents of
> +.B /
> +as seen by [pid]. See

In this case, use:
.IR pid .

Se rationale above.

> +.BR mount_namespaces (7)
> +for details.
> +.IP
>  .\" The following was still true as at kernel 2.6.13
>  In a multithreaded process, the contents of the
>  .I /proc/[pid]/root

BTW, I now realize that the manual page is currently incorrectly
formatted according to what I just said above.
So, please don't fix that in your patch,
so that the whole page is consistent with itself,
and I'll fix the whole page after your patch
(and some other pages that seem to the same problem). :)

> diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
> index 7725b341f..98bfd864c 100644
> --- a/man7/mount_namespaces.7
> +++ b/man7/mount_namespaces.7
> @@ -75,6 +75,20 @@ and
>  in either mount namespace will not (by default) affect the
>  mount list seen in the other namespace
>  (but see the following discussion of shared subtrees).
> +.PP
> +The pseudo-symlinks
> +.IR /proc/[pid]/exe ,
> +.IR /proc/[pid]/root ,
> +.IR /proc/[pid]/fds ,
> +and
> +.IR /proc/[pid]/cwd
> +provide views into the mount namespace of
> +.IR [pid]
> +from outside that namespace.
> +These links provide a way to access the mount namespace seen by another process
> +- even if its root is disjoint from the current process's root. See
> +.BR proc (5)
> +for details and caveats.
>  .\"
>  .SH SHARED SUBTREES
>  After the implementation of mount namespaces was completed,
> -- 
> 2.34.1
> 

Thanks!

Alex

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

Re: [patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[G. Branden Robinson]

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

Hi, Alex!

At 2022-03-14T15:05:49+0100, Alejandro Colomar (man-pages) wrote:
> Always start sentences after '.' in a new line.
> That's already covered by "semantic newlines" (see above),
> but it's especially important in this case because
> groff(1) prints (at least) 2 spaces after '.' normally,
> but if you write it this way it doesn't.
> 
> BTW, Branden,
> I CCd you because I didn't find this documented in groff(7),
> or at least I couldn't find it.
> I tried /\.[^ [a-z]] and also keywords like period, point or dot,
> but no luck.
> Is it documented anywhere?

It used to be one of those things everybody just "knew" about writing in
*roff--back when people hung on Brian Kernighan's every word[1]--but
over the years the knowledge has atrophied.

The groff 1.22.4 Texinfo manual has the following.  I believe this
material is adapted from Eric Allman's paper "Writing Papers with NROFF
using -me".

[[
3 Tutorial for Macro Users
**************************

Most users tend to use a macro package to format their papers.  This
means that the whole breadth of 'groff' is not necessary for most
people.  This chapter covers the material needed to efficiently use a
macro package.
[...]
   * In keeping with this, it is helpful to begin a new line after every
     comma or phrase, since common corrections are to add or delete
     sentences or phrases.

   * End each sentence with two spaces - or better, start each sentence
     on a new line.  'gtroff' recognizes characters that usually end a
     sentence, and inserts sentence space accordingly.
]]

This advice, in the context of macro package usage, is scoped too
narrowly.  The manual has a later section which makes the point again.

[[
5.1.6 Input Conventions
-----------------------

Since 'gtroff' does filling automatically, it is traditional in 'groff'
not to try and type things in as nicely formatted paragraphs.  These are
some conventions commonly used when typing 'gtroff' text:

   * Break lines after punctuation, particularly at the end of a
     sentence and in other logical places.  Keep separate phrases on
     lines by themselves, as entire phrases are often added or deleted
     when editing.

   * Try to keep lines less than 40-60 characters, to allow space for
     inserting more text.

   * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
     try using spaces to get proper indentation).
]]

I have written new material for groff's Texinfo manual in the
forthcoming 1.23.0 release.  The above section is significantly expanded
and, happily for skeptics of GNU Texinfo, ported to a man page as well.
The roff(7) page bears the fruit of much labor, including the following.

[[
Input conventions
       Since troff fills text automatically, it is common practice in
       roff languages to not attempt careful visual composition of text
       in input files: it is the esthetic appeal of the formatted output
       that matters.  Therefore, roff input should be arranged such that
       it is easy for authors and maintainers to compose and develop the
       document, understand the syntax of roff requests, macro calls,
       and preprocessor languages used, and predict the behavior of the
       formatter.  Several traditions have accrued in service of these
       goals.

       •      Break input lines after sentence‐ending punctuation to
              ease their recognition.  It is frequently convenient to
              break after colons and semicolons as well, as these
              typically precede independent clauses.  Consider breaking
              after commas; they often occur in lists that become easy
              to scan when itemized by line, or constitute supplements
              to the sentence that are added, deleted, or updated to
              clarify it.  Parenthetical and quoted phrases are also
              good candidates for placement on input lines by
              themselves.  In filled text, spaces and newlines are
              interchangeable; place breaks where it aids your purpose.

       •      Set your text editor’s line length to 72 characters or
              fewer; see the subsections below.  This limit, combined
              with the previous advice regarding breaking around
              punctuation, makes it less common that an input line will
              wrap in your text editor, and thus will help you perceive
              excessively long constructions in your text.  Recall that
              natural languages originate in speech, not writing, and
              that punctuation is correlated with pauses for breathing
              and changes in prosody.

       •      Use \& after “!”, “?”, and “.” if they are followed by
              space, tab, or newline characters and don’t end a
              sentence.

       •      In filled text lines, use \& before “.” and “'” if they
              are preceded by space, so that reflowing the input doesn't
              turn them into control lines.

       •      Do not attempt to format the input in a WYSIWYG manner
              (i.e., don’t try using spaces to get proper indentation or
              align columns of a table).

       •      Comment your document.  It is never too soon to apply
              comments to record information of use to future document
              maintainers (including your future self).  The \" escape
              sequence causes troff to ignore the remainder of the input
              line.

       •      Use the empty request—a control character followed
              immediately by a newline—to visually manage separation of
              material in input files.  Many of the groff project’s own
              documents use an empty request between sentences, after
              macro definitions, and where a break is expected, and two
              empty requests between paragraphs or other requests or
              macro calls that will introduce vertical space into the
              document.  You can combine the empty request with the
              comment escape sequence to include whole‐line comments in
              your document, and even “comment out” sections of it.
]]

This point about beginning sentences only on new input lines _is_
missing from groff_man_style(7).  As noted in the groff 1.22.4 NEWS
file:

o ... groff_man(7) has been expanded and largely rewritten ... to be
  more helpful and accessible to man page writers who may never read any
  other groff documentation.

groff_man_style(7) is now fulfilling this role, since a quick reference
for experienced man page writers remains desirable.  (I avoid letting
the two drift out of sync by generating both from an m4 master
document.)

I've been dithering over writing a new introductory section just for
groff_man_style(7) to present an example of a partial man page and use
it to explain typesetting terms that are inescapable even in the reduced
domain of man pages: breaking, filling, adjustment, hyphenation, and the
notorious matter of supplementary inter-sentence space.

As you will have observed, when I write in a hurry, I write a lot.  The
foregoing notional material needs to be written well, and that means
taking the time to cook the fat off.

Regards,
Branden

[1] https://rhodesmill.org/brandon/2012/one-sentence-per-line/

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

Re: [patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 3/20/22 15:53, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2022-03-14T15:05:49+0100, Alejandro Colomar (man-pages) wrote:
>> Always start sentences after '.' in a new line.
>> That's already covered by "semantic newlines" (see above),
>> but it's especially important in this case because
>> groff(1) prints (at least) 2 spaces after '.' normally,
>> but if you write it this way it doesn't.
>>
>> BTW, Branden,
>> I CCd you because I didn't find this documented in groff(7),
>> or at least I couldn't find it.
>> I tried /\.[^ [a-z]] and also keywords like period, point or dot,
>> but no luck.
>> Is it documented anywhere?
> 
> It used to be one of those things everybody just "knew" about writing in
> *roff--back when people hung on Brian Kernighan's every word[1]--but
> over the years the knowledge has atrophied.

Okay.
> 
> The groff 1.22.4 Texinfo manual has the following.  I believe this
> material is adapted from Eric Allman's paper "Writing Papers with NROFF
> using -me".
> 
> [[
> 3 Tutorial for Macro Users
> **************************
> 
[...]
> 
>    * End each sentence with two spaces - or better, start each sentence
>      on a new line.  'gtroff' recognizes characters that usually end a
>      sentence, and inserts sentence space accordingly.

Ahh, that paragraph is what I was looking for.

[...]
> 
>        •      Set your text editor’s line length to 72 characters or
>               fewer; see the subsections below.  This limit, combined
>               with the previous advice regarding breaking around
>               punctuation, makes it less common that an input line will
>               wrap in your text editor, and thus will help you perceive
>               excessively long constructions in your text.  Recall that
>               natural languages originate in speech, not writing, and
>               that punctuation is correlated with pauses for breathing
>               and changes in prosody.

That last line should be reminded more often :)

[...]
> This point about beginning sentences only on new input lines _is_
> missing from groff_man_style(7).  As noted in the groff 1.22.4 NEWS
> file:
> 
> o ... groff_man(7) has been expanded and largely rewritten ... to be
>   more helpful and accessible to man page writers who may never read any
>   other groff documentation.
> 
> groff_man_style(7) is now fulfilling this role, since a quick reference
> for experienced man page writers remains desirable.  (I avoid letting
> the two drift out of sync by generating both from an m4 master
> document.)
> 
> I've been dithering over writing a new introductory section just for
> groff_man_style(7) to present an example of a partial man page and use
> it to explain typesetting terms that are inescapable even in the reduced
> domain of man pages: breaking, filling, adjustment, hyphenation, and the
> notorious matter of supplementary inter-sentence space.
> 
> As you will have observed, when I write in a hurry, I write a lot.  The
> foregoing notional material needs to be written well, and that means
> taking the time to cook the fat off.

I'll try to find some time to read the whole pages...

Thank you very much for your (very) detailed responses! :-)

Cheers,

Alex

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

Re: [patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 10371 bytes --]

Hi Craig,

I'm checking old mail, and see that this thread was unresolved.  Do
you still have this patch around and are interested in sending it?\

Thanks,

Alex

On 3/14/22 15:05, Alejandro Colomar (man-pages) wrote:
> Hi Craig,
> 
> On 3/14/22 07:10, Craig Ringer wrote:
>> The attached 4-patch series adds information to the mount namespaces
>> and pid namespaces documentation to help users discover how to access
>> important related information.
>>
>> 1. Elaborate on /proc/[pid]/root and x-ref it
>> 2. Mention /proc/$pid/status NSpid in pid_namespaces
>> 3. Mention pid namespaces /proc/[pid]/root/proc
>> 4. Additional namespaces related x-refs
>>
>> 1): Mention /proc/[pid]/root in mount_namespaces(7) to help people
>> discover how to access the file system tree seen by a process in
>> another mount namespace. In the proc (5) entry for it, warn about the
>> possibly-confusing semantics of readlink() vs following the path in
>> the vfs layer.
>>
>>   Adding because I found it difficult to figure out how to access the
>> file system seen by another process in a disjoint chroot in a
>> non-ancestor mount namespace.
>>
>> 2): Mention the /proc/[pid]/status NSpid field and related fields in
>> pid_namespaces (7) to help people discover how to map process IDs
>> between a parent namespace and any child namespace(s) the process is
>> in.
>>
>>   Adding because I found it difficult to discover how to map pids
>> between namespaces.
>>
>> 3): Mention how /proc/[pid]/root/proc behaves when [pid] is in a
>> different pid namespace. It's useful to know that you can see another
>> process's view of procfs via its /proc/[pid]/root link.
>>
>> 4): Some minor cross-references and see-alsos that would've helped me
>> during unrelated past efforts.
> 
> PATCH 1/4:
> 
>> Subject: [PATCH v1 1/4] Elaborate on /proc/[pid]/root and x-ref it
> 
> Please mention the modified page(s) in the Subject line.
> See <https://www.kernel.org/doc/man-pages/patches.html>.
> 
> Also, per the same documentation, please send the patches inline (or
> inline + attached if your mailer is likely to break the patches) if you
> can, since it's easier for us to review and work with them.
> 
>>
>> Mention /proc/[pid]/{root,cwd,exe,fds} in mount_namespaces (7)
>> to help users understand how to access the file system tree of
>> a process in different mount namespace and possibly-disjoint
>> chroot.
>>
>> In proc (5) provide a little more detail on how links like
>> /proc/[pid]/root behave when read with readlink (2) vs when
>> resolved via kernel vfs layer path lookup. It can be quite confusing
>> that "readlink /proc/$pid/root" prints "/" so
>> "ls $(readlink /proc/$pid/root)" has the same result as "ls /" but
>> "ls /proc/$pid/root/" actually lists the target pid's root.
>>
>> Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
>> ---
>>  man5/proc.5             | 29 ++++++++++++++++++++++++++++-
>>  man7/mount_namespaces.7 | 14 ++++++++++++++
>>  2 files changed, 42 insertions(+), 1 deletion(-)
>>
>> diff --git a/man5/proc.5 b/man5/proc.5
>> index c6684620e..2eed160e2 100644
>> --- a/man5/proc.5
>> +++ b/man5/proc.5
>> @@ -658,6 +658,12 @@ are not available if the main thread has already terminated
>>  (typically by calling
>>  .BR pthread_exit (3)).
>>  .IP
>> +If the process is in a chroot and/or a different mount namespace, reading the
> 
> Please use semantic newlines
> (i.e., break after that comma, instead of just before col 80).
> See man-pages(7):
> 
> STYLE GUIDE
>        [...]
>    Use semantic newlines
>        In the source of a manual page, new sentences  should  be
>        started on new lines, long sentences should be split into
>        lines  at  clause breaks (commas, semicolons, colons, and
>        so on), and long clauses should be split at phrase bound‐
>        aries.  This convention,  sometimes  known  as  "semantic
>        newlines",  makes it easier to see the effect of patches,
>        which often operate at the level of individual sentences,
>        clauses, or phrases.
> 
>> +symlink path will return the executable path relative to the process's root.
>> +Opening the path within the kernel vfs layer will yield the actual executable
>> +contents even if  the path does may not exist within the currently active mount
>> +namespace.
>> +.IP
>>  Permission to dereference or read
>>  .RB ( readlink (2))
>>  this symbolic link is governed by a ptrace access mode
>> @@ -1830,7 +1836,8 @@ and
>>  .IP
>>  Note however that this file is not merely a symbolic link.
>>  It provides the same view of the filesystem (including namespaces and the
>> -set of per-process mounts) as the process itself.
>> +set of per-process mounts) as the process itself
>> +if dereferenced via the kernel vfs layer.
>>  An example illustrates this point.
>>  In one terminal, we start a shell in new user and mount namespaces,
>>  and in that shell we create some new mounts:
>> @@ -1866,6 +1873,26 @@ sh2# \fBls /usr | wc \-l\fP                  # /usr in initial NS
>>  .EE
>>  .in
>>  .IP
>> +If the target process is in a different mount namespace
>> +and has a different root, following the
>> +.B /proc/[pid]/root
>> +link directly will resolve paths relative to the target
>> +process's root. But
>> +.BR readlink (2)
>> +will return the root path as seen from within the target process's mount
>> +namespace. Tools that canonicalize paths or resolve symbolic links in
> 
> Always start sentences after '.' in a new line.
> That's already covered by "semantic newlines" (see above),
> but it's especially important in this case because
> groff(1) prints (at least) 2 spaces after '.' normally,
> but if you write it this way it doesn't.
> 
> BTW, Branden,
> I CCd you because I didn't find this documented in groff(7),
> or at least I couldn't find it.
> I tried /\.[^ [a-z]] and also keywords like period, point or dot,
> but no luck.
> Is it documented anywhere?
> 
>> +user-space will not be able to see the target process's root. So
>> +.B ls $(realpath /proc/[pid]/root)
> 
> Commands should use italics (.I) instead of bold (.B).
> See man-pages(7):
> 
> [
> STYLE GUIDE
>        [...]
>    Formatting conventions (general)
>        [...]
>        Complete commands should, if long, be written as  an  in‐
>        dented  line  on  their own, with a blank line before and
>        after the command, for example
> 
>            man 7 man-pages
> 
>        If the command is short, then it can be  included  inline
>        in  the  text,  in italic format, for example, man 7 man-
>        pages.  In this case, it may be worth  using  nonbreaking
>        spaces  (\~)  at suitable places in the command.  Command
>        options should be written in italics (e.g., -l).
> ]
> 
> Variable text inside running italics should be in roman.
> So instead of writing [pid], you should use:
> .IR "ls $(realpath /proc/" pid /root)
> 
> See groff_man_style(7):
> 
> [
> Description
>        [...]
>    Font style macros
>        [...]
>        .I [text]
>               Set text in italics.  If the macro is given no ar‐
>               guments, the text of the next input line is set in
>               italics.
> 
>               Use italics for file and path names, for  environ‐
>               ment  variables, for C data types, for enumeration
>               or  preprocessor  constants  in  C,  for  variable
>               (user-determined) portions of syntax synopses, for
>               the first occurrence (only) of a technical concept
>               being  introduced,  for  names  of journals and of
>               literary works longer than an  article,  and  any‐
>               where  a  parameter  requiring  replacement by the
>               user is encountered.  An exception involves  vari‐
>               able  text  in a context that is already marked up
>               in italics, such as file or path names with  vari‐
>               able components; in such cases, follow the conven‐
>               tion  of  mathematical typography: set the file or
>               path name in italics as usual but  use  roman  for
>               the  variable  part  (see  .IR and .RI below), and
>               italics again in running roman text when referring
>               to the variable material.
> ]
> 
>> +will expand to
>> +.B ls /
>> +and print the root of the invoking shell, but
>> +.B ls /proc/[pid]/root/
>> +will list the contents of
>> +.B /
>> +as seen by [pid]. See
> 
> In this case, use:
> .IR pid .
> 
> Se rationale above.
> 
>> +.BR mount_namespaces (7)
>> +for details.
>> +.IP
>>  .\" The following was still true as at kernel 2.6.13
>>  In a multithreaded process, the contents of the
>>  .I /proc/[pid]/root
> 
> BTW, I now realize that the manual page is currently incorrectly
> formatted according to what I just said above.
> So, please don't fix that in your patch,
> so that the whole page is consistent with itself,
> and I'll fix the whole page after your patch
> (and some other pages that seem to the same problem). :)
> 
>> diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
>> index 7725b341f..98bfd864c 100644
>> --- a/man7/mount_namespaces.7
>> +++ b/man7/mount_namespaces.7
>> @@ -75,6 +75,20 @@ and
>>  in either mount namespace will not (by default) affect the
>>  mount list seen in the other namespace
>>  (but see the following discussion of shared subtrees).
>> +.PP
>> +The pseudo-symlinks
>> +.IR /proc/[pid]/exe ,
>> +.IR /proc/[pid]/root ,
>> +.IR /proc/[pid]/fds ,
>> +and
>> +.IR /proc/[pid]/cwd
>> +provide views into the mount namespace of
>> +.IR [pid]
>> +from outside that namespace.
>> +These links provide a way to access the mount namespace seen by another process
>> +- even if its root is disjoint from the current process's root. See
>> +.BR proc (5)
>> +for details and caveats.
>>  .\"
>>  .SH SHARED SUBTREES
>>  After the implementation of mount namespaces was completed,
>> -- 
>> 2.34.1
>>
> 
> Thanks!
> 
> Alex
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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