[PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[John Garry]

Linux v6.13 will include atomic write support for xfs and ext4, so update
STATX_WRITE_ATOMIC commentary to mention that.

Signed-off-by: John Garry <john.g.garry@oracle.com>

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index c5b5a28ec..2d33998c5 100644
--- a/man/man2/statx.2
+++ b/man/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,
+.RI 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
-- 
2.31.1

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[Darrick J. Wong]

On Tue, Dec 03, 2024 at 02:53:59PM +0000, John Garry wrote:
> Linux v6.13 will include atomic write support for xfs and ext4, so update
> STATX_WRITE_ATOMIC commentary to mention that.
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index c5b5a28ec..2d33998c5 100644
> --- a/man/man2/statx.2
> +++ b/man/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,
> +.RI 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.

woot!

Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>

--D

>  .TP
>  .I stx_atomic_write_segments_max
>  The maximum number of elements in an array of vectors
> -- 
> 2.31.1
> 

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[Alejandro Colomar]

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

Hi John,

On Tue, Dec 03, 2024 at 02:53:59PM +0000, John Garry wrote:
> Linux v6.13 will

Is this already in Linus's tree?

> include atomic write support for xfs and ext4, so update
> STATX_WRITE_ATOMIC commentary to mention that.
> 
> Signed-off-by: John Garry <john.g.garry@oracle.com>

Thanks for the patch!  Please see some small comment below.

Have a lovely night!
Alex

> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index c5b5a28ec..2d33998c5 100644
> --- a/man/man2/statx.2
> +++ b/man/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,
> +.RI stx_atomic_write_unit_max,

There should be a space before the ','.

> +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
> -- 
> 2.31.1
> 

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

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

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[John Garry]

On 04/12/2024 20:45, Alejandro Colomar wrote:
> Hi John,
> 
> On Tue, Dec 03, 2024 at 02:53:59PM +0000, John Garry wrote:
>> Linux v6.13 will
> 
> Is this already in Linus's tree?

The code to support xfs and ext4 is in Linus' tree from v6.13-rc1, but 
v6.13 final is not released yet.

So maybe you want to hold off on this patch until v6.13 final is released.

> 
>> include atomic write support for xfs and ext4, so update
>> STATX_WRITE_ATOMIC commentary to mention that.
>>
>> Signed-off-by: John Garry <john.g.garry@oracle.com>
> 
> Thanks for the patch!  Please see some small comment below.
> 
> Have a lovely night!
> Alex
> 
>>
>> diff --git a/man/man2/statx.2 b/man/man2/statx.2
>> index c5b5a28ec..2d33998c5 100644
>> --- a/man/man2/statx.2
>> +++ b/man/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,
>> +.RI stx_atomic_write_unit_max,
> 
> There should be a space before the ','.
> 
>> +and
>> +.IR stx_atomic_write_segments_max )

How about this:

.B STATX_WRITE_ATOMIC
.RI ( stx_atomic_write_unit_min,
.I stx_atomic_write_unit_max,
and
.IR stx_atomic_write_segments_max )

I think that this looks right.

Thanks,
John

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[Alejandro Colomar]

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

Hi John,

On Thu, Dec 05, 2024 at 09:33:18AM +0000, John Garry wrote:
> On 04/12/2024 20:45, Alejandro Colomar wrote:
> > Hi John,
> > 
> > On Tue, Dec 03, 2024 at 02:53:59PM +0000, John Garry wrote:
> > > Linux v6.13 will
> > 
> > Is this already in Linus's tree?
> 
> The code to support xfs and ext4 is in Linus' tree from v6.13-rc1, but v6.13
> final is not released yet.
> 
> So maybe you want to hold off on this patch until v6.13 final is released.

Nah, we can apply it already.  Just let me know if anything changes
before the release.

> > > diff --git a/man/man2/statx.2 b/man/man2/statx.2
> > > index c5b5a28ec..2d33998c5 100644
> > > --- a/man/man2/statx.2
> > > +++ b/man/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,
> > > +.RI stx_atomic_write_unit_max,
> > 
> > There should be a space before the ','.
> > 
> > > +and
> > > +.IR stx_atomic_write_segments_max )
> 
> How about this:
> 
> .B STATX_WRITE_ATOMIC
> .RI ( stx_atomic_write_unit_min,
> .I stx_atomic_write_unit_max,
> and
> .IR stx_atomic_write_segments_max )
> 
> I think that this looks right.

No; the comma shouldn't be in italics.

.B STATX_WRITE_ATOMIC
.RI ( stx_atomic_write_unit_min ,
.IR stx_atomic_write_unit_max ,
and
.IR stx_atomic_write_segments_max )


Cheers,
Alex

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

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

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[G. Branden Robinson]

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

[trimming the linux-fsdevel list from CC, reasoning that it cares little
about typography]

Hi Alex,

At 2024-12-05T11:02:10+0100, Alejandro Colomar wrote:
> No; the comma shouldn't be in italics.
> 
> .B STATX_WRITE_ATOMIC
> .RI ( stx_atomic_write_unit_min ,
> .IR stx_atomic_write_unit_max ,
> and
> .IR stx_atomic_write_segments_max )

Style authorities differ on this point.[1]  At least three factors are
in tension:

1.  In traditional typography, one does in fact set the comma in italics
    like the preceding word.  To some eyes, including mine, that looks
    better.

2.  It is true that the comma is not part of the named parameter, so
    under rules analogous to those that govern quotation marks in the
    U.K., for instance, one would _not_ put the comma in italics.

3.  It doesn't matter all that much because unlike with literals, like
    STATX_WRITE_ATOMIC, precise copy-and-pasting doesn't buy you much.
    A formal argument name frequently _lacks_ a corresponding symbol of
    the same name in source code.  Users of memmem(3) need not name
    their parameters "needle" or "haystack".  So almost no one needs to
    precisely aim their pointer between the final letter of the
    parameter name and the trailing punctuation.

Given these factors, if you have a strong preference here, I think you
should document it in man-pages(7).

Regards,
Branden

[1] https://iconlogic.blogs.com/weblog/2011/04/writing-grammar-do-i-italicize-the-comma-after-an-italic-word.html

    https://english.stackexchange.com/questions/9878/should-punctuation-surrounding-italicised-words-be-italicised

    (The foregoing quotes the [in]famous Chicago Manual of Style, which
    I generally like except for the malicious lies about historical
    inter-sentence spacing practices promulgated by its editor, the
    dreadful Russell Harper.[2])

    https://style.mla.org/comma-after-italicized-element/

[2] https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324

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

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[Alejandro Colomar]

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

Hi Branden,

On Thu, Dec 05, 2024 at 04:34:54AM -0600, G. Branden Robinson wrote:
> [trimming the linux-fsdevel list from CC, reasoning that it cares little
> about typography]
> 
> Hi Alex,
> 
> At 2024-12-05T11:02:10+0100, Alejandro Colomar wrote:
> > No; the comma shouldn't be in italics.
> > 
> > .B STATX_WRITE_ATOMIC
> > .RI ( stx_atomic_write_unit_min ,
> > .IR stx_atomic_write_unit_max ,
> > and
> > .IR stx_atomic_write_segments_max )
> 
> Style authorities differ on this point.[1]  At least three factors are
> in tension:
> 
> 1.  In traditional typography, one does in fact set the comma in italics
>     like the preceding word.  To some eyes, including mine, that looks
>     better.

I think this is in concordance with the other meh thing US typographers
do: put punctuation within quotes, misattributing them to the quotee.
I don't like that.

> 
> 2.  It is true that the comma is not part of the named parameter, so
>     under rules analogous to those that govern quotation marks in the
>     U.K., for instance, one would _not_ put the comma in italics.

Indeed.  Similar rules apply in Spain, AFAIR.

And this isn't documented in man-pages(7) either.  We probaby should.

> 3.  It doesn't matter all that much because unlike with literals, like
>     STATX_WRITE_ATOMIC, precise copy-and-pasting doesn't buy you much.
>     A formal argument name frequently _lacks_ a corresponding symbol of
>     the same name in source code.  Users of memmem(3) need not name
>     their parameters "needle" or "haystack".  So almost no one needs to
>     precisely aim their pointer between the final letter of the
>     parameter name and the trailing punctuation.

In PDF output it doesn't matter much, but underscoring a comma (which
will happen in terminals) is quite more egregious than just a minor
oddity when the last letter overlaps the punctuation slightly in the
PDF.  So, I'd say it matters in our case.

> 
> Given these factors, if you have a strong preference here, I think you
> should document it in man-pages(7).

I do.

> 
> Regards,
> Branden
> 
> [1] https://iconlogic.blogs.com/weblog/2011/04/writing-grammar-do-i-italicize-the-comma-after-an-italic-word.html
> 
>     https://english.stackexchange.com/questions/9878/should-punctuation-surrounding-italicised-words-be-italicised
> 
>     (The foregoing quotes the [in]famous Chicago Manual of Style, which
>     I generally like except for the malicious lies about historical
>     inter-sentence spacing practices promulgated by its editor, the
>     dreadful Russell Harper.[2])
> 
>     https://style.mla.org/comma-after-italicized-element/

I like the advice in that link.  :)

> 
> [2] https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324

Thanks for the link!  I applied this commit now:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=bcf7d00fa4c7ce270f07d6e347c01b1f1e37580f>


Have a lovely day!
Alex

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

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

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[John Garry]

On 05/12/2024 10:02, Alejandro Colomar wrote:
> Hi John,
> 
> On Thu, Dec 05, 2024 at 09:33:18AM +0000, John Garry wrote:
>> On 04/12/2024 20:45, Alejandro Colomar wrote:
>>> Hi John,
>>>
>>> On Tue, Dec 03, 2024 at 02:53:59PM +0000, John Garry wrote:
>>>> Linux v6.13 will
>>>
>>> Is this already in Linus's tree?
>>
>> The code to support xfs and ext4 is in Linus' tree from v6.13-rc1, but v6.13
>> final is not released yet.
>>
>> So maybe you want to hold off on this patch until v6.13 final is released.
> 
> Nah, we can apply it already.  Just let me know if anything changes
> before the release.

Hi Alex,

I'd suggest that it is ok to merge this now, but Branden seems to have 
comments...

> 
>>>> diff --git a/man/man2/statx.2 b/man/man2/statx.2
>>>> index c5b5a28ec..2d33998c5 100644
>>>> --- a/man/man2/statx.2
>>>> +++ b/man/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,
>>>> +.RI stx_atomic_write_unit_max,
>>>
>>> There should be a space before the ','.
>>>
>>>> +and
>>>> +.IR stx_atomic_write_segments_max )
>>
>> How about this:
>>
>> .B STATX_WRITE_ATOMIC
>> .RI ( stx_atomic_write_unit_min,
>> .I stx_atomic_write_unit_max,
>> and
>> .IR stx_atomic_write_segments_max )
>>
>> I think that this looks right.
> 
> No; the comma shouldn't be in italics.


Please fix up as you see fit.

> 
> .B STATX_WRITE_ATOMIC
> .RI ( stx_atomic_write_unit_min ,
> .IR stx_atomic_write_unit_max ,
> and
> .IR stx_atomic_write_segments_max )
>


Thanks,
John

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[G. Branden Robinson]

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

Hi John,

At 2024-12-16T10:35:42+0000, John Garry wrote:
> On 05/12/2024 10:02, Alejandro Colomar wrote:
> > On Thu, Dec 05, 2024 at 09:33:18AM +0000, John Garry wrote:
> > Nah, we can apply it already.  Just let me know if anything changes
> > before the release.
> 
> I'd suggest that it is ok to merge this now, but Branden seems to have
> comments...

I don't generally intend my review comments to be gating, and this is no
exception.  (I should try harder to state that explicitly more often.)
Please don't delay on my account.  :)

Regards,
Branden

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

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[Alejandro Colomar]

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

Hi Branden, John,

On Mon, Dec 16, 2024 at 06:38:53AM -0600, G. Branden Robinson wrote:
> Hi John,
> 
> At 2024-12-16T10:35:42+0000, John Garry wrote:
> > On 05/12/2024 10:02, Alejandro Colomar wrote:
> > > On Thu, Dec 05, 2024 at 09:33:18AM +0000, John Garry wrote:
> > > Nah, we can apply it already.  Just let me know if anything changes
> > > before the release.
> > 
> > I'd suggest that it is ok to merge this now, but Branden seems to have
> > comments...
> 
> I don't generally intend my review comments to be gating, and this is no
> exception.  (I should try harder to state that explicitly more often.)

Nah, I just forgot about this patch.  Thanks for the ping; I'll apply it
later today (if I don't forget again).  :)

Cheers,
Alex

> Please don't delay on my account.  :)
> 
> Regards,
> Branden



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

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

Re: [PATCH] statx.2: Update STATX_WRITE_ATOMIC filesystem support

[Alejandro Colomar]

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

Hi John,

On Mon, Dec 16, 2024 at 01:47:53PM +0100, Alejandro Colomar wrote:
> Hi Branden, John,
> 
> On Mon, Dec 16, 2024 at 06:38:53AM -0600, G. Branden Robinson wrote:
> > Hi John,
> > 
> > At 2024-12-16T10:35:42+0000, John Garry wrote:
> > > On 05/12/2024 10:02, Alejandro Colomar wrote:
> > > > On Thu, Dec 05, 2024 at 09:33:18AM +0000, John Garry wrote:
> > > > Nah, we can apply it already.  Just let me know if anything changes
> > > > before the release.
> > > 
> > > I'd suggest that it is ok to merge this now, but Branden seems to have
> > > comments...
> > 
> > I don't generally intend my review comments to be gating, and this is no
> > exception.  (I should try harder to state that explicitly more often.)
> 
> Nah, I just forgot about this patch.  Thanks for the ping; I'll apply it
> later today (if I don't forget again).  :)

I did forget again.  :)

I have applied the patch now.  Thanks!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=e2d3dadf562ac07d086a9732993cb79898bc6b17>


Cheers,
Alex

> 
> Cheers,
> Alex
> 
> > Please don't delay on my account.  :)
> > 
> > Regards,
> > Branden
> 
> 
> 
> -- 
> <https://www.alejandro-colomar.es/>



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

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