[PATCH v2] man/man2/readv.2: Document RWF_DONTCACHE

[Alejandro Colomar <alx@kernel.org>]

Add a description of the RWF_DONTCACHE IO flag, which tells the kernel
that any page cache instantiated by this IO, should be dropped when the
operation has completed.

Reported-by: Christoph Hellwig <hch@infradead.org>
Cc: "Darrick J. Wong" <djwong@kernel.org>
Cc: Johannes Thumshirn <Johannes.Thumshirn@wdc.com>
Cc: linux-fsdevel@vger.kernel.org
Co-authored-by: Jens Axboe <axboe@kernel.dk>
[alx: editorial improvements; srcfix, ffix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Jens,

Here's the patch.  We don't need to paste it into writev(2), because
writev(2) is documented in readv(2); they're the same page.

Thanks for the commit message!

Please sign it, if you like it.


Have a lovely day!
Alex


 man/man2/readv.2 | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/man/man2/readv.2 b/man/man2/readv.2
index c3b0a7091..5b2de3025 100644
--- a/man/man2/readv.2
+++ b/man/man2/readv.2
@@ -301,6 +301,39 @@ .SS preadv2() and pwritev2()
 .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
+were already in cache before this read or write,
+then those ranges will not be pruned at I/O completion time.
+.IP
+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
+.I 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.
+.IP
+If used on a file system or block device
+that doesn't support it,
+it will return \-1, and
+.I errno
+will be set to
+.BR EOPNOTSUPP .
 .SH RETURN VALUE
 On success,
 .BR readv (),
@@ -368,6 +401,12 @@ .SH ERRORS
 .I statx.
 .TP
 .B EOPNOTSUPP
+.B RWF_DONTCACHE
+was set in
+.I flags
+and the file doesn't support it.
+.TP
+.B EOPNOTSUPP
 An unknown flag is specified in
 .IR flags .
 .SH VERSIONS

Range-diff against v1:
-:  --------- > 1:  9e1f1b2d6 man/man2/readv.2: Document RWF_DONTCACHE

base-commit: aa88bcfabc52b7d4ef52a8e5a4be0260676d81bc
prerequisite-patch-id: b91cde16f48eeae2a44bae89e8cbb41d9034a865
prerequisite-patch-id: 0c0617b91c32758d64e6e8b2f8ddd434199d842b
prerequisite-patch-id: 02385b38b2a5ec5c04a468e888b1bc14aace9ec6
prerequisite-patch-id: 10e6a0e6e2edd5e74767af533958389454f72ab5
prerequisite-patch-id: 2dc3d94ce9d6e965182437c822479f55ec67da07
prerequisite-patch-id: 9e5fef3be8cc4d5d2828c415cf5a923e055640fc
prerequisite-patch-id: 3de1fc513b71447bb13ac740474138c80e3a463e
-- 
2.50.1