[PATCH] man2/openat2.2: add RESOLVE_CACHED

[Jens Axboe <axboe@kernel.dk>]

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