RWF_DONTCACHE documentation

RWF_DONTCACHE documentation

[Christoph Hellwig]

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?

Re: RWF_DONTCACHE documentation

[Jens Axboe]

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.

-- 
Jens Axboe

Re: RWF_DONTCACHE documentation

[Jens Axboe]

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

Re: RWF_DONTCACHE documentation

[Johannes Thumshirn]

On 02.06.25 17:53, 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.
> 

Hi Jens,

Small sidetrack here. What happened to the ext4 and btrfs support of 
RWF_DONTCACHE? I remember seeing your series having ext4 and btrfs 
support as well but in current master only xfs is setting FOP_DONTCACHE.

What did I miss?

Thanks,
	Johannes

Re: RWF_DONTCACHE documentation

[Jens Axboe]

On 6/3/25 12:20 AM, Johannes Thumshirn wrote:
> On 02.06.25 17:53, 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.
>>
> 
> Hi Jens,
> 
> Small sidetrack here. What happened to the ext4 and btrfs support of 
> RWF_DONTCACHE? I remember seeing your series having ext4 and btrfs 
> support as well but in current master only xfs is setting FOP_DONTCACHE.

The btrfs support got queued up, that's all I know on that front. For
ext4, it needed a bit of a hack [1] and there was some chatter on
converting the write side to iomap, which would eliminate the need for
that hack. The last fs patches I had on top of the core bits was:

https://git.kernel.dk/cgit/linux/log/?h=buffered-uncached-fs.11

in case you or someone else wants to pursue those parts.

[1] https://git.kernel.dk/cgit/linux/commit/?h=buffered-uncached-fs.11&id=92df0ef308d0bfbbc26a7efa1d571a506fd8fee3

-- 
Jens Axboe

Re: RWF_DONTCACHE documentation

[Johannes Thumshirn]

On 03.06.25 15:10, Jens Axboe wrote:
> On 6/3/25 12:20 AM, Johannes Thumshirn wrote:
>> On 02.06.25 17:53, 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.
>>>
>>
>> Hi Jens,
>>
>> Small sidetrack here. What happened to the ext4 and btrfs support of
>> RWF_DONTCACHE? I remember seeing your series having ext4 and btrfs
>> support as well but in current master only xfs is setting FOP_DONTCACHE.
> 
> The btrfs support got queued up, that's all I know on that front. For
> ext4, it needed a bit of a hack [1] and there was some chatter on
> converting the write side to iomap, which would eliminate the need for
> that hack. The last fs patches I had on top of the core bits was:
> 
> https://git.kernel.dk/cgit/linux/log/?h=buffered-uncached-fs.11
> 
> in case you or someone else wants to pursue those parts.
> 
> [1] https://git.kernel.dk/cgit/linux/commit/?h=buffered-uncached-fs.11&id=92df0ef308d0bfbbc26a7efa1d571a506fd8fee3
> 

Thanks

Re: RWF_DONTCACHE documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4349 bytes --]

Hi Jens,

On Mon, Jun 02, 2025 at 02:54:01PM -0600, Jens Axboe wrote:
> 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,

Please use semantic newlines, even for drafts; it makes editing later
much easier.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.

And a quote from Brian W. Kernighan about preparing documents:

    Brian W. Kernighan, 1974 [UNIX For Beginners]:
    
    [
    Hints for Preparing Documents
    
    Most documents go through several versions
    (always more than you expected)
    before they are finally finished.
    Accordingly,
    you should do whatever possible
    to make the job of changing them easy.
    
    First,
    when you do the purely mechanical operations of typing,
    type so subsequent editing will be easy.
    Start each sentence on a new line.
    Make lines short,
    and break lines at natural places,
    such as after commas and semicolons,
    rather than randomly.
    Since most people change documents
    by rewriting phrases and
    adding, deleting and rearranging sentences,
    these precautions simplify any editing you have to do later.
    ]

> +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

s/was/were/

> +cache before this read or write, then those range will not be pruned at I/O

s/range/&s/

> +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.

I'd remove the sentence above.  It's redundant with the following one.
Also, to give it more visibility, and because it's not connected with
the preceding text, I'd move it to a new paragraph with '.IP'.

Other than this comments, the text looks good to me.  Thanks!


Have a lovely day!
Alex

> +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
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: RWF_DONTCACHE documentation

[Jens Axboe]

>
> Hi Jens,
>
> On Mon, Jun 02, 2025 at 02:54:01PM -0600, Jens Axboe wrote:
> > 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,
>
> Please use semantic newlines, even for drafts; it makes editing later
> much easier.  See man-pages(7):
>
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
>    Use semantic newlines
>      In the source of a manual page, new sentences should be started on
>      new lines, long sentences should be split  into  lines  at  clause
>      breaks  (commas,  semicolons, colons, and so on), and long clauses
>      should be split at phrase boundaries.  This convention,  sometimes
>      known as "semantic newlines", makes it easier to see the effect of
>      patches, which often operate at the level of individual sentences,
>      clauses, or phrases.
>
> And a quote from Brian W. Kernighan about preparing documents:
>
>     Brian W. Kernighan, 1974 [UNIX For Beginners]:
>
>     [
>     Hints for Preparing Documents
>
>     Most documents go through several versions
>     (always more than you expected)
>     before they are finally finished.
>     Accordingly,
>     you should do whatever possible
>     to make the job of changing them easy.
>
>     First,
>     when you do the purely mechanical operations of typing,
>     type so subsequent editing will be easy.
>     Start each sentence on a new line.
>     Make lines short,
>     and break lines at natural places,
>     such as after commas and semicolons,
>     rather than randomly.
>     Since most people change documents
>     by rewriting phrases and
>     adding, deleting and rearranging sentences,
>     these precautions simplify any editing you have to do later.
>     ]
>
> > +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
>
> s/was/were/
>
> > +cache before this read or write, then those range will not be pruned at I/O
>
> s/range/&s/
>
> > +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.
>
> I'd remove the sentence above.  It's redundant with the following one.
> Also, to give it more visibility, and because it's not connected with
> the preceding text, I'd move it to a new paragraph with '.IP'.
>
> Other than this comments, the text looks good to me.  Thanks!

I kind of walked away from this one as I didn't have time or motivation
to push it forward. FWIW, if you want to massage it into submission
that'd be greatly appreciated. I'm not a regular man page contributor
nor do I aim to be, but I do feel like we should this feature
documented.

-- 
Jens Axboe

Re: RWF_DONTCACHE documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2889 bytes --]

Hi Jens,

On Mon, Aug 11, 2025 at 11:25:52AM -0600, Jens Axboe wrote:
> > Other than this comments, the text looks good to me.  Thanks!
> 
> I kind of walked away from this one as I didn't have time or motivation
> to push it forward. FWIW, if you want to massage it into submission
> that'd be greatly appreciated. I'm not a regular man page contributor
> nor do I aim to be, but I do feel like we should this feature
> documented.

I understand your lack of interest in writing quality man(7) source code
if that means iterations of patches.  However, you may find the build
system helpful to find some of the most obvious mistakes by yourself.
This might help you in future patches.

	$ make lint-man build-all -R
	TROFF		.tmp/man/man2/readv.2.cat.set
	an.tmac:.tmp/man/man2/readv.2:316: style: .IR expects at least 2 arguments, got 1
	an.tmac:.tmp/man/man2/readv.2:395: style: .IR expects at least 2 arguments, got 1
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/catman/troff.mk:66: .tmp/man/man2/readv.2.cat.set] Error 1
	make: *** Deleting file '.tmp/man/man2/readv.2.cat.set'

Here's a diff with all the issues I raised fixed.  Please add a commit
message, and I'll apply it.


Have a lovely day!
Alex


diff --git i/man/man2/readv.2 w/man/man2/readv.2
index c3b0a7091..5b2de3025 100644
--- i/man/man2/readv.2
+++ w/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



> 
> -- 
> Jens Axboe
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: RWF_DONTCACHE documentation

[Jens Axboe]

On 8/17/25 10:01 PM, Alejandro Colomar wrote:
> Hi Jens,
> 
> On Mon, Aug 11, 2025 at 11:25:52AM -0600, Jens Axboe wrote:
>>> Other than this comments, the text looks good to me.  Thanks!
>>
>> I kind of walked away from this one as I didn't have time or motivation
>> to push it forward. FWIW, if you want to massage it into submission
>> that'd be greatly appreciated. I'm not a regular man page contributor
>> nor do I aim to be, but I do feel like we should this feature
>> documented.
> 
> I understand your lack of interest in writing quality man(7) source code
> if that means iterations of patches.  However, you may find the build

It's not really lack of interest, it's just that there's only so much
time and the idea of a back and forth on documentation isn't high on the
list :-)

> system helpful to find some of the most obvious mistakes by yourself.
> This might help you in future patches.
> 
> 	$ make lint-man build-all -R
> 	TROFF		.tmp/man/man2/readv.2.cat.set
> 	an.tmac:.tmp/man/man2/readv.2:316: style: .IR expects at least 2 arguments, got 1
> 	an.tmac:.tmp/man/man2/readv.2:395: style: .IR expects at least 2 arguments, got 1
> 	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/catman/troff.mk:66: .tmp/man/man2/readv.2.cat.set] Error 1
> 	make: *** Deleting file '.tmp/man/man2/readv.2.cat.set'

I'll remember for next time!

> Here's a diff with all the issues I raised fixed.  Please add a commit
> message, and I'll apply it.

Beautiful, thank you! Maybe paste the same section into writev.2 as
well? For commit message, something ala

man/man2/readv.2: document RWF_DONTCACHE

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.

?

-- 
Jens Axboe

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

[Alejandro Colomar]

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3408 bytes --]

Oops, I forgot to sent to linux-man@.

On Mon, Sep 01, 2025 at 04:22:06PM +0200, Alejandro Colomar wrote:
> 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
> 

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Jens Axboe]

On 9/1/25 8:22 AM, Alejandro Colomar wrote:
> 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.

Thanks for doing this!


Signed-off-by: Jens Axboe <axboe@kernel.dk>
-- 
Jens Axboe

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

[Christoph Hellwig]

Looks good:

Reviewed-by: Christoph Hellwig <hch@lst.de>