Re: RWF_DONTCACHE documentation

[Jens Axboe <axboe@kernel.dk>]

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