* [PATCH] man2/openat2.2: add RESOLVE_CACHED
@ 2020-12-17 21:18 Jens Axboe
2020-12-23 12:41 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 3+ messages in thread
From: Jens Axboe @ 2020-12-17 21:18 UTC (permalink / raw)
To: linux-man; +Cc: Michael Kerrisk-manpages
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.
Signed-off-by: Jens Axboe <axboe@kernel.dk>
---
First attempt at this, fully expecting the phrasing to require some
massaging.
Also see: https://lore.kernel.org/linux-fsdevel/20201217161911.743222-1-axboe@kernel.dk/T/
diff --git a/man2/openat2.2 b/man2/openat2.2
index 3bda20620574..282c13e2df96 100644
--- a/man2/openat2.2
+++ b/man2/openat2.2
@@ -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 .
--
Jens Axboe
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] man2/openat2.2: add RESOLVE_CACHED
2020-12-17 21:18 [PATCH] man2/openat2.2: add RESOLVE_CACHED Jens Axboe
@ 2020-12-23 12:41 ` Michael Kerrisk (man-pages)
2020-12-23 14:04 ` Jens Axboe
0 siblings, 1 reply; 3+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-23 12:41 UTC (permalink / raw)
To: Jens Axboe, linux-man; +Cc: mtk.manpages
Hi Jens,
On 12/17/20 10:18 PM, Jens Axboe wrote:
> 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.
>
> Signed-off-by: Jens Axboe <axboe@kernel.dk>
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.)
>
> ---
>
> First attempt at this, fully expecting the phrasing to require some
> massaging.
>
> Also see: https://lore.kernel.org/linux-fsdevel/20201217161911.743222-1-axboe@kernel.dk/T/
>
> diff --git a/man2/openat2.2 b/man2/openat2.2
> index 3bda20620574..282c13e2df96 100644
> --- a/man2/openat2.2
> +++ b/man2/openat2.2
> @@ -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.
]]
?
> +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.
> +lookup, then fail the open attempt with
"fail the open attempt with"
==>
.BR openat2 ()
fails with the error
> +.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
semantic newline
> +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
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] man2/openat2.2: add RESOLVE_CACHED
2020-12-23 12:41 ` Michael Kerrisk (man-pages)
@ 2020-12-23 14:04 ` Jens Axboe
0 siblings, 0 replies; 3+ messages in thread
From: Jens Axboe @ 2020-12-23 14:04 UTC (permalink / raw)
To: Michael Kerrisk (man-pages), linux-man
On 12/23/20 5:41 AM, Michael Kerrisk (man-pages) wrote:
> Hi Jens,
>
> On 12/17/20 10:18 PM, Jens Axboe wrote:
>> 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.
>>
>> Signed-off-by: Jens Axboe <axboe@kernel.dk>
>
> 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.)
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!
>> First attempt at this, fully expecting the phrasing to require some
>> massaging.
>>
>> Also see: https://lore.kernel.org/linux-fsdevel/20201217161911.743222-1-axboe@kernel.dk/T/
>>
>> diff --git a/man2/openat2.2 b/man2/openat2.2
>> index 3bda20620574..282c13e2df96 100644
>> --- a/man2/openat2.2
>> +++ b/man2/openat2.2
>> @@ -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.
> ]]
> ?
That is cleared indeed, I'll rephrase that one.
>> +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
>> +lookup, then fail the open attempt with
>
> "fail the open attempt with"
> ==>
> .BR openat2 ()
> fails with the error
Fixed up
>> +.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
>
> semantic newline
OK
Thanks Michael, I'll make the edits.
--
Jens Axboe
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-12-23 14:05 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-17 21:18 [PATCH] man2/openat2.2: add RESOLVE_CACHED Jens Axboe
2020-12-23 12:41 ` Michael Kerrisk (man-pages)
2020-12-23 14:04 ` Jens Axboe
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.