[PATCH v3 0/3] man2: Document RWF_ATOMIC

[PATCH v3 0/3] man2: Document RWF_ATOMIC

[John Garry]

Document RWF_ATOMIC flag for pwritev2().

RWF_ATOMIC atomic is used for enabling torn-write protection.

We use RWF_ATOMIC as this is legacy name for similar feature proposed in
the past.

Kernel support has now been queued in
https://lore.kernel.org/linux-block/20240620125359.2684798-1-john.g.garry@oracle.com/

Differences to v2:
- rebase

Differences to v1:
- Add statx max segments param
- Expand readv.2 description
- Document EINVAL

Himanshu Madhani (2):
  statx.2: Document STATX_WRITE_ATOMIC
  readv.2: Document RWF_ATOMIC flag

John Garry (1):
  io_submit.2: Document RWF_ATOMIC

 man/man2/io_submit.2 | 17 +++++++++++
 man/man2/readv.2     | 73 +++++++++++++++++++++++++++++++++++++++++++-
 man/man2/statx.2     | 29 ++++++++++++++++++
 3 files changed, 118 insertions(+), 1 deletion(-)

-- 
2.31.1

[PATCH v3 1/3] statx.2: Document STATX_WRITE_ATOMIC

[John Garry]

From: Himanshu Madhani <himanshu.madhani@oracle.com>

Add the text to the statx man page.

Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/statx.2 | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index 3d47319c6..36ecc8360 100644
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -70,6 +70,11 @@ struct statx {
     __u32 stx_dio_offset_align;
 \&
     __u64 stx_subvol;      /* Subvolume identifier */
+\&
+    /* 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
@@ -259,6 +264,9 @@ STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
 STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.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.
+	(since Linux 6.11; support varies by filesystem)
 .TE
 .in
 .P
@@ -463,6 +471,24 @@ Subvolumes are fancy directories,
 i.e. they form a tree structure that may be walked recursively.
 Support varies by filesystem;
 it is supported by bcachefs and btrfs since Linux 6.10.
+.I stx_atomic_write_unit_min
+The minimum size (in bytes) supported for direct I/O
+.RB ( O_DIRECT )
+on the file to be written with torn-write protection. This value is guaranteed
+to be a power-of-2.
+.TP
+.I stx_atomic_write_unit_max
+The maximum size (in bytes) supported for direct I/O
+.RB ( O_DIRECT )
+on the file to be written with torn-write protection. This value is 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
+.BR RWF_ATOMIC
+flag for
+.BR pwritev2 (2).
 .P
 For further information on the above fields, see
 .BR inode (7).
@@ -516,6 +542,9 @@ It cannot be written to, and all reads from it will be verified
 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
-- 
2.31.1

Re: [PATCH v3 1/3] statx.2: Document STATX_WRITE_ATOMIC

[Alejandro Colomar]

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

On Mon, Jul 08, 2024 at 11:42:25AM GMT, John Garry wrote:
> From: Himanshu Madhani <himanshu.madhani@oracle.com>
> 
> Add the text to the statx man page.
> 
> Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
> Signed-off-by: John Garry <john.g.garry@oracle.com>
> ---
>  man/man2/statx.2 | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index 3d47319c6..36ecc8360 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -70,6 +70,11 @@ struct statx {
>      __u32 stx_dio_offset_align;
>  \&
>      __u64 stx_subvol;      /* Subvolume identifier */
> +\&
> +    /* 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
> @@ -259,6 +264,9 @@ STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
>  STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.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.
> +	(since Linux 6.11; support varies by filesystem)
>  .TE
>  .in
>  .P
> @@ -463,6 +471,24 @@ Subvolumes are fancy directories,
>  i.e. they form a tree structure that may be walked recursively.
>  Support varies by filesystem;
>  it is supported by bcachefs and btrfs since Linux 6.10.

.TP

> +.I stx_atomic_write_unit_min
> +The minimum size (in bytes) supported for direct I/O
> +.RB ( O_DIRECT )
> +on the file to be written with torn-write protection. This value is guaranteed

Please use semantic newlines.  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.

> +to be a power-of-2.
> +.TP
> +.I stx_atomic_write_unit_max

You should probably merge both fields with a single paragraph.  See for
example 'stx_dev_major' and 'stx_dev_minor'.

Have a lovely day!
Alex

> +The maximum size (in bytes) supported for direct I/O
> +.RB ( O_DIRECT )
> +on the file to be written with torn-write protection. This value is 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
> +.BR RWF_ATOMIC
> +flag for
> +.BR pwritev2 (2).
>  .P
>  For further information on the above fields, see
>  .BR inode (7).
> @@ -516,6 +542,9 @@ It cannot be written to, and all reads from it will be verified
>  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
> -- 
> 2.31.1


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

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

Re: [PATCH v3 1/3] statx.2: Document STATX_WRITE_ATOMIC

[John Garry]

On 09/07/2024 17:48, Alejandro Colomar wrote:
> On Mon, Jul 08, 2024 at 11:42:25AM GMT, John Garry wrote:
>> From: Himanshu Madhani<himanshu.madhani@oracle.com>
>>
>> Add the text to the statx man page.
>>
>> Signed-off-by: Himanshu Madhani<himanshu.madhani@oracle.com>
>> Signed-off-by: John Garry<john.g.garry@oracle.com>
>> ---
>>   man/man2/statx.2 | 29 +++++++++++++++++++++++++++++
>>   1 file changed, 29 insertions(+)
>>
>> diff --git a/man/man2/statx.2 b/man/man2/statx.2
>> index 3d47319c6..36ecc8360 100644
>> --- a/man/man2/statx.2
>> +++ b/man/man2/statx.2
>> @@ -70,6 +70,11 @@ struct statx {
>>       __u32 stx_dio_offset_align;
>>   \&
>>       __u64 stx_subvol;      /* Subvolume identifier */
>> +\&
>> +    /* 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
>> @@ -259,6 +264,9 @@ STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
>>   STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.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.
>> +	(since Linux 6.11; support varies by filesystem)
>>   .TE
>>   .in
>>   .P
>> @@ -463,6 +471,24 @@ Subvolumes are fancy directories,
>>   i.e. they form a tree structure that may be walked recursively.
>>   Support varies by filesystem;
>>   it is supported by bcachefs and btrfs since Linux 6.10.
> .TP

ok

> 
>> +.I stx_atomic_write_unit_min
>> +The minimum size (in bytes) supported for direct I/O
>> +.RB ( O_DIRECT )
>> +on the file to be written with torn-write protection. This value is guaranteed
> Please use semantic newlines.  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.
> 

ok

>> +to be a power-of-2.
>> +.TP
>> +.I stx_atomic_write_unit_max
> You should probably merge both fields with a single paragraph.  See for
> example 'stx_dev_major' and 'stx_dev_minor'.

ok, I'll try to merge. I do note that we then will still have 
stx_atomic_write_segments_max in a separate paragraph.

Thanks,
John

Re: [PATCH v3 1/3] statx.2: Document STATX_WRITE_ATOMIC

[Alejandro Colomar]

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

On Wed, Jul 10, 2024 at 11:11:33AM GMT, John Garry wrote:
> On 09/07/2024 17:48, Alejandro Colomar wrote:
> > On Mon, Jul 08, 2024 at 11:42:25AM GMT, John Garry wrote:
> > > From: Himanshu Madhani<himanshu.madhani@oracle.com>
> > > 
> > > Add the text to the statx man page.
> > > 
> > > Signed-off-by: Himanshu Madhani<himanshu.madhani@oracle.com>
> > > Signed-off-by: John Garry<john.g.garry@oracle.com>
> > > ---

> > > +to be a power-of-2.
> > > +.TP
> > > +.I stx_atomic_write_unit_max
> > You should probably merge both fields with a single paragraph.  See for
> > example 'stx_dev_major' and 'stx_dev_minor'.
> 
> ok, I'll try to merge. I do note that we then will still have
> stx_atomic_write_segments_max in a separate paragraph.

Yep; since it's different that's correct.

Cheers,
Alex

> 
> Thanks,
> John
> 
> 

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

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

[PATCH v3 2/3] readv.2: Document RWF_ATOMIC flag

[John Garry]

From: Himanshu Madhani <himanshu.madhani@oracle.com>

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>
---
 man/man2/readv.2 | 73 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 72 insertions(+), 1 deletion(-)

diff --git a/man/man2/readv.2 b/man/man2/readv.2
index eecde06dc..78d8305e3 100644
--- a/man/man2/readv.2
+++ b/man/man2/readv.2
@@ -193,6 +193,61 @@ which provides lower latency, but may use additional resources.
 .B O_DIRECT
 flag.)
 .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 failure 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 between
+.I stx_atomic_write_unit_min
+ and
+.I  stx_atomic_write_unit_max
+, both inclusive. 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 32KB at a file offset of
+32KB is permitted, however a write of length 32KB at a file offset of 48KB is
+not permitted. The upper limit of
+.I iovcnt
+for
+.BR pwritev2 ()
+is 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,
+.BR fdatasync (2),
+or
+.BR fsync (2),
+or
+.BR open (2)
+and either
+.B O_SYNC
+or
+.B O_DSYNC,
+or
+.B pwritev2 ()
+and either
+.B RWF_SYNC
+or
+.B RWF_DSYNC
+is required. Flags
+.B O_SYNC
+or
+.B RWF_SYNC
+provide the strongest guarantees for
+.BR RWF_ATOMIC,
+in that all data and also file metadata updates will be persisted for a
+successfully completed write. Just using either flags
+.B O_DSYNC
+or
+.B RWF_DSYNC
+means that all data and any file updates will be persisted for a successfully
+completed write. Not using any sync flags means that there
+is no guarantee that data or filesystem updates are persisted.
+.TP
 .BR RWF_SYNC " (since Linux 4.7)"
 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
 Provide a per-write equivalent of the
@@ -279,10 +334,26 @@ values overflows an
 .I ssize_t
 value.
 .TP
+.B EINVAL
+ For
+.BR RWF_ATOMIC
+set,
+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.
+is less than zero or greater than the permitted maximum. For
+.BR RWF_ATOMIC
+set, this maximum is in
+.I stx_atomic_write_segments_max
+from
+.I statx.
 .TP
 .B EOPNOTSUPP
 An unknown flag is specified in \fIflags\fP.
-- 
2.31.1

Re: [PATCH v3 2/3] readv.2: Document RWF_ATOMIC flag

[Alejandro Colomar]

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

Hi John,

On Mon, Jul 08, 2024 at 11:42:26AM GMT, John Garry wrote:
> From: Himanshu Madhani <himanshu.madhani@oracle.com>
> 
> 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>
> ---
>  man/man2/readv.2 | 73 +++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 72 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/readv.2 b/man/man2/readv.2
> index eecde06dc..78d8305e3 100644
> --- a/man/man2/readv.2
> +++ b/man/man2/readv.2
> @@ -193,6 +193,61 @@ which provides lower latency, but may use additional resources.
>  .B O_DIRECT
>  flag.)
>  .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 failure 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 between
> +.I stx_atomic_write_unit_min
> + and
> +.I  stx_atomic_write_unit_max
> +, both inclusive. The

We use mathematical notation for ranges:

... in the range
.RI [ stx_atomic_write_unit_min ,
.IR stx_atomic_write_unit_max ].

Have a lovely day!
Alex

> +write must be at a naturally-aligned offset within the file with respect to the
> +total write length - for example, a write of length 32KB at a file offset of
> +32KB is permitted, however a write of length 32KB at a file offset of 48KB is
> +not permitted. The upper limit of
> +.I iovcnt
> +for
> +.BR pwritev2 ()
> +is 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,
> +.BR fdatasync (2),
> +or
> +.BR fsync (2),
> +or
> +.BR open (2)
> +and either
> +.B O_SYNC
> +or
> +.B O_DSYNC,
> +or
> +.B pwritev2 ()
> +and either
> +.B RWF_SYNC
> +or
> +.B RWF_DSYNC
> +is required. Flags
> +.B O_SYNC
> +or
> +.B RWF_SYNC
> +provide the strongest guarantees for
> +.BR RWF_ATOMIC,
> +in that all data and also file metadata updates will be persisted for a
> +successfully completed write. Just using either flags
> +.B O_DSYNC
> +or
> +.B RWF_DSYNC
> +means that all data and any file updates will be persisted for a successfully
> +completed write. Not using any sync flags means that there
> +is no guarantee that data or filesystem updates are persisted.
> +.TP
>  .BR RWF_SYNC " (since Linux 4.7)"
>  .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
>  Provide a per-write equivalent of the
> @@ -279,10 +334,26 @@ values overflows an
>  .I ssize_t
>  value.
>  .TP
> +.B EINVAL
> + For
> +.BR RWF_ATOMIC
> +set,
> +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.
> +is less than zero or greater than the permitted maximum. For
> +.BR RWF_ATOMIC
> +set, this maximum is in
> +.I stx_atomic_write_segments_max
> +from
> +.I statx.
>  .TP
>  .B EOPNOTSUPP
>  An unknown flag is specified in \fIflags\fP.
> -- 
> 2.31.1
> 

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

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

[PATCH v3 3/3] io_submit.2: Document RWF_ATOMIC

[John Garry]

Document RWF_ATOMIC for asynchronous I/O.

Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/io_submit.2 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
index c53ae9aaf..ef6414d24 100644
--- a/man/man2/io_submit.2
+++ b/man/man2/io_submit.2
@@ -140,6 +140,23 @@ 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 the flag of the same name in
+.BR pwritev2 (2).
+For usage with
+.BR IOCB_CMD_PWRITEV,
+the upper vector limit is in
+.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
-- 
2.31.1

Re: [PATCH v3 3/3] io_submit.2: Document RWF_ATOMIC

[Alejandro Colomar]

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

On Mon, Jul 08, 2024 at 11:42:27AM GMT, John Garry wrote:
> Document RWF_ATOMIC for asynchronous I/O.
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>
> ---
>  man/man2/io_submit.2 | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
> index c53ae9aaf..ef6414d24 100644
> --- a/man/man2/io_submit.2
> +++ b/man/man2/io_submit.2
> @@ -140,6 +140,23 @@ 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 the flag of the same name in

Maybe?:

of this same flag in

> +.BR pwritev2 (2).
> +For usage with
> +.BR IOCB_CMD_PWRITEV,
> +the upper vector limit is in
> +.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
> -- 
> 2.31.1
> 

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

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

Re: [PATCH v3 3/3] io_submit.2: Document RWF_ATOMIC

[Alejandro Colomar]

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

On Tue, Jul 09, 2024 at 06:53:03PM GMT, Alejandro Colomar wrote:
> On Mon, Jul 08, 2024 at 11:42:27AM GMT, John Garry wrote:
> > Document RWF_ATOMIC for asynchronous I/O.
> > 
> > Signed-off-by: John Garry <john.g.garry@oracle.com>
> > ---
> >  man/man2/io_submit.2 | 17 +++++++++++++++++
> >  1 file changed, 17 insertions(+)
> > 
> > diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
> > index c53ae9aaf..ef6414d24 100644
> > --- a/man/man2/io_submit.2
> > +++ b/man/man2/io_submit.2
> > @@ -140,6 +140,23 @@ 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 the flag of the same name in
> 
> Maybe?:
> 
> of this same flag in

Or just to be less ambiguous:

See the description of
.B RWF_ATOMIC
in

> 
> > +.BR pwritev2 (2).
> > +For usage with
> > +.BR IOCB_CMD_PWRITEV,
> > +the upper vector limit is in
> > +.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
> > -- 
> > 2.31.1
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



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

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

Re: [PATCH v3 3/3] io_submit.2: Document RWF_ATOMIC

[John Garry]

On 09/07/2024 17:53, Alejandro Colomar wrote:
>>> +.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 the flag of the same name in
>> Maybe?:
>>
>> of this same flag in
> Or just to be less ambiguous:
> 
> See the description of
> .B RWF_ATOMIC
> in


ok, that seems better.

Thanks,
John

Re: [PATCH v3 0/3] man2: Document RWF_ATOMIC

[Alejandro Colomar]

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

Hi John,

On Mon, Jul 08, 2024 at 11:42:24AM GMT, John Garry wrote:
> Document RWF_ATOMIC flag for pwritev2().
> 
> RWF_ATOMIC atomic is used for enabling torn-write protection.
> 
> We use RWF_ATOMIC as this is legacy name for similar feature proposed in
> the past.
> 
> Kernel support has now been queued in
> https://lore.kernel.org/linux-block/20240620125359.2684798-1-john.g.garry@oracle.com/
> 
> Differences to v2:
> - rebase
> 
> Differences to v1:
> - Add statx max segments param
> - Expand readv.2 description
> - Document EINVAL

I don't remember having seen v1 or v2.  This is the first iteration sent
to linux-man@, right?  (No problem with that; just to confirm.)

Cheers,
Alex

> 
> Himanshu Madhani (2):
>   statx.2: Document STATX_WRITE_ATOMIC
>   readv.2: Document RWF_ATOMIC flag
> 
> John Garry (1):
>   io_submit.2: Document RWF_ATOMIC
> 
>  man/man2/io_submit.2 | 17 +++++++++++
>  man/man2/readv.2     | 73 +++++++++++++++++++++++++++++++++++++++++++-
>  man/man2/statx.2     | 29 ++++++++++++++++++
>  3 files changed, 118 insertions(+), 1 deletion(-)
> 
> -- 
> 2.31.1
> 

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

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

Re: [PATCH v3 0/3] man2: Document RWF_ATOMIC

[John Garry]

On 09/07/2024 17:43, Alejandro Colomar wrote:
> Hi John,
> 
> On Mon, Jul 08, 2024 at 11:42:24AM GMT, John Garry wrote:
>> Document RWF_ATOMIC flag for pwritev2().
>>
>> RWF_ATOMIC atomic is used for enabling torn-write protection.
>>
>> We use RWF_ATOMIC as this is legacy name for similar feature proposed in
>> the past.
>>
>> Kernel support has now been queued in
>> https://lore.kernel.org/linux-block/20240620125359.2684798-1-john.g.garry@oracle.com/
>>
>> Differences to v2:
>> - rebase
>>
>> Differences to v1:
>> - Add statx max segments param
>> - Expand readv.2 description
>> - Document EINVAL
> 
> I don't remember having seen v1 or v2.  This is the first iteration sent
> to linux-man@, right?  (No problem with that; just to confirm.)

Yes, first for linux-man@. An oversight on my part (not to include for 
previous iterations), sorry. Please see v1 and v2 at:

https://lore.kernel.org/linux-api/20230929093717.2972367-1-john.g.garry@oracle.com/
https://lore.kernel.org/linux-api/20240124112731.28579-1-john.g.garry@oracle.com/

Thanks,
John

> 
>>
>> Himanshu Madhani (2):
>>    statx.2: Document STATX_WRITE_ATOMIC
>>    readv.2: Document RWF_ATOMIC flag
>>
>> John Garry (1):
>>    io_submit.2: Document RWF_ATOMIC
>>
>>   man/man2/io_submit.2 | 17 +++++++++++
>>   man/man2/readv.2     | 73 +++++++++++++++++++++++++++++++++++++++++++-
>>   man/man2/statx.2     | 29 ++++++++++++++++++
>>   3 files changed, 118 insertions(+), 1 deletion(-)
>>
>> -- 
>> 2.31.1
>>
>