Re: [PATCH] statx.2: document STATX_DIO_READ_ALIGN

Alejandro Colomar
2025-01-06T22:01:35Z

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

Hi Christoph,

On Mon, Jan 06, 2025 at 04:19:38PM +0100, Christoph Hellwig wrote:
> Document the new STATX_DIO_READ_ALIGN flag and the new
> stx_dio_read_offset_align field guarded by it.
>
> Signed-off-by: Christoph Hellwig <hch@lst.de>

Thanks for the patch! Please see some minor comments below.

Have a lovely night!
Alex

> ---
> man/man2/statx.2 | 27 ++++++++++++++++++++++++++-
> 1 file changed, 26 insertions(+), 1 deletion(-)
>
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index c5b5a28ec2f1..378bf363d93f 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -76,6 +76,9 @@ struct statx {
> __u32 stx_atomic_write_unit_min;
> __u32 stx_atomic_write_unit_max;
> __u32 stx_atomic_write_segments_max;
> +
> + /* File offset alignment for direct I/O reads */
> + __u32 stx_dio_read_offset_align;
> };
> .EE
> .in
> @@ -261,7 +264,7 @@ STATX_BTIME Want stx_btime
> STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME.
> It is deprecated and should not be used.
> STATX_MNT_ID Want stx_mnt_id (since Linux 5.8)
> -STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align
> +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align.
> (since Linux 6.1; support varies by filesystem)
> STATX_MNT_ID_UNIQUE Want unique stx_mnt_id (since Linux 6.8)
> STATX_SUBVOL Want stx_subvol
> @@ -270,6 +273,8 @@ STATX_WRITE_ATOMIC Want stx_atomic_write_unit_min,
> stx_atomic_write_unit_max,
> and stx_atomic_write_segments_max.
> (since Linux 6.11; support varies by filesystem)
> +STATX_DIO_READ_ALIGN Want stx_dio_read_offset_align.
> + (since Linux 6.14; support varies by filesystem)
> .TE
> .in
> .P
> @@ -467,6 +472,26 @@ This will only be nonzero if
> .I stx_dio_mem_align
> is nonzero, and vice versa.
> .TP
> +.I stx_dio_read_offset_align
> +The alignment (in bytes) required for file offsets and I/O segment lengths for
> +direct I/O reads
> +.RB ( O_DIRECT )
> +on this file. If zero the limit in

Please write poems, not prose. :)

In other words, new sentence, new line. 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.

> +.I
> +stx_dio_offset_align

We put the italics word in the same line as the .I.

> +applies for reads as well. If non-zero this value must be
> +smaller than
> +.I
> +stx_dio_offset_align
> +which must be provided by the file system.
> +This value does not affect the memory alignent in
> +.I stx_dio_mem_align .
> +.IP
> +.B STATX_DIO_READ_ALIGN
> +.I ( stx_dio_offset_align )

You probably meant .RI (roman-italics alternating).

> +support by filesystem;
> +it is supported by xfs since Linux 6.14.
> +.TP
> .I stx_subvol
> Subvolume number of the current file.
> .IP
> --
> 2.45.2
>
>

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

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