Re: RWF_DONTCACHE documentation

[Jens Axboe <axboe@kernel.dk>]

On 6/2/25 9:49 AM, Jens Axboe wrote:
> On 6/2/25 9:00 AM, Christoph Hellwig wrote:
>> Hi Jens,
>>
>> I just tried to reference RWF_DONTCACHE semantics in a standards
>> discussion, but it doesn't seem to be documented in the man pages
>> or in fact anywhere else I could easily find.  Could you please write
>> up the semantics for the preadv2/pwritev2 man page?
> 
> Sure, I can write up something for the man page.

Adding Darrick as well, as a) he helped review the patches, and b) his
phrasing is usually much better than mine.

Anyway, here's my first attempt:

diff --git a/man/man2/readv.2 b/man/man2/readv.2
index c3b0a7091619..2e23e2f15cf4 100644
--- a/man/man2/readv.2
+++ b/man/man2/readv.2
@@ -301,6 +301,28 @@ or their equivalent flags and system calls are used
 .B RWF_SYNC
 is specified for
 .BR pwritev2 ()).
+.TP
+.BR RWF_DONTCACHE " (since Linux 6.14)"
+Reads or writes to a regular file will prune instantiated page cache content
+when the operation completes. This is different than normal buffered I/O,
+where the data usually remains in cache until such time that it gets reclaimed
+due to memory pressure. If ranges of the read or written I/O was already in
+cache before this read or write, then those range will not be pruned at I/O
+completion time. Additionally, any range dirtied by a write operation with
+.B RWF_DONTCACHE
+set will get kicked off for writeback. This is similar to calling
+.BR sync_file_range (2)
+with
+.IR SYNC_FILE_RANGE_WRITE
+to start writeback on the given range.
+.B RWF_DONTCACHE
+is a hint, or best effort, where no hard guarantees are given on the state of
+the page cache once the operation completes. Note: file systems must support
+this feature as well. If used on a file system or block device that doesn't
+support it will return \-1 and
+.I errno
+will be set to
+.B EOPNOTSUPP .
 .SH RETURN VALUE
 On success,
 .BR readv (),
@@ -368,6 +390,12 @@ value from
 .I statx.
 .TP
 .B EOPNOTSUPP
+.B RWF_DONTCACHE
+was set in
+.IR flags
+and the file doesn't support it.
+.TP
+.B EOPNOTSUPP
 An unknown flag is specified in
 .IR flags .
 .SH VERSIONS

-- 
Jens Axboe