Skip to contentSkip to conversation

Document EFTYPE error code and OPENAT2_REGULAR flag

PATCH In review Dorjoy Chowdhury 3 participants 15 messages Apr 26 – Jul 2

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index a070dabca..ed3578b07 100644
@@ -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
maintainer Reviewed-by on v2 1/2
#2 lore raw

Re: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code

[CC += libc-alpha]

Hi Dorjoy,

Quoted 1 line · Dorjoy Chowdhury

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
index a070dabca..ed3578b07 100644
@@ -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
Signature · 1 line
<https://www.alejandro-colomar.es>
#3 lore raw

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
Quoted 8 lines

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).

I'm not sure where this is coming from. POSIX says EFTYPE was rejected in favor of ENOTTY.

Thanks,
Florian

#4 lore raw

Re: [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

Thanks!

Quoted 8 lines
Quoted 6 lines

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>
#5 lore raw

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

Thanks!

Quoted 8 lines
Quoted 6 lines

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

#6 lore raw

Re: [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

Thanks!

Quoted 8 lines
Quoted 6 lines

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.
”

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>
#7 lore raw

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

Thanks!

Quoted 8 lines
Quoted 6 lines

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.
”

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

--
<https://www.alejandro-colomar.es>

#8 lore raw

Re: [PATCH v2 1/2] man/man3/errno.3: Document EFTYPE error code

Hi Dorjoy,

Quoted 5 lines · Dorjoy Chowdhury

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.

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,
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

Thanks!

Quoted 8 lines
Quoted 6 lines

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.
”

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

--
<https://www.alejandro-colomar.es>

Signature · 1 line
<https://www.alejandro-colomar.es>
#9 lore raw

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
index f0770f3a0..ea3d9ac7b 100644
@@ -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
maintainer Reviewed-by on v2 2/2
#10 lore raw

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

Hi Dorjoy,

Quoted 1 line · Dorjoy Chowdhury

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
index f0770f3a0..ea3d9ac7b 100644
@@ -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
Signature · 1 line
<https://www.alejandro-colomar.es>
#11 lore raw

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

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

#12 lore raw

Re: [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
Quoted 7 lines
Quoted 4 lines

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>
#13 lore raw

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

In reply to Dorjoy Chowdhury

Hi Dorjoy,

Quoted 1 line · Dorjoy Chowdhury

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
index f0770f3a0..ea3d9ac7b 100644
@@ -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
Signature · 1 line
<https://www.alejandro-colomar.es>
#14 lore raw

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

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