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:
signature.asc
Description: PGP signature
