From: John Garry Date: Thu, 19 Jun 2025 15:44:55 +0000 (+0000) Subject: man/man2/statx.2: Add stx_atomic_write_unit_max_opt X-Git-Tag: man-pages-6.15~17 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=684b9001d0cd0367daad5d7a7c9e3b7c040e0250;p=thirdparty%2Fman-pages.git man/man2/statx.2: Add stx_atomic_write_unit_max_opt XFS supports atomic writes - or untorn writes - based on two different methods: - HW offload in the disk - FS method based on out-of-place writes The value reported in stx_atomic_write_unit_max will be the max size of the FS-based method. The max atomic write unit size of the FS-based atomic writes will typically be much larger than what is capable from the HW offload. However, FS-based atomic writes will also be typically much slower. Advertise this HW offload size limit to the user in a new statx member, stx_atomic_write_unit_max_opt. We want STATX_WRITE_ATOMIC to get this new member in addition to the already-existing members, so mention that a value of 0 in stx_atomic_write_unit_max_opt means that stx_atomic_write_unit_max holds this optimised limit. Linux will zero unused statx members, so stx_atomic_write_unit_max_opt will always hold 0 for older kernel versions which do not support this FS-based atomic write method (for XFS). Signed-off-by: John Garry Message-ID: <20250619154455.321848-3-john.g.garry@oracle.com> Signed-off-by: Alejandro Colomar --- diff --git a/man/man2/statx.2 b/man/man2/statx.2 index 273d80711..07ac60b3c 100644 --- a/man/man2/statx.2 +++ b/man/man2/statx.2 @@ -74,6 +74,9 @@ struct statx { \& /* File offset alignment for direct I/O reads */ __u32 stx_dio_read_offset_align; +\& + /* Direct I/O atomic write max opt limit */ + __u32 stx_atomic_write_unit_max_opt; }; .EE .in @@ -266,7 +269,8 @@ STATX_SUBVOL Want stx_subvol (since Linux 6.10; support varies by filesystem) STATX_WRITE_ATOMIC Want stx_atomic_write_unit_min, stx_atomic_write_unit_max, - and stx_atomic_write_segments_max. + stx_atomic_write_segments_max, + and stx_atomic_write_unit_max_opt. (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) @@ -514,6 +518,21 @@ is supported on block devices since Linux 6.11. The support on regular files varies by filesystem; it is supported by xfs and ext4 since Linux 6.13. .TP +.I stx_atomic_write_unit_max_opt +The maximum size (in bytes) which is +optimised for writes issued with torn-write protection. +If non-zero, +this value will not exceed the value in +.I stx_atomic_write_unit_max +and will not be less than the value in +.IR stx_atomic_write_unit_min . +A value of zero indicates that +.I stx_atomic_write_unit_max +is the optimised limit. +Slower writes may be experienced when the size of the write exceeds +.I stx_atomic_write_unit_max_opt +(when non-zero). +.TP .I stx_atomic_write_segments_max The maximum number of elements in an array of vectors for a write with torn-write protection enabled.