OPENAT2_REGULAR flag documentation
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
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
@@ -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
Alejandro Colomar
maintainerRe: [PATCH 1/1] man/man2/openat2.2: Document OPENAT2_REGULAR flag
Hi Dorjoy,
Quoted 12 lines · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>--- man/man2/openat2.2 | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)man/man2/openat2.2 +0
-0@@ -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 HISTORYSignature · 1 line
2.53.0
Signature · 1 line
<https://www.alejandro-colomar.es>
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
Signed-off-by Dorjoy Chowdhury <[email protected]>--- man/man2/openat2.2 | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)man/man2/openat2.2 +0
-0@@ -133,6 +133,19 @@ argument, .BR openat2 () returns an error if unknown or conflicting flags are specified inman/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_REGULARThis 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
Alejandro Colomar
maintainerRe: [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>