Re: [PATCH] man2/openat2.2: add RESOLVE_CACHED

[Jens Axboe <axboe@kernel.dk>]

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