Re: [PATCH man-pages v2 2/2] openat2.2: document new openat2(2) syscall

On 2020-03-30, Michael Kerrisk (man-pages) [off-list ref] wrote:

Hello Aleksa,

On 2/2/20 4:19 PM, Aleksa Sarai wrote:

quoted

Rather than trying to merge the new syscall documentation into open.2
(which would probably result in the man-page being incomprehensible),
instead the new syscall gets its own dedicated page with links between
open(2) and openat2(2) to avoid duplicating information such as the list
of O_* flags or common errors.

In addition to describing all of the key flags, information about the
extensibility design is provided so that users can better understand why
they need to pass sizeof(struct open_how) and how their programs will
work across kernels. After some discussions with David Laight, I also
included explicit instructions to zero the structure to avoid issues
when recompiling with new headers.

Signed-off-by: Aleksa Sarai <redacted>

Thanks. I've applied this patch, but also done quite a lot of
editing of the page. The current draft is below (and also pushed 
to Git). Could I ask you to review the page, to see if I injected
any error during my edits.

Looks good to me.

In addition, I've added a number of FIXMEs in comments
in the page source. Can you please check these, and let me
know your thoughts.

Will do, see below.

.\" FIXME I find the "previously-functional systems" in the previous
.\" sentence a little odd (since openat2() ia new sysycall), so I would
.\" like to clarify a little...
.\" Are you referring to the scenario where someone might take an
.\" existing application that uses openat() and replaces the uses
.\" of openat() with openat2()? In which case, is it correct to
.\" understand that you mean that one should not just indiscriminately
.\" add the RESOLVE_NO_XDEV flag to all of the openat2() calls?
.\" If I'm not on the right track, could you point me in the right
.\" direction please.

This is mostly meant as a warning to hopefully avoid applications
because the developer didn't realise that system paths may contain
symlinks or bind-mounts. For an application which has switched to
openat2() and then uses RESOLVE_NO_SYMLINKS for a non-security reason,
it's possible that on some distributions (or future versions of a
distribution) that their application will stop working because a system
path suddenly contains a symlink or is a bind-mount.

This was a concern which was brought up on LWN some time ago. If you can
think of a phrasing that makes this more clear, I'd appreciate it.

.\" FIXME: what specific details in symlink(7) are being referred
.\" by the following sentence? It's not clear.

The section on magic-links, but you're right that the sentence ordering
is a bit odd. It should probably go after the first sentence.

.\" FIXME I found the following hard to understand (in particular, the
.\" meaning of "scoped" is unclear) , and reworded as below. Is it okay?
.\"     Absolute symbolic links and ".." path components will be scoped to
.\"     .IR dirfd .

Scoped does broadly mean "interpreted relative to", though the
difference is mainly that when I said scoped it's meant to be more of an
assertive claim ("the kernel promises to always treat this path inside
dirfd"). But "interpreted relative to" is a clearer way of phrasing the
semantics, so I'm okay with this change.

.\" FIXME The next piece is unclear (to me). What kind of ".." escape
.\" attempts does chroot() not detect that RESOLVE_IN_ROOT does?

If the root is moved, you can escape from a chroot(2). But this sentence
might not really belong in a man-page since it's describing (important)
aspects of the implementation and not the semantics.

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>