Skip to contentSkip to conversation

OPENAT2_REGULAR flag documentation

PATCH In review Dorjoy Chowdhury 2 participants 5 messages Apr 25 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

cover OPENAT2_REGULAR flag documentation

Hi,
I am the author of the patch series that adds OPENAT2_REGULAR flag support for the openat2 system call. The patch series has been picked up in the vfs-7.2.openat.regular branch of the vfs/vfs.git tree. Hopefully, it will make it to linux 7.2 without problems. I wanted to send the man page changes beforehand. I can ping when/if the patches make it to the linux kernel and then we can merge the man page changes. Thanks!

patch URL: https://lore.kernel.org/linux-fsdevel/[email protected]/
applied mail: https://lore.kernel.org/linux-fsdevel/20260416-abgraben-seeweg-a44ce660957f@brauner/

Regards,
Dorjoy

Dorjoy Chowdhury (1):
man/man2/openat2.2: Document OPENAT2_REGULAR flag

 man/man2/openat2.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
Signature · 1 line
2.53.0
#1 lore raw

PATCH 1/1 man/man2/openat2.2: Document OPENAT2_REGULAR flag

---
 man/man2/openat2.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
man/man2/openat2.2 +19 -0
index f0770f3a0..42ebf22ea 100644
@@ -133,6 +133,19 @@ argument,
 .BR openat2 ()
 returns an error if unknown or conflicting flags are specified in
 .IR how.flags .
+.IP
+.BR openat2 ()
+also supports the below additional flags:
+.RS
+.TP
+.BR OPENAT2_REGULAR " (since Linux 7.2)"
+Only open the file specified by
+.I path
+if it is a regular file. If it is not a regular file,
+.BR openat2 ()
+fails with the error
+.BR EFTYPE .
+.RE
 .TP
 .I mode
 This field specifies the
@@ -471,6 +484,12 @@ and an escape from the root during path resolution was detected.
 contains
 .BR RESOLVE_NO_XDEV ,
 and a path component crosses a mount point.
+.TP
+.B EFTYPE
+.I how.flags
+contains
+.BR OPENAT2_REGULAR
+flag and the path is not a regular file.
 .SH STANDARDS
 Linux.
 .SH HISTORY
Signature · 1 line
2.53.0
#2 lore raw

Re: [PATCH 1/1] man/man2/openat2.2: Document OPENAT2_REGULAR flag

Hi Dorjoy,

Quoted 12 lines · Dorjoy Chowdhury
---
 man/man2/openat2.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
man/man2/openat2.2 +0 -0
index f0770f3a0..42ebf22ea 100644
@@ -133,6 +133,19 @@ argument,
 .BR openat2 ()
 returns an error if unknown or conflicting flags are specified in

man/man2/openat2.2 argument, · line 144

Quoted 10 lines
man/man2/openat2.2 +9 -0
 .IR how.flags .
+.IP
+.BR openat2 ()
+also supports the below additional flags:
+.RS
+.TP
+.BR OPENAT2_REGULAR " (since Linux 7.2)"
+Only open the file specified by
+.I path
+if it is a regular file. If it is not a regular file,

Please use semantic newlines. See man-pages(7):

$ MANWIDTH=72 man man-pages | awk '/Use semantic newlines/,/^$/'
   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 boundaries.  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.

That is, break the line after period.

man/man2/openat2.2 argument, · line 147

Quoted 3 lines
man/man2/openat2.2 +3 -0
+.BR openat2 ()
+fails with the error
+.BR EFTYPE .

Hmmm, this error code is new to me.

	alx@devuan:~$ errno EFTYPE
	alx@devuan:~$ echo $?
	1
	alx@devuan:~$ man 3 errno | grep EFTYPE
	alx@devuan:~$ grepc EFTYPE /usr/include/
	alx@devuan:~$ 

I don't see it documented, nor defined under </usr/include>. Is this error code available in user space?
Is it a new error code?

man/man2/openat2.2 and an escape from the root during path resolution was detected. · line 491

Quoted 13 lines
man/man2/openat2.2 +6 -0
+.RE
 .TP
 .I mode
 This field specifies the
@@ -471,6 +484,12 @@ and an escape from the root during path resolution was detected.
 contains
 .BR RESOLVE_NO_XDEV ,
 and a path component crosses a mount point.
+.TP
+.B EFTYPE
+.I how.flags
+contains
+.BR OPENAT2_REGULAR

This should use B instead of BR. BR is for alternating Bold and Roman. B is for Bold.

Other than these minor formatting issues, and the question about EFTYPE, the patch looks good to me. Thanks!

Have a lovely day!
Alex

Quoted 7 lines
man/man2/openat2.2 +1 -0
+flag and the path is not a regular file.
 .SH STANDARDS
 Linux.
 .SH HISTORY
Signature · 1 line
2.53.0
Signature · 1 line
<https://www.alejandro-colomar.es>
#3 lore raw

Re: [PATCH 1/1] man/man2/openat2.2: Document OPENAT2_REGULAR flag

Hey Alex,

Quoted 39 lines · Alejandro Colomar

Hi Dorjoy,

Quoted 12 lines · Dorjoy Chowdhury
---
 man/man2/openat2.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
man/man2/openat2.2 +0 -0
index f0770f3a0..42ebf22ea 100644
@@ -133,6 +133,19 @@ argument,
 .BR openat2 ()
 returns an error if unknown or conflicting flags are specified in

man/man2/openat2.2 argument, · line 144

Quoted 10 lines
man/man2/openat2.2 +9 -0
 .IR how.flags .
+.IP
+.BR openat2 ()
+also supports the below additional flags:
+.RS
+.TP
+.BR OPENAT2_REGULAR " (since Linux 7.2)"
+Only open the file specified by
+.I path
+if it is a regular file. If it is not a regular file,

Please use semantic newlines. See man-pages(7):

$ MANWIDTH=72 man man-pages | awk '/Use semantic newlines/,/^$/'
   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 boundaries.  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.
Quoted 2 lines

That is, break the line after period.

Got it. Will fixup in v2. Thanks!

Quoted 13 lines

man/man2/openat2.2 argument, · line 147

Quoted 3 lines
man/man2/openat2.2 +3 -0
+.BR openat2 ()
+fails with the error
+.BR EFTYPE .

Hmmm, this error code is new to me.

        alx@devuan:~$ errno EFTYPE
        alx@devuan:~$ echo $?
        1
        alx@devuan:~$ man 3 errno | grep EFTYPE
        alx@devuan:~$ grepc EFTYPE /usr/include/
        alx@devuan:~$
Quoted 4 lines

I don't see it documented, nor defined under </usr/include>. Is this error code available in user space?
Is it a new error code?

Yes. This is a new error code added in the patch series i.e., if the path is not a regular file, then this new error code is returned from the system call. Does the new error code need to be included anywhere else for man pages?

Quoted 17 lines

man/man2/openat2.2 and an escape from the root during path resolution was detected. · line 491

Quoted 13 lines
man/man2/openat2.2 +6 -0
+.RE
 .TP
 .I mode
 This field specifies the
@@ -471,6 +484,12 @@ and an escape from the root during path resolution was detected.
 contains
 .BR RESOLVE_NO_XDEV ,
 and a path component crosses a mount point.
+.TP
+.B EFTYPE
+.I how.flags
+contains
+.BR OPENAT2_REGULAR

This should use B instead of BR. BR is for alternating Bold and Roman. B is for Bold.

Quoted 3 lines

Other than these minor formatting issues, and the question about EFTYPE, the patch looks good to me. Thanks!

Thanks. I will fixup.

Quoted 2 lines

Have a lovely day!

You too!

Regards,
Dorjoy

#4 lore raw

Re: [PATCH 1/1] man/man2/openat2.2: Document OPENAT2_REGULAR flag

Hey Dorjoy,

Quoted 18 lines · Dorjoy Chowdhury
Quoted 13 lines
Quoted 3 lines

+.BR openat2 ()
+fails with the error
+.BR EFTYPE .

Hmmm, this error code is new to me.

        alx@devuan:~$ errno EFTYPE
        alx@devuan:~$ echo $?
        1
        alx@devuan:~$ man 3 errno | grep EFTYPE
        alx@devuan:~$ grepc EFTYPE /usr/include/
        alx@devuan:~$
Quoted 4 lines

I don't see it documented, nor defined under </usr/include>. Is this error code available in user space?
Is it a new error code?

Quoted 4 lines

Yes. This is a new error code added in the patch series i.e., if the path is not a regular file, then this new error code is returned from the system call. Does the new error code need to be included anywhere else for man pages?

Yes, it should be documented in the errno(3) manual page.

It should also be added to glibc's <errno.h>, of course.

However, that can be done after the code has been merged to Linus's tree. But you could write the documentation for errno(3) already.

Cheers,
Alex

Signature · 1 line
<https://www.alejandro-colomar.es>