From cbd4800909ebd7be012382e6337f145ff52be60f Mon Sep 17 00:00:00 2001 From: Patsy Griffin Date: Wed, 1 Oct 2025 20:55:41 -0400 Subject: [PATCH] Document RWF_ATOMIC, STATX_ATTR_WRITE_ATOMIC flags (RHEL-87625) Resolves: RHEL-87625 --- RHEL-87625-1.patch | 107 +++++++++++++++++++++++++++++++++++++++++++++ RHEL-87625-2.patch | 49 +++++++++++++++++++++ RHEL-87625-3.patch | 82 ++++++++++++++++++++++++++++++++++ RHEL-87625-4.patch | 36 +++++++++++++++ man-pages.spec | 15 ++++++- 5 files changed, 288 insertions(+), 1 deletion(-) create mode 100644 RHEL-87625-1.patch create mode 100644 RHEL-87625-2.patch create mode 100644 RHEL-87625-3.patch create mode 100644 RHEL-87625-4.patch diff --git a/RHEL-87625-1.patch b/RHEL-87625-1.patch new file mode 100644 index 0000000..4ddc25d --- /dev/null +++ b/RHEL-87625-1.patch @@ -0,0 +1,107 @@ +commit 8c967453fc1c4bd5274d90db22fc857d87e13d12 +Author: Himanshu Madhani +Date: Mon Jul 22 09:57:22 2024 +0000 + + readv.2: Document RWF_ATOMIC flag + + Add RWF_ATOMIC flag description for pwritev2(). + + Signed-off-by: Himanshu Madhani + [jpg: complete rewrite] + Signed-off-by: John Garry + Cc: + Cc: Jens Axboe + Cc: Christoph Hellwig + Cc: Dave Chinner + Cc: "Martin K. Petersen" + Message-ID: <20240722095723.597846-3-john.g.garry@oracle.com> + Reviewed-by: Darrick J. Wong + [alx: semantic newlines; srcfix] + Signed-off-by: Alejandro Colomar + +diff --git a/man2/readv.2 b/man2/readv.2 +index e369acdec..78232c19f 100644 +--- a/man2/readv.2 ++++ b/man2/readv.2 +@@ -237,6 +237,54 @@ the data is always appended to the end of the file. + However, if the + .I offset + argument is \-1, the current file offset is updated. ++.TP ++.BR RWF_ATOMIC " (since Linux 6.11)" ++Requires that ++writes to regular files in block-based filesystems ++be issued with torn-write protection. ++Torn-write protection means that ++for a power or any other hardware failure, ++all or none of the data from the write will be stored, ++but never a mix of old and new data. ++This flag is meaningful only for ++.BR pwritev2 (), ++and its effect applies only to ++the data range written by the system call. ++The total write length must be power-of-2 ++and must be sized in the range ++.RI [ stx_atomic_write_unit_min , ++.IR stx_atomic_write_unit_max ]. ++The write must be at a naturally-aligned offset within the file ++with respect to the total write length. ++For example, ++a write of length 32KiB at a file offset of 32KiB is permitted, ++however a write of length 32KiB at a file offset of 48KiB is not permitted. ++The upper limit of ++.I iovcnt ++for ++.BR pwritev2 () ++is given by the value in ++.I stx_atomic_write_segments_max. ++Torn-write protection only works with ++.B O_DIRECT ++flag, ++i.e. buffered writes are not supported. ++To guarantee consistency from the write ++between a file's in-core state ++with the storage device, ++.B O_SYNC ++or ++.B O_DSYNC ++must be specified for ++.BR open (2). ++The same synchronized I/O guarantees as described in ++.BR open (2) ++are provided when these flags ++or their equivalent flags and system calls are used ++(e.g., if ++.B RWF_SYNC ++is specified for ++.BR pwritev2 ()). + .SH RETURN VALUE + On success, + .BR readv (), +@@ -280,9 +328,26 @@ values overflows an + value. + .TP + .B EINVAL ++If ++.B RWF_ATOMIC ++is specified, ++the combination of the sum of the ++.I iov_len ++values and the ++.I offset ++value does not comply with the length and offset torn-write protection rules. ++.TP ++.B EINVAL + The vector count, + .IR iovcnt , + is less than zero or greater than the permitted maximum. ++If ++.B RWF_ATOMIC ++is specified, ++this maximum is given by the ++.I stx_atomic_write_segments_max ++value from ++.I statx. + .TP + .B EOPNOTSUPP + An unknown flag is specified in \fIflags\fP. diff --git a/RHEL-87625-2.patch b/RHEL-87625-2.patch new file mode 100644 index 0000000..8642a19 --- /dev/null +++ b/RHEL-87625-2.patch @@ -0,0 +1,49 @@ +commit ed4bb613b3fb0f5ed1c365e4280e0517d36bbf25 +Author: John Garry +Date: Mon Jul 22 09:57:23 2024 +0000 + + io_submit.2: Document RWF_ATOMIC + + Document RWF_ATOMIC for asynchronous I/O. + + Reviewed-by: "Darrick J. Wong" + Signed-off-by: John Garry + Cc: + Cc: Jens Axboe + Cc: Christoph Hellwig + Cc: Dave Chinner + Cc: "Martin K. Petersen" + Message-ID: <20240722095723.597846-4-john.g.garry@oracle.com> + [alx: wfix; ffix] + Signed-off-by: Alejandro Colomar + +diff --git a/man2/io_submit.2 b/man2/io_submit.2 +index 5e4e41af0..c3d86b4c4 100644 +--- a/man2/io_submit.2 ++++ b/man2/io_submit.2 +@@ -140,6 +140,25 @@ as well the description of + .B O_SYNC + in + .BR open (2). ++.TP ++.BR RWF_ATOMIC " (since Linux 6.11)" ++Write a block of data such that ++a write will never be torn from power fail or similar. ++See the description of ++.B RWF_ATOMIC ++in ++.BR pwritev2 (2). ++For usage with ++.BR IOCB_CMD_PWRITEV , ++the upper vector limit is ++.I stx_atomic_write_segments_max. ++See ++.B STATX_WRITE_ATOMIC ++and ++.I stx_atomic_write_segments_max ++description ++in ++.BR statx (2). + .RE + .TP + .I aio_lio_opcode diff --git a/RHEL-87625-3.patch b/RHEL-87625-3.patch new file mode 100644 index 0000000..4bcebe4 --- /dev/null +++ b/RHEL-87625-3.patch @@ -0,0 +1,82 @@ +commit d4de003f2d752e514f0d28e1df62583fab186a9e +Author: Himanshu Madhani +Date: Mon Jul 22 09:57:21 2024 +0000 + + statx.2: Document STATX_WRITE_ATOMIC + + Add the text to the statx man page. + + Signed-off-by: Himanshu Madhani + Reviewed-by: "Darrick J. Wong" + Signed-off-by: John Garry + Cc: + Cc: Jens Axboe + Cc: Christoph Hellwig + Cc: Dave Chinner + Cc: "Martin K. Petersen" + Message-ID: <20240722095723.597846-2-john.g.garry@oracle.com> + [alx: ffix] + Signed-off-by: Alejandro Colomar + +Conflicts: + man2/statx.2: rework due to missing intermittent patches + +diff -Nrup a/man2/statx.2 b/man-pages-6.04/man2/statx.2 +--- a/man2/statx.2 2023-04-02 20:27:21.000000000 -0400 ++++ b/man2/statx.2 2025-10-01 19:55:56.898084564 -0400 +@@ -68,6 +68,11 @@ struct statx { + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; ++\& ++ /* Direct I/O atomic write limits */ ++ __u32 stx_atomic_write_unit_min; ++ __u32 stx_atomic_write_unit_max; ++ __u32 stx_atomic_write_segments_max; + }; + .EE + .in +@@ -255,6 +260,10 @@ STATX_ALL The same as STATX_BASIC_STATS + STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) + STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) ++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) + .TE + .in + .PP +@@ -439,6 +448,22 @@ or 0 if direct I/O is not supported on t + This will only be nonzero if + .I stx_dio_mem_align + is nonzero, and vice versa. ++.TP ++.I stx_atomic_write_unit_min ++.TQ ++.I stx_atomic_write_unit_max ++The minimum and maximum sizes (in bytes) supported for direct I/O ++.RB ( O_DIRECT ) ++on the file to be written with torn-write protection. ++These values are each guaranteed to be a power-of-2. ++.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. ++See ++.B RWF_ATOMIC ++flag for ++.BR pwritev2 (2). + .PP + For further information on the above fields, see + .BR inode (7). +@@ -492,6 +517,9 @@ It cannot be written to, and all reads f + against a cryptographic hash that covers the + entire file (e.g., via a Merkle tree). + .TP ++.BR STATX_ATTR_WRITE_ATOMIC " (since Linux 6.11)" ++The file supports torn-write protection. ++.TP + .BR STATX_ATTR_DAX " (since Linux 5.8)" + The file is in the DAX (cpu direct access) state. + DAX state attempts to diff --git a/RHEL-87625-4.patch b/RHEL-87625-4.patch new file mode 100644 index 0000000..6068026 --- /dev/null +++ b/RHEL-87625-4.patch @@ -0,0 +1,36 @@ +commit d47bd08d8b254ff1dc46726e38fa205ad5eecba5 +Author: John Garry +Date: Tue Dec 3 14:53:59 2024 +0000 + + man/man2/statx.2: Update STATX_WRITE_ATOMIC filesystem support + + Linux v6.13 will include atomic write support for xfs and ext4, so + update STATX_WRITE_ATOMIC commentary to mention that. + + Cc: "Darrick J. Wong" + Cc: + Signed-off-by: John Garry + Message-ID: <20241203145359.2691972-1-john.g.garry@oracle.com> + [alx: ffix] + Signed-off-by: Alejandro Colomar + +diff --git a/man2/statx.2 b/man2/statx.2 +index c5b5a28ec..7fab1d3d8 100644 +--- a/man2/statx.2 ++++ b/man2/statx.2 +@@ -482,6 +482,15 @@ The minimum and maximum sizes (in bytes) supported for direct I/O + .RB ( O_DIRECT ) + on the file to be written with torn-write protection. + These values are each guaranteed to be a power-of-2. ++.IP ++.B STATX_WRITE_ATOMIC ++.RI ( stx_atomic_write_unit_min , ++.IR stx_atomic_write_unit_max , ++and ++.IR stx_atomic_write_segments_max ) ++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_segments_max + The maximum number of elements in an array of vectors diff --git a/man-pages.spec b/man-pages.spec index 9651d14..78ee88d 100644 --- a/man-pages.spec +++ b/man-pages.spec @@ -1,7 +1,7 @@ Summary: Linux kernel and C library user-space interface documentation Name: man-pages Version: 6.04 -Release: 7%{?dist} +Release: 8%{?dist} # List of licenses with examples of man-pages using them # BSD-2-Clause: man-pages/man5/elf.5 # BSD-3-Clause: man-pages/man3/list.3 @@ -62,6 +62,12 @@ Patch27: 0000-sched.7-Clarifications-corrections.patch # Add rtas.2, swapcontext.2 and cons.saver.8 man pages Patch28: additional-man-pages.patch +# Add update for RWF_ATOMIC. (RHEL-87647) +Patch29: RHEL-87625-1.patch +Patch30: RHEL-87625-2.patch +Patch31: RHEL-87625-3.patch +Patch32: RHEL-87625-4.patch + %description A large collection of manual pages from the Linux Documentation Project (LDP). @@ -76,6 +82,10 @@ A large collection of manual pages from the Linux Documentation Project (LDP). %patch -p1 -P 26 %patch -p1 -P 27 %patch -p1 -P 28 +%patch -p1 -P 29 +%patch -p1 -P 30 +%patch -p1 -P 31 +%patch -p1 -P 32 ## Remove man pages we are not going to use ## @@ -128,6 +138,9 @@ fi %{_mandir}/man*/* %changelog +* Thu Oct 02 2025 Patsy Griffin - 6.04-8 +- Document RWF_ATOMIC, STATX_ATTR_WRITE_ATOMIC flags (RHEL-87625) + * Mon Aug 18 2025 Patsy Griffin - 6.04-7 - Break up man-pages-additional-20140218.tar.xz - Add rtas.2, swapcontext.2 and cons.saver.8 man pages as a patch.