man2/openat2.2: add RESOLVE_CACHED
PATCH 1/1 man2/openat2.2: add RESOLVE_CACHED
RESOLVE_CACHED allows an application to attempt a cache-only open of a file. If this isn't possible, the request will fail with -1/EAGAIN and the caller should retry without RESOLVE_CACHED set. This will generally happen from a different context, where a slower open operation can be performed.
---
First attempt at this, fully expecting the phrasing to require some massaging.
Also see: https://lore.kernel.org/linux-fsdevel/[email protected]/T/
man2/openat2.2 +17 -0
@@ -385,6 +385,15 @@ This may occur if, for example, a system pathname that is used by an application is modified (e.g., in a new distribution release) so that a pathname component (now) contains a bind mount. +.TP +.B RESOLVE_CACHED +Fail path resolution, unless all components needed already exist in the +lookup cache. If any kind of revalidation or IO is needed to satisfy the +lookup, then fail the open attempt with +.B EAGAIN. +This is useful in providing a fast path open that can be performed without +resorting to thread offload, or other mechanism that an application might +use to offload slower operations. .RE .IP If any bits other than those listed above are set in
@@ -421,6 +430,14 @@ The caller may choose to retry the .BR openat2 () call. .TP +.B EAGAIN +.BR RESOLVE_CACHED +was set, and the open operation cannot be performed cached. The caller should +retry without +.B RESOLVE_CACHED +set in +.I how.resolve +.TP .B EINVAL An unknown flag or invalid value was specified in .IR how .
Signature · 1 line
Jens Axboe
Hi Jens,
Quoted 7 lines · Jens Axboe
RESOLVE_CACHEDallows an application to attempt a cache-only open of a file. If this isn't possible, the request will fail with -1/EAGAIN and the caller should retry withoutRESOLVE_CACHEDset. This will generally happen from a different context, where a slower open operation can be performed.Signed-off-by Jens Axboe <[email protected]>
I take it that this feature is not yet merged into the kernel? (At least, I couldn't grep RESOLVE_CACHED in current kernel sources.)
Quoted 13 lines
---
First attempt at this, fully expecting the phrasing to require some massaging.
Also see: https://lore.kernel.org/linux-fsdevel/[email protected]/T/
man2/openat2.2 +0
-0
man2/openat2.2 This may occur if, for example, · line 390
Quoted 6 lines
man2/openat2.2 +3
-0@@ -385,6 +385,15 @@ This may occur if, for example, a system pathname that is used by an application is modified (e.g., in a new distribution release) so that a pathname component (now) contains a bind mount. +.TP +.B RESOLVE_CACHED +Fail path resolution, unless all components needed already exist in the
I think "Fail path resolution" needs some clarification.
Maybe something like:
[[
Make the open operation fail unless all path components are already present in the kernel's lookup cache. ]]
?
man2/openat2.2 This may occur if, for example, · line 391
Quoted 1 line
man2/openat2.2 +1
-0+lookup cache. If any kind of revalidation or IO is needed to satisfy the
^
Please start new sentences on new lines. Using such-called "semantic newlines" makes for cleaner future patches.
man2/openat2.2 This may occur if, for example, · line 392
Quoted 1 line
man2/openat2.2 +1
-0+lookup, then fail the open attempt with
"fail the open attempt with"
==>
.BR openat2 ()
fails with the error
Quoted 8 lines
man2/openat2.2 +4
-0+.B EAGAIN. +This is useful in providing a fast path open that can be performed without +resorting to thread offload, or other mechanism that an application might +use to offload slower operations. .RE .IP If any bits other than those listed above are set in
man2/openat2.2 The caller may choose to retry the · line 435
Quoted 6 lines
man2/openat2.2 +3
-0@@ -421,6 +430,14 @@ The caller may choose to retry the .BR openat2 () call. .TP +.B EAGAIN +.BR RESOLVE_CACHED +was set, and the open operation cannot be performed cached. The caller should
semantic newline
man2/openat2.2 The caller may choose to retry the · line 443
Quoted 8 lines
man2/openat2.2 +5
-0+retry without +.B RESOLVE_CACHED +set in +.I how.resolve +.TP .B EINVAL An unknown flag or invalid value was specified in .IR how .
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 9 lines · Michael Kerrisk (man-pages)
Hi Jens,
Quoted 6 lines · Jens Axboe
RESOLVE_CACHEDallows an application to attempt a cache-only open of a file. If this isn't possible, the request will fail with -1/EAGAIN and the caller should retry withoutRESOLVE_CACHEDset. This will generally happen from a different context, where a slower open operation can be performed.
Quoted 5 lines
Quoted 1 line
Signed-off-by Jens Axboe <[email protected]>I take it that this feature is not yet merged into the kernel? (At least, I couldn't grep
RESOLVE_CACHEDin current kernel sources.)
Right - see the email thread linked in the posting. Should be landing in 5.12 though, and I just wanted to hash out the details of the man page upfront so it'd be ready to go as well. Sorry if that wasn't 100% clear!
Quoted 19 lines
Quoted 10 lines
First attempt at this, fully expecting the phrasing to require some massaging.
Also see: https://lore.kernel.org/linux-fsdevel/[email protected]/T/
man2/openat2.2 +0
-0man2/openat2.2 This may occur if, for example, · line 390
Quoted 6 lines
man2/openat2.2 +3
-0@@ -385,6 +385,15 @@ This may occur if, for example, a system pathname that is used by an application is modified (e.g., in a new distribution release) so that a pathname component (now) contains a bind mount. +.TP +.B RESOLVE_CACHED +Fail path resolution, unless all components needed already exist in theI think "Fail path resolution" needs some clarification.
Quoted 6 lines
Maybe something like:
[[
Make the open operation fail unless all path components are already present in the kernel's lookup cache. ]]
?
That is cleared indeed, I'll rephrase that one.
Quoted 4 lines
man2/openat2.2 This may occur if, for example, · line 391
Quoted 1 line
man2/openat2.2 +1
-0+lookup cache. If any kind of revalidation or IO is needed to satisfy the^Please start new sentences on new lines. Using such-called "semantic newlines" makes for cleaner future patches.
OK
Quoted 6 lines
man2/openat2.2 This may occur if, for example, · line 392
Quoted 1 line
man2/openat2.2 +1
-0+lookup, then fail the open attempt with"fail the open attempt with"
==>
.BR openat2 ()
fails with the error
Fixed up
Quoted 8 lines
Quoted 8 lines
man2/openat2.2 +4
-0+.B EAGAIN. +This is useful in providing a fast path open that can be performed without +resorting to thread offload, or other mechanism that an application might +use to offload slower operations. .RE .IP If any bits other than those listed above are set in@@ -421,6 +430,14 @@ The caller may choose to retry the
Quoted 8 lines
man2/openat2.2 The caller may choose to retry the · line 435
Quoted 6 lines
man2/openat2.2 +3
-0.BR openat2 () call. .TP +.B EAGAIN +.BR RESOLVE_CACHED +was set, and the open operation cannot be performed cached. The caller shouldsemantic newline
OK
Thanks Michael, I'll make the edits.
Signature · 1 line
Jens Axboe