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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Jens

Thanks for the revised patch. Just some minor comments below.

On 2/20/21 8:17 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>
> 
> ---
> 
> Sending a v2 of this one, as the kernel side patches are queued up
> for 5.12 inclusion.
> 
> diff --git a/man2/openat2.2 b/man2/openat2.2
> index 3bda20620574..37e70c43de6d 100644
> --- a/man2/openat2.2
> +++ b/man2/openat2.2
> @@ -385,6 +385,17 @@ 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
> +Make the open operation fail unless all path components are already present
> +in the kernels lookup cache.

s/kernels/kernel's/

> +If any kind of revalidation or I/O is needed to satisfy the lookup,
> +.BR openat2 ()
> +fails with the error
> +.B EAGAIN.

.BR EAGAIN .

> +This is useful in providing a fast path open that can be performed without

s/fast path open/fast-path open/

> +resorting to thread offload, or other mechanisms that an application might
> +use to offload slower operations.
>  .RE
>  .IP
>  If any bits other than those listed above are set in
> @@ -421,6 +432,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.

Maybe:
s/cached
 /using only cached information/
?

> +The caller should retry without
> +.B RESOLVE_CACHED
> +set in
> +.I how.resolve

.IR 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/