[PATCH] statx.2: Document STATX_SUBVOL

[PATCH] statx.2: Document STATX_SUBVOL

[Kent Overstreet]

Document the new statxt.stx_subvol field.

This would be clearer if we had a proper API for walking subvolumes that
we could refer to, but that's still coming.

Link: https://lore.kernel.org/linux-fsdevel/20240308022914.196982-1-kent.overstreet@linux.dev/
Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
Cc: Alejandro Colomar <alx@kernel.org>
Cc: linux-man@vger.kernel.org
Cc: linux-fsdevel@vger.kernel.org
---
 man2/statx.2 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/man2/statx.2 b/man2/statx.2
index 0dcf7e20bb1f..480e69b46a89 100644
--- a/man2/statx.2
+++ b/man2/statx.2
@@ -68,6 +68,7 @@ struct statx {
     /* Direct I/O alignment restrictions */
     __u32 stx_dio_mem_align;
     __u32 stx_dio_offset_align;
+    __u64 stx_subvol;      /* Subvolume identifier */
 };
 .EE
 .in
@@ -255,6 +256,8 @@ STATX_ALL	The same as STATX_BASIC_STATS | STATX_BTIME.
 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_SUBVOL	Wants stx_subvol
+	(since Linux 6.9; support varies by filesystem)
 .TE
 .in
 .P
@@ -439,6 +442,11 @@ or 0 if direct I/O is not supported on this file.
 This will only be nonzero if
 .I stx_dio_mem_align
 is nonzero, and vice versa.
+.TP
+.I stx_subvolume
+Subvolume number of the current file.
+
+Subvolumes are fancy directories, i.e. they form a tree structure that may be walked recursively.
 .P
 For further information on the above fields, see
 .BR inode (7).
-- 
2.43.0

Re: [PATCH] statx.2: Document STATX_SUBVOL

[Eric Biggers]

On Mon, Mar 11, 2024 at 04:31:36PM -0400, Kent Overstreet wrote:
> Document the new statxt.stx_subvol field.
> 
> This would be clearer if we had a proper API for walking subvolumes that
> we could refer to, but that's still coming.
> 
> Link: https://lore.kernel.org/linux-fsdevel/20240308022914.196982-1-kent.overstreet@linux.dev/
> Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
> Cc: Alejandro Colomar <alx@kernel.org>
> Cc: linux-man@vger.kernel.org
> Cc: linux-fsdevel@vger.kernel.org
> ---
>  man2/statx.2 | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/man2/statx.2 b/man2/statx.2
> index 0dcf7e20bb1f..480e69b46a89 100644
> --- a/man2/statx.2
> +++ b/man2/statx.2
> @@ -68,6 +68,7 @@ struct statx {
>      /* Direct I/O alignment restrictions */
>      __u32 stx_dio_mem_align;
>      __u32 stx_dio_offset_align;
> +    __u64 stx_subvol;      /* Subvolume identifier */
>  };
>  .EE
>  .in
> @@ -255,6 +256,8 @@ STATX_ALL	The same as STATX_BASIC_STATS | STATX_BTIME.
>  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_SUBVOL	Wants stx_subvol
> +	(since Linux 6.9; support varies by filesystem)

The other ones say "Want", not "Wants".

> +.TP
> +.I stx_subvolume

It's stx_subvol, not stx_subvolume.

> +Subvolume number of the current file.
> +
> +Subvolumes are fancy directories, i.e. they form a tree structure that may be walked recursively.

How about documenting which filesystems support it?

- Eric

Re: [PATCH] statx.2: Document STATX_SUBVOL

[Alejandro Colomar]

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

Hi!

On Mon, Mar 11, 2024 at 07:19:08PM -0700, Eric Biggers wrote:
> On Mon, Mar 11, 2024 at 04:31:36PM -0400, Kent Overstreet wrote:
> > Document the new statxt.stx_subvol field.
> > 
> > This would be clearer if we had a proper API for walking subvolumes that
> > we could refer to, but that's still coming.
> > 
> > Link: https://lore.kernel.org/linux-fsdevel/20240308022914.196982-1-kent.overstreet@linux.dev/
> > Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
> > Cc: Alejandro Colomar <alx@kernel.org>
> > Cc: linux-man@vger.kernel.org
> > Cc: linux-fsdevel@vger.kernel.org
> > ---
> >  man2/statx.2 | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> > 
> > diff --git a/man2/statx.2 b/man2/statx.2
> > index 0dcf7e20bb1f..480e69b46a89 100644
> > --- a/man2/statx.2
> > +++ b/man2/statx.2
> > @@ -68,6 +68,7 @@ struct statx {
> >      /* Direct I/O alignment restrictions */
> >      __u32 stx_dio_mem_align;
> >      __u32 stx_dio_offset_align;
> > +    __u64 stx_subvol;      /* Subvolume identifier */
> >  };
> >  .EE
> >  .in
> > @@ -255,6 +256,8 @@ STATX_ALL	The same as STATX_BASIC_STATS | STATX_BTIME.
> >  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_SUBVOL	Wants stx_subvol
> > +	(since Linux 6.9; support varies by filesystem)
> 
> The other ones say "Want", not "Wants".
> 
> > +.TP
> > +.I stx_subvolume
> 
> It's stx_subvol, not stx_subvolume.
> 
> > +Subvolume number of the current file.
> > +

Also, don't use blank lines.  We use '.P' for new paragraphs.

> > +Subvolumes are fancy directories, i.e. they form a tree structure that may be walked recursively.

And please use semantic newlines (see man-pages(7)).

Have a lovely day!
Alex

> 
> How about documenting which filesystems support it?
> 
> - Eric
> 

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

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

Re: [PATCH] statx.2: Document STATX_SUBVOL

[John Garry]

On 15/03/2024 13:47, Alejandro Colomar wrote:
> Hi!


Was there ever an updated version of this patch?

I don't see anything for this in the man pages git yet.


> 
> On Mon, Mar 11, 2024 at 07:19:08PM -0700, Eric Biggers wrote:
>> On Mon, Mar 11, 2024 at 04:31:36PM -0400, Kent Overstreet wrote:
>>> Document the new statxt.stx_subvol field.
>>>
>>> This would be clearer if we had a proper API for walking subvolumes that
>>> we could refer to, but that's still coming.
>>>
>>> Link: https://lore.kernel.org/linux-fsdevel/20240308022914.196982-1-kent.overstreet@linux.dev/
>>> Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
>>> Cc: Alejandro Colomar <alx@kernel.org>
>>> Cc: linux-man@vger.kernel.org
>>> Cc: linux-fsdevel@vger.kernel.org
>>> ---
>>>   man2/statx.2 | 8 ++++++++
>>>   1 file changed, 8 insertions(+)
>>>
>>> diff --git a/man2/statx.2 b/man2/statx.2
>>> index 0dcf7e20bb1f..480e69b46a89 100644
>>> --- a/man2/statx.2
>>> +++ b/man2/statx.2
>>> @@ -68,6 +68,7 @@ struct statx {
>>>       /* Direct I/O alignment restrictions */
>>>       __u32 stx_dio_mem_align;
>>>       __u32 stx_dio_offset_align;
>>> +    __u64 stx_subvol;      /* Subvolume identifier */
>>>   };
>>>   .EE
>>>   .in
>>> @@ -255,6 +256,8 @@ STATX_ALL	The same as STATX_BASIC_STATS | STATX_BTIME.
>>>   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_SUBVOL	Wants stx_subvol
>>> +	(since Linux 6.9; support varies by filesystem)
>>
>> The other ones say "Want", not "Wants".
>>
>>> +.TP
>>> +.I stx_subvolume
>>
>> It's stx_subvol, not stx_subvolume.
>>
>>> +Subvolume number of the current file.
>>> +
> 
> Also, don't use blank lines.  We use '.P' for new paragraphs.
> 
>>> +Subvolumes are fancy directories, i.e. they form a tree structure that may be walked recursively.
> 
> And please use semantic newlines (see man-pages(7)).
> 
> Have a lovely day!
> Alex
> 
>>
>> How about documenting which filesystems support it?
>>
>> - Eric
>>
> 

Re: [PATCH] statx.2: Document STATX_SUBVOL

[Alejandro Colomar]

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

Hi John,

On Mon, Jun 17, 2024 at 08:36:34AM GMT, John Garry wrote:
> On 15/03/2024 13:47, Alejandro Colomar wrote:
> > Hi!
> 
> 
> Was there ever an updated version of this patch?
> 
> I don't see anything for this in the man pages git yet.

When I pick a patch, I explicitly notify the author in a reply in the
same thread.  I haven't.  I commented some issues with the patch so that
the author sends some revised patch.

Have a lovely day!
Alex


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

Re: [PATCH] statx.2: Document STATX_SUBVOL

[John Garry]

Hi Alex,

> 
> On Mon, Jun 17, 2024 at 08:36:34AM GMT, John Garry wrote:
>> On 15/03/2024 13:47, Alejandro Colomar wrote:
>>> Hi!
>>
>> Was there ever an updated version of this patch?
>>
>> I don't see anything for this in the man pages git yet.
> When I pick a patch, I explicitly notify the author in a reply in the
> same thread.  I haven't.  I commented some issues with the patch so that
> the author sends some revised patch.
> 

I wanted to send a rebased version of my series 
https://lore.kernel.org/linux-api/20240124112731.28579-1-john.g.garry@oracle.com/

[it was an oversight to not cc you / linux-man@vger.kernel.org there]

Anyway I would like to use a proper baseline, which includes 
STATX_SUBVOL info. So I will send an updated patch for STATX_SUBVOL if I 
don't see it soon.

Thanks,
John

Re: [PATCH] statx.2: Document STATX_SUBVOL

[Alejandro Colomar]

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

Hi John,

On Tue, Jun 18, 2024 at 10:19:05AM GMT, John Garry wrote:
> Hi Alex,
> 
> > 
> > On Mon, Jun 17, 2024 at 08:36:34AM GMT, John Garry wrote:
> > > On 15/03/2024 13:47, Alejandro Colomar wrote:
> > > > Hi!
> > > 
> > > Was there ever an updated version of this patch?
> > > 
> > > I don't see anything for this in the man pages git yet.
> > When I pick a patch, I explicitly notify the author in a reply in the
> > same thread.  I haven't.  I commented some issues with the patch so that
> > the author sends some revised patch.
> > 
> 
> I wanted to send a rebased version of my series https://lore.kernel.org/linux-api/20240124112731.28579-1-john.g.garry@oracle.com/
> 
> [it was an oversight to not cc you / linux-man@vger.kernel.org there]
> 
> Anyway I would like to use a proper baseline, which includes STATX_SUBVOL
> info. So I will send an updated patch for STATX_SUBVOL if I don't see it
> soon.

Thanks!  no problem.

Have a lovely day!
Alex

> 
> Thanks,
> John
> 

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

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

Re: [PATCH] statx.2: Document STATX_SUBVOL

[Alejandro Colomar]

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

Hi Kent, Eric, John,

Thread: <https://lore.kernel.org/linux-man/20240311203221.2118219-1-kent.overstreet@linux.dev/T/#u>

I revisited this thread today and checked that there wasn't an updated
patch.  Would you like to send a revised version of the patch?

Have a lovely day!
Alex

On Tue, Jun 18, 2024 at 02:14:46PM +0200, Alejandro Colomar wrote:
> Hi John,
> 
> On Tue, Jun 18, 2024 at 10:19:05AM GMT, John Garry wrote:
> > Hi Alex,
> > 
> > > 
> > > On Mon, Jun 17, 2024 at 08:36:34AM GMT, John Garry wrote:
> > > > On 15/03/2024 13:47, Alejandro Colomar wrote:
> > > > > Hi!
> > > > 
> > > > Was there ever an updated version of this patch?
> > > > 
> > > > I don't see anything for this in the man pages git yet.
> > > When I pick a patch, I explicitly notify the author in a reply in the
> > > same thread.  I haven't.  I commented some issues with the patch so that
> > > the author sends some revised patch.
> > > 
> > 
> > I wanted to send a rebased version of my series https://lore.kernel.org/linux-api/20240124112731.28579-1-john.g.garry@oracle.com/
> > 
> > [it was an oversight to not cc you / linux-man@vger.kernel.org there]
> > 
> > Anyway I would like to use a proper baseline, which includes STATX_SUBVOL
> > info. So I will send an updated patch for STATX_SUBVOL if I don't see it
> > soon.
> 
> Thanks!  no problem.
> 
> Have a lovely day!
> Alex
> 
> > 
> > Thanks,
> > John
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



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

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

Re: [PATCH] statx.2: Document STATX_SUBVOL

[John Garry]

On 24/11/2024 13:35, Alejandro Colomar wrote:
> Hi Kent, Eric, John,
> 
> Thread: <https://lore.kernel.org/linux-man/20240311203221.2118219-1-kent.overstreet@linux.dev/T/#u>
> 
> I revisited this thread today and checked that there wasn't an updated
> patch.  Would you like to send a revised version of the patch?

Hi Alex,

Wasn't this done in the following:

commit d0621648b4b5a356e86cea23e842f2591461f0cf
Author: Kent Overstreet <kent.overstreet@linux.dev>
Date:   Thu Jun 20 13:00:17 2024 +0000

    statx.2: Document STATX_SUBVOL

    Document the new statx.stx_subvol field.

    This would be clearer if we had a proper API for walking subvolumes that
    we could refer to, but that's still coming.

    Link: 
https://urldefense.com/v3/__https://lore.kernel.org/linux-fsdevel/20240308022914.196982-1-kent.overstreet@linux.dev/__;!!ACWV5N9M2RV99hQ!JYMR3Qwb11MmwlhEqgGhq3ITse9gIJ2sfyZQHyiVMQsb77VfyLGvmdLonkpcrGymbqfkUZE0DnYahWZPrc-vZG1rkIHW$ 

    Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
    [jpg: mention supported FSes and formatting improvements]
    Signed-off-by: John Garry <john.g.garry@oracle.com>
    Cc: Eric Biggers <ebiggers@kernel.org>
    Cc: <linux-fsdevel@vger.kernel.org>
    Message-ID: <20240620130017.2686511-1-john.g.garry@oracle.com>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>

BTW, on another totally separate topic, there is nothing for this:

https://lore.kernel.org/linux-fsdevel/f20a786f-156a-4772-8633-66518bd09a02@oracle.com/

right?

Thanks,
John


> 
> Have a lovely day!
> Alex
> 
> On Tue, Jun 18, 2024 at 02:14:46PM +0200, Alejandro Colomar wrote:
>> Hi John,
>>
>> On Tue, Jun 18, 2024 at 10:19:05AM GMT, John Garry wrote:
>>> Hi Alex,
>>>
>>>>
>>>> On Mon, Jun 17, 2024 at 08:36:34AM GMT, John Garry wrote:
>>>>> On 15/03/2024 13:47, Alejandro Colomar wrote:
>>>>>> Hi!
>>>>>
>>>>> Was there ever an updated version of this patch?
>>>>>
>>>>> I don't see anything for this in the man pages git yet.
>>>> When I pick a patch, I explicitly notify the author in a reply in the
>>>> same thread.  I haven't.  I commented some issues with the patch so that
>>>> the author sends some revised patch.
>>>>
>>>
>>> I wanted to send a rebased version of my series https://lore.kernel.org/linux-api/20240124112731.28579-1-john.g.garry@oracle.com/
>>>
>>> [it was an oversight to not cc you / linux-man@vger.kernel.org there]
>>>
>>> Anyway I would like to use a proper baseline, which includes STATX_SUBVOL
>>> info. So I will send an updated patch for STATX_SUBVOL if I don't see it
>>> soon.
>>
>> Thanks!  no problem.
>>
>> Have a lovely day!
>> Alex
>>
>>>
>>> Thanks,
>>> John
>>>
>>
>> -- 
>> <https://www.alejandro-colomar.es/>
> 
> 
> 

Re: [PATCH] statx.2: Document STATX_SUBVOL

[Alejandro Colomar]

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

Hi John,

On Mon, Nov 25, 2024 at 09:03:50AM +0000, John Garry wrote:
> On 24/11/2024 13:35, Alejandro Colomar wrote:
> > Hi Kent, Eric, John,
> > 
> > Thread: <https://lore.kernel.org/linux-man/20240311203221.2118219-1-kent.overstreet@linux.dev/T/#u>
> > 
> > I revisited this thread today and checked that there wasn't an updated
> > patch.  Would you like to send a revised version of the patch?
> 
> Hi Alex,
> 
> Wasn't this done in the following:

Ahh, true.  I cound't find it because it was in another thread.  That's
why I prefer that patch v2 is a reply to the same thread that sent patch
v1.  :-)  I'll have to document this in the CONTRIBUTING.d/* guidelines.

Thanks!

> 
> commit d0621648b4b5a356e86cea23e842f2591461f0cf
> Author: Kent Overstreet <kent.overstreet@linux.dev>
> Date:   Thu Jun 20 13:00:17 2024 +0000
> 
>    statx.2: Document STATX_SUBVOL
> 
>    Document the new statx.stx_subvol field.
> 
>    This would be clearer if we had a proper API for walking subvolumes that
>    we could refer to, but that's still coming.
> 
>    Link: https://urldefense.com/v3/__https://lore.kernel.org/linux-fsdevel/20240308022914.196982-1-kent.overstreet@linux.dev/__;!!ACWV5N9M2RV99hQ!JYMR3Qwb11MmwlhEqgGhq3ITse9gIJ2sfyZQHyiVMQsb77VfyLGvmdLonkpcrGymbqfkUZE0DnYahWZPrc-vZG1rkIHW$
> 
>    Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
>    [jpg: mention supported FSes and formatting improvements]
>    Signed-off-by: John Garry <john.g.garry@oracle.com>
>    Cc: Eric Biggers <ebiggers@kernel.org>
>    Cc: <linux-fsdevel@vger.kernel.org>
>    Message-ID: <20240620130017.2686511-1-john.g.garry@oracle.com>
>    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> BTW, on another totally separate topic, there is nothing for this:
> 
> https://lore.kernel.org/linux-fsdevel/f20a786f-156a-4772-8633-66518bd09a02@oracle.com/
> 
> right?

grep(1) seems to say you're right.

alx@devuan:~/src/linux/man-pages/man-pages/contrib$ grep -rn RWF_NOAPPEND
alx@devuan:~/src/linux/man-pages/man-pages/contrib$ 

I guess we should ping that thread.

Have a lovely day!
Alex

> 
> Thanks,
> John

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

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