Linux-man Archive on lore.kernel.org
 help / color / Atom feed
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: "Philipp Wendler" <ml@philippwendler.de>,
	"Eric W. Biederman" <ebiederm@xmission.com>,
	"Serge E. Hallyn" <serge@hallyn.com>,
	"Christian Brauner" <christian@brauner.io>,
	"Aleksa Sarai" <asarai@suse.de>,
	"Reid Priedhorsky" <reidpr@lanl.gov>,
	"Andy Lutomirski" <luto@amacapital.net>,
	"Yang Bo" <rslovers@yandex.com>, "Jakub Wilk" <jwilk@jwilk.net>,
	"Joseph Sible" <josephcsible@gmail.com>,
	"Al Viro" <viro@ftp.linux.org.uk>,
	werner@almesberger.net, linux-man <linux-man@vger.kernel.org>,
	lkml <linux-kernel@vger.kernel.org>,
	Containers <containers@lists.linux-foundation.org>,
	"Stéphane Graber" <stgraber@ubuntu.com>
Subject: Re: For review: rewritten pivot_root(2) manual page
Date: Wed, 9 Oct 2019 19:18:30 +1100
Message-ID: <20191009081811.u4p3bd3bqvppgvcf@localhost.localdomain> (raw)
In-Reply-To: <e51e454c-b0e7-e5d1-7810-e8f023574aa2@gmail.com>

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

At 2019-10-09T09:41:34+0200, Michael Kerrisk (man-pages) wrote:
> I'm not sure. Some people have a bit of trouble to wrap their head
> around the pivot_root(".", ".") idea. (I possibly am one of them.)
> I'd be quite keen to hear other opinions on this. Unfortunately,
> few people have commented on this manual page rewrite.

pivot_root(".", ".") seems as ineffable to me as chdir(".").

Meaning mostly, but not completely.

I have an external drive with a USB cable that's a little dodgy.  If it
moves around a bit the external drive gets auto-unmounted, and then
remounted in the same place, so I can experience the otherwise-baffling
shell experience of:

[disconnect/reconnect happens; the device is mounted again now]
$ ls .
Input/output error
$ cd .
$ ls .
[perfectly fine listing]

What's happened is that the meaning of "." has subtly changed in a way
that I suppose would never have been seen back in Version 7 Unix days.
Maybe I've been reading too much historical documentation (I'm currently
enjoying McKusick et al.'s _Design and Implementation of the 4.4BSD
Operations System_), but the way we describe and teach Unixlike systems
in operating systems classes and, more to the point, in our man pages I
think continues to be strongly informed by the invariants we learned in
our youth, and which are slowly but steadily being invalidated.

Concretely, I recommend having pivot_root(".", ".") in the man page as
an example, but perhaps as an alternate.  Because it is
counterintuitive (to some minds), it's worth spending some time to
explain it.  But I would offer it because it's a valid use of the system
call and because it makes sense to a domain expert (Eric Biedermann).

I would try to offer an explanation myself but I lack the understanding.
_If_ I'm following the discussion correctly, which I doubt, then what I
imagine to happen is that a sequence point occurs between the function
parameters, and "." changes its meaning as with my "cd ." example above.
I am probably reasoning by analogy, and perhaps not by a good one.

Also, it is okay if the language of this page continues to evolve over
time.  I appreciate your desire to get it "perfect" (or at least to some
local optimum) now since you're most of the way through an overhaul of
it, but it is not just the system that changes with time--the audience
does too.

Maybe in 5 or 10 years, the kids will be au fait with pivot_root(".",
".") and only some graybeards will continue to think of it as a bit
strange.

Regards,
Branden

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

  reply index

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-23 12:04 Michael Kerrisk (man-pages)
2019-09-23 13:42 ` Philipp Wendler
2019-10-09  7:41   ` Michael Kerrisk (man-pages)
2019-10-09  8:18     ` G. Branden Robinson [this message]
2019-10-09  8:46     ` ebiederm
2019-10-09 10:22       ` Michael Kerrisk (man-pages)
2019-10-09 16:00         ` ebiederm
2019-10-09 21:01           ` Michael Kerrisk (man-pages)
2019-10-10  7:42             ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191009081811.u4p3bd3bqvppgvcf@localhost.localdomain \
    --to=g.branden.robinson@gmail.com \
    --cc=asarai@suse.de \
    --cc=christian@brauner.io \
    --cc=containers@lists.linux-foundation.org \
    --cc=ebiederm@xmission.com \
    --cc=josephcsible@gmail.com \
    --cc=jwilk@jwilk.net \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=luto@amacapital.net \
    --cc=ml@philippwendler.de \
    --cc=mtk.manpages@gmail.com \
    --cc=reidpr@lanl.gov \
    --cc=rslovers@yandex.com \
    --cc=serge@hallyn.com \
    --cc=stgraber@ubuntu.com \
    --cc=viro@ftp.linux.org.uk \
    --cc=werner@almesberger.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git