Re: [PATCH] statx.2: document STATX_DIO_READ_ALIGN

Darrick J. Wong
2025-01-08T17:27:43Z

On Wed, Jan 08, 2025 at 09:59:00AM +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>
> ---
> man/man2/statx.2 | 26 +++++++++++++++++++++++++-
> 1 file changed, 25 insertions(+), 1 deletion(-)
>
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index c5b5a28ec2f1..8ef6a1cfb1c0 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,25 @@ 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

nit: add a comma here (really a dependent clause) to make it clearer
that 'zero' isn't being used as a verb here:

"If zero, the limit in..."

> +.I stx_dio_offset_align
> +applies for reads as well.
> +If non-zero this value must be smaller than

Same here.

"If non-zero, this value..."

With that fixed,
Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>

--D

> +.I stx_dio_offset_align
> +which must be provided by the file system.
> +The memory alignment in
> +.I stx_dio_mem_align
> +is not affected by this value.
> +.IP
> +.B STATX_DIO_READ_ALIGN
> +.RI ( stx_dio_offset_align )
> +is supported by xfs on regular files since Linux 6.14.
> +.TP
> .I stx_subvol
> Subvolume number of the current file.
> .IP
> --
> 2.45.2
>
>