Re: [PATCH] statx.2: Document STATX_SUBVOL

[Alejandro Colomar <alx@kernel.org>]

[-- 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 --]