Document EFTYPE error code and OPENAT2_REGULAR flag
v2 cover Document EFTYPE error code and OPENAT2_REGULAR flag
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/
Changes in v2:
- new commit documenting EFTYPE error code (review by: Alejandro Colomar <[email protected]>)
- use semantic newline (review by: Alejandro Colomar <[email protected]>)
- use B instead of BR (review by: Alejandro Colomar <[email protected]>)
- v1 is at: https://lore.kernel.org/linux-man/[email protected]/
Regards,
Dorjoy
Dorjoy Chowdhury (2):
man/man3/errno.3: Document EFTYPE error code man/man2/openat2.2: Document OPENAT2_REGULAR flag
man/man2/openat2.2 | 20 ++++++++++++++++++++ man/man3/errno.3 | 3 +++ 2 files changed, 23 insertions(+)
Signature · 1 line
2.53.0
PATCH v2 1/2 man/man3/errno.3: Document EFTYPE error code
--- man/man3/errno.3 | 3 +++ 1 file changed, 3 insertions(+)
man/man3/errno.3 +3 -0
@@ -590,6 +590,9 @@ Invalid cross-device link (POSIX.1-2001). .TP .B EXFULL Exchange full. +.TP +.B EFTYPE +Wrong file type for the intended operation. .SH NOTES A common mistake is to do .P
Signature · 1 line
2.53.0
Re: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>
Thanks!
I will wait until glibc adds this error code to their <errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).
Have a lovely day!
Alex
Quoted 21 lines
--- man/man3/errno.3 | 3 +++ 1 file changed, 3 insertions(+)man/man3/errno.3 +3
-0@@ -590,6 +590,9 @@ Invalid cross-device link (POSIX.1-2001). .TP .B EXFULL Exchange full. +.TP +.B EFTYPE +Wrong file type for the intended operation. .SH NOTES A common mistake is to do .PSignature · 1 line
2.53.0
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
* Alejandro Colomar:
Quoted 7 lines
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>
Quoted 8 lines
Thanks!
Reviewed-by Alejandro Colomar <[email protected]>I will wait until glibc adds this error code to their <
errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).
I'm not sure where this is coming from. POSIX says EFTYPE was rejected in favor of ENOTTY.
Thanks,
Florian
Alejandro Colomar
maintainerRe: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
Hi Florian,
Quoted 11 lines · Florian Weimer
* Alejandro Colomar:
Quoted 9 lines
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Thanks!
Quoted 8 lines
Quoted 6 lines
Reviewed-by Alejandro Colomar <[email protected]>I will wait until glibc adds this error code to their <
errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).I'm not sure where this is coming from.
Here's a link to the thread:
<https://lore.kernel.org/linux-man/[email protected]/T/>
Quoted 2 lines
POSIX says EFTYPE was rejected
in favor of ENOTTY.
Could you please share a link to that?
Anyway, I guess ENOTTY would be inappropriate in this case. Although maybe a better error code could be devised; I don't know. This is why I wanted glibc involved in this discussion before this arrives to a Linux release. Thanks for the quick feedback!
Quoted 2 lines
Thanks,
Florian
Have a lovely day!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
* Alejandro Colomar:
Quoted 29 lines
Hi Florian,
Quoted 11 lines · Florian Weimer
* Alejandro Colomar:
Quoted 9 lines
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Thanks!
Quoted 8 lines
Quoted 6 lines
Reviewed-by Alejandro Colomar <[email protected]>I will wait until glibc adds this error code to their <
errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).I'm not sure where this is coming from.
Here's a link to the thread:
<https://lore.kernel.org/linux-man/[email protected]/T/>Quoted 2 lines
POSIX says EFTYPE was rejected
in favor of ENOTTY.
Quoted 6 lines
Could you please share a link to that?
Anyway, I guess ENOTTY would be inappropriate in this case. Although maybe a better error code could be devised; I don't know. This is why I wanted glibc involved in this discussion before this arrives to a Linux release. Thanks for the quick feedback!
It's in the Rationale for System Interfaces:
“
[EFTYPE]
This error code was proposed in earlier proposals as "Inappropriate operation for file type", meaning that the operation requested is not appropriate for the file specified in the function call. This code was proposed, although the same idea was covered by [ENOTTY], because the connotations of the name would be misleading. It was pointed out that the fcntl() function uses the error code [EINVAL] for this notion, and hence all instances of [EFTYPE] were changed to this code.
”
I replied on linux-fsdevel, too.
(It would be nice to submit patches introducing new error codes to linux-api with a subject mentioning the error code.)
Thanks,
Florian
Alejandro Colomar
maintainerRe: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
Hi Florian,
Quoted 52 lines · Florian Weimer
* Alejandro Colomar:
Quoted 29 lines
Hi Florian,
Quoted 11 lines · Florian Weimer
* Alejandro Colomar:
Quoted 9 lines
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Thanks!
Quoted 8 lines
Quoted 6 lines
Reviewed-by Alejandro Colomar <[email protected]>I will wait until glibc adds this error code to their <
errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).I'm not sure where this is coming from.
Here's a link to the thread:
<https://lore.kernel.org/linux-man/[email protected]/T/>Quoted 2 lines
POSIX says EFTYPE was rejected
in favor of ENOTTY.Quoted 6 lines
Could you please share a link to that?
Anyway, I guess ENOTTY would be inappropriate in this case. Although maybe a better error code could be devised; I don't know. This is why I wanted glibc involved in this discussion before this arrives to a Linux release. Thanks for the quick feedback!
It's in the Rationale for System Interfaces:
“
[EFTYPE]
This error code was proposed in earlier proposals as "Inappropriate operation for file type", meaning that the operation requested is not appropriate for the file specified in the function call. This code was proposed, although the same idea was covered by [ENOTTY], because the connotations of the name would be misleading. It was pointed out that thefcntl()function uses the error code [EINVAL] for this notion, and hence all instances of [EFTYPE] were changed to this code.
”
Quoted 1 line
I replied on linux-fsdevel, too.
Thanks!
Quoted 3 lines
(It would be nice to submit patches introducing new error codes to linux-api with a subject mentioning the error code.)
Thanks! I'll remember this advice for when receiving patches that add error codes.
Quoted 3 lines
Thanks,
Florian
Cheers,
Alex
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
Hi,
The OPENAT2_REGULAR and EFTYPE changes are in the 7.2-rc1 now I believe. I am not sure if it's the right time to merge the man-page changes now. I also don't know the whole flow so I'm asking. Do both of these need to be added to glibc manually or do these get pulled in from the uapi headers of linux into glibc automatically?
Regards,
Dorjoy
Quoted 76 lines · Alejandro Colomar
Hi Florian,
Quoted 52 lines · Florian Weimer
* Alejandro Colomar:
Quoted 29 lines
Hi Florian,
Quoted 11 lines · Florian Weimer
* Alejandro Colomar:
Quoted 9 lines
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Thanks!
Quoted 8 lines
Quoted 6 lines
Reviewed-by Alejandro Colomar <[email protected]>I will wait until glibc adds this error code to their <
errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).I'm not sure where this is coming from.
Here's a link to the thread:
<https://lore.kernel.org/linux-man/[email protected]/T/>Quoted 2 lines
POSIX says EFTYPE was rejected
in favor of ENOTTY.Quoted 6 lines
Could you please share a link to that?
Anyway, I guess ENOTTY would be inappropriate in this case. Although maybe a better error code could be devised; I don't know. This is why I wanted glibc involved in this discussion before this arrives to a Linux release. Thanks for the quick feedback!
It's in the Rationale for System Interfaces:
“
[EFTYPE]
This error code was proposed in earlier proposals as "Inappropriate operation for file type", meaning that the operation requested is not appropriate for the file specified in the function call. This code was proposed, although the same idea was covered by [ENOTTY], because the connotations of the name would be misleading. It was pointed out that thefcntl()function uses the error code [EINVAL] for this notion, and hence all instances of [EFTYPE] were changed to this code.
”Quoted 1 line
I replied on linux-fsdevel, too.
Thanks!
Quoted 3 lines
(It would be nice to submit patches introducing new error codes to linux-api with a subject mentioning the error code.)
Thanks! I'll remember this advice for when receiving patches that add error codes.
Quoted 3 lines
Thanks,
FlorianCheers,
Alex
Alejandro Colomar
maintainerRe: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code
Hi Dorjoy,
Quoted 5 lines · Dorjoy Chowdhury
Hi,
The
OPENAT2_REGULARand EFTYPE changes are in the 7.2-rc1 now I believe. I am not sure if it's the right time to merge the man-page changes now.
Yes, it is.
Quoted 1 line
I also don't know the whole flow so I'm asking.
If it's in an -rc, and you believe there won't be significant changes before release, we can merge the documentation already. If there's any last-minute change before the actual 7.2 release, just send some patch fixing the documentation.
Please keep all the CCs when sending the patches, and send in reply to the first message in this thread, so that it's easier to correlate them. Please also include CC tags in the trailer of the commit message.
Quoted 3 lines
Do both
of these need to be added to glibc manually or do these get pulled in from the uapi headers of linux into glibc automatically?
I don't know about this; someone from glibc will have to comment.
Have a lovely night!
Alex
Quoted 82 lines
Regards,
DorjoyQuoted 76 lines · Alejandro Colomar
Hi Florian,
Quoted 52 lines · Florian Weimer
* Alejandro Colomar:
Quoted 29 lines
Hi Florian,
Quoted 11 lines · Florian Weimer
* Alejandro Colomar:
Quoted 9 lines
[CC += libc-alpha]
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Thanks!
Quoted 8 lines
Quoted 6 lines
Reviewed-by Alejandro Colomar <[email protected]>I will wait until glibc adds this error code to their <
errno.h> before applying the patch. This means either you should write and send a patch to glibc (if so, please CC me), or you should ask them to add it themselves (if you're not comfortable writing glibc code).I'm not sure where this is coming from.
Here's a link to the thread:
<https://lore.kernel.org/linux-man/[email protected]/T/>Quoted 2 lines
POSIX says EFTYPE was rejected
in favor of ENOTTY.Quoted 6 lines
Could you please share a link to that?
Anyway, I guess ENOTTY would be inappropriate in this case. Although maybe a better error code could be devised; I don't know. This is why I wanted glibc involved in this discussion before this arrives to a Linux release. Thanks for the quick feedback!
It's in the Rationale for System Interfaces:
“
[EFTYPE]
This error code was proposed in earlier proposals as "Inappropriate operation for file type", meaning that the operation requested is not appropriate for the file specified in the function call. This code was proposed, although the same idea was covered by [ENOTTY], because the connotations of the name would be misleading. It was pointed out that thefcntl()function uses the error code [EINVAL] for this notion, and hence all instances of [EFTYPE] were changed to this code.
”Quoted 1 line
I replied on linux-fsdevel, too.
Thanks!
Quoted 3 lines
(It would be nice to submit patches introducing new error codes to linux-api with a subject mentioning the error code.)
Thanks! I'll remember this advice for when receiving patches that add error codes.
Quoted 3 lines
Thanks,
FlorianCheers,
Alex
Signature · 1 line
<https://www.alejandro-colomar.es>
PATCH v2 2/2 man/man2/openat2.2: Document OPENAT2_REGULAR flag
In reply to Dorjoy Chowdhury--- man/man2/openat2.2 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)
man/man2/openat2.2 +20 -0
@@ -133,6 +133,20 @@ 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 +485,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 +.B OPENAT2_REGULAR +flag and the path is not a regular file. .SH STANDARDS Linux. .SH HISTORY
Signature · 1 line
2.53.0
Re: [PATCH v2 2/2] man/man2/openat2.2: Document OPENAT2_REGULAR flag
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>
Thanks! Please ping when it's in Linus's tree, so that I'll merge.
Cheers,
Alex
Quoted 45 lines
--- man/man2/openat2.2 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)man/man2/openat2.2 +20
-0@@ -133,6 +133,20 @@ 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 +485,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 +.B OPENAT2_REGULAR +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 v2 2/2] man/man2/openat2.2: Document OPENAT2_REGULAR flag
Hey Alex,
Quoted 10 lines · Alejandro Colomar
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Reviewed-by Alejandro Colomar <[email protected]>Thanks! Please ping when it's in Linus's tree, so that I'll merge.
Thanks for reviewing. I should ping after it's in Linus's tree, meaning if it's in Linux 7.2 or Linux 7.2-rc1 ? Sorry I don't quite know the workflow. Also I guess I need to look into glibc after it gets into Linus's tree, right?
Regards,
Dorjoy
Alejandro Colomar
maintainerRe: [PATCH v2 2/2] man/man2/openat2.2: Document OPENAT2_REGULAR flag
Hey Dorjoy,
Quoted 9 lines · Dorjoy Chowdhury
Hey Alex,
Quoted 6 lines · Alejandro Colomar
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>
Quoted 7 lines
Quoted 4 lines
Reviewed-by Alejandro Colomar <[email protected]>Thanks! Please ping when it's in Linus's tree, so that I'll merge.
Thanks for reviewing. I should ping after it's in Linus's tree, meaning if it's in Linux 7.2 or Linux 7.2-rc1 ?
-rc1 should be fine. If anything is eventually reverted, we can fix it here; no problem.
Quoted 6 lines
Sorry I don't quite
know the workflow.Also I guess I need to look into glibc after it
gets into Linus's tree, right?
I guess once it's in -rc1, you can start discussing a patch there. I guess they won't merge anything until it's in the final release, but you could discuss it earlier, so that it lands there soon after Linux 7.2.
Have a lovely night!
Alex
Quoted 3 lines
Regards,
Dorjoy
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerRe: [PATCH v2 2/2] man/man2/openat2.2: Document OPENAT2_REGULAR flag
In reply to Dorjoy ChowdhuryHi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>
Thanks! I've applied the patch, with some minor changes and removals in the wording. It's already pushed.
Have a lovely day!
Alex
Quoted 46 lines
--- man/man2/openat2.2 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)man/man2/openat2.2 +20
-0@@ -133,6 +133,20 @@ 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 +485,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 +.B OPENAT2_REGULAR +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 v2 2/2] man/man2/openat2.2: Document OPENAT2_REGULAR flag
Hey Alex,
Quoted 9 lines · Alejandro Colomar
Hi Dorjoy,
Quoted 1 line · Dorjoy Chowdhury
Signed-off-by Dorjoy Chowdhury <[email protected]>Thanks! I've applied the patch, with some minor changes and removals in the wording. It's already pushed.
Thanks for fixing up and applying the patch!
Regards,
Dorjoy