diff mbox series

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

Message ID 20240708114227.211195-2-john.g.garry@oracle.com (mailing list archive)
State New
Headers show
Series man2: Document RWF_ATOMIC | expand

Commit Message

John Garry July 8, 2024, 11:42 a.m. UTC 
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(+)

Comments

Alejandro Colomar July 9, 2024, 4:48 p.m. UTC | #1 
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
John Garry July 10, 2024, 10:11 a.m. UTC | #2 
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
Alejandro Colomar July 10, 2024, 10:23 a.m. UTC | #3 
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
> 
>
diff mbox series

Patch

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