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:

On 3/30/20 11:20 AM, Aleksa Sarai wrote:

quoted

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

quoted

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>

I'm just editing this page, and have a question on one piece.

quoted

+Unlike
+.BR openat (2),
+it is an error to provide
+.BR openat2 ()
+with a
+.I mode
+which contains bits other than
+.IR 0777 ,

This piece appears not to be true, both from my reading of the
source code, and from testing (i.e., I wrote a a small program that
successfully called openat2() and created a file that had the
set-UID, set-GID, and sticky bits set).

Is this a bug in the implementation or a bug in the manual page text?

My bad -- it's a bug in the manual. The actual check (which does work,
there are selftests for this) is:

	if (how->mode & ~S_IALLUGO)
		return -EINVAL;

But when writing the man page I forgot that S_IALLUGO also includes
those bits. Do you want me to send an updated version or would you
prefer to clean it up?

I'll clean it up.

So, it should say, "bits other than 07777", right?

Yes, that would be correct.

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