rpms/man-pages
6
0
Fork 0
Code Issues Pull Requests Releases Activity

Document RWF_ATOMIC, STATX_ATTR_WRITE_ATOMIC flags (RHEL-87625)

Browse Source 
Resolves: RHEL-87625
This commit is contained in:
Patsy Griffin 2025-10-01 20:55:41 -04:00
parent e02208476e
commit cbd4800909
5 changed files with 288 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
RHEL-87625-1.patch Normal file
View File

@ -0,0 +1,107 @@
commit 8c967453fc1c4bd5274d90db22fc857d87e13d12
Author: Himanshu Madhani <himanshu.madhani@oracle.com>
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 <himanshu.madhani@oracle.com>
[jpg: complete rewrite]
Signed-off-by: John Garry <john.g.garry@oracle.com>
Cc: <linux-fsdevel@vger.kernel.org>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Dave Chinner <dchinner@redhat.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Message-ID: <20240722095723.597846-3-john.g.garry@oracle.com>
Reviewed-by: Darrick J. Wong <djwong@kernel.org>
[alx: semantic newlines; srcfix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
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.

49
RHEL-87625-2.patch Normal file
View File

@ -0,0 +1,49 @@
commit ed4bb613b3fb0f5ed1c365e4280e0517d36bbf25
Author: John Garry <john.g.garry@oracle.com>
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" <djwong@kernel.org>
Signed-off-by: John Garry <john.g.garry@oracle.com>
Cc: <linux-fsdevel@vger.kernel.org>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Dave Chinner <dchinner@redhat.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Message-ID: <20240722095723.597846-4-john.g.garry@oracle.com>
[alx: wfix; ffix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
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

82
RHEL-87625-3.patch Normal file
View File

@ -0,0 +1,82 @@
commit d4de003f2d752e514f0d28e1df62583fab186a9e
Author: Himanshu Madhani <himanshu.madhani@oracle.com>
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 <himanshu.madhani@oracle.com>
Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>
Signed-off-by: John Garry <john.g.garry@oracle.com>
Cc: <linux-fsdevel@vger.kernel.org>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Dave Chinner <dchinner@redhat.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Message-ID: <20240722095723.597846-2-john.g.garry@oracle.com>
[alx: ffix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
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

36
RHEL-87625-4.patch Normal file
View File

@ -0,0 +1,36 @@
commit d47bd08d8b254ff1dc46726e38fa205ad5eecba5
Author: John Garry <john.g.garry@oracle.com>
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" <djwong@kernel.org>
Cc: <ritesh.list@gmail.com>
Signed-off-by: John Garry <john.g.garry@oracle.com>
Message-ID: <20241203145359.2691972-1-john.g.garry@oracle.com>
[alx: ffix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
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

15
man-pages.spec
View File

@ -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 <patsy@redhat.com> - 6.04-8
- Document RWF_ATOMIC, STATX_ATTR_WRITE_ATOMIC flags (RHEL-87625)
* Mon Aug 18 2025 Patsy Griffin <patsy@redhat.com> - 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.