Re: [PATCH] btrfs: Add the nlink annotation in btrfs_inode_item

[Qu Wenruo]

在 2025/9/28 11:44, Youling Tang 写道:
> Hi, Wenruo
>
> On 9/26/25 16:34, Qu Wenruo wrote:
> > 在 2025/9/26 17:15, Youling Tang 写道:
> > > From: Youling Tang <tangyouling@xxxxxxxxxx>
> > >
> > > When I created a directory, I found that its hard link count was
> > > 1 (unlike other file system phenomena, including the "." directory,
> > > which defaults to an initial count of 2).
> > >
> > > By analyzing the code, it is found that the nlink of the directory
> > > in btrfs has always been kept at 1, which is a deliberate design.
> > >
> > > Adding its comments can prevent it from being mistakenly regarded
> > > as a BUG.
> > >
> > > Signed-off-by: Youling Tang <tangyouling@xxxxxxxxxx>
> > > ---
> > >   include/uapi/linux/btrfs_tree.h | 1 +
> > >   1 file changed, 1 insertion(+)
> > >
> > > diff --git a/include/uapi/linux/btrfs_tree.h b/include/uapi/linux/ 
> > > btrfs_tree.h
> > > index fc29d273845d..b4f7da90fd0e 100644
> > > --- a/include/uapi/linux/btrfs_tree.h
> > > +++ b/include/uapi/linux/btrfs_tree.h
> > > @@ -876,6 +876,7 @@ struct btrfs_inode_item {
> > >       __le64 size;
> > >       __le64 nbytes;
> > >       __le64 block_group;
> > > +    /* nlink in directories is fixed at 1 */
> >
> > nlink of what?
> >
> > Shouldn't be "nlink of directories" or "nlink of directory inodes"?
> >
> >
> > There are better location like btrfs-progs/Documentation/dev/On-disk- 
> > format.rst for this.
> >
> > And you're only adding one single comment for a single member?
> > Even this is a different behavior compared to other fses, why not 
> > explain what the impact of the change?
> >
> >
> > If you really want to add proper comments, spend more time and effort 
> > like commit 9c6b1c4de1c6 ("btrfs: document device locking") to do it 
> > correctly.
>
> My understanding of nlink is as follows, please correct me if I'm wrong,
>
> /*
>   * nlink represents the hard link count (corresponds to inode->i_nlink 
> value).
>   * For directories, this value is always 1, which differs from other 
> filesystems
>   * where a newly created directory has an inode->i_nlink value of 2 
> (including
>   * the "." entry pointing to itself).

Have you checked what's the meaning of the nlink number for other fses 
and why other fses go like that?

Especially the impact to user space tools like find?

>   *
>   * BTRFS maintains parent-child relationships through explicit back 
> references
>   * (BTRFS_INODE_REF_KEY items) rather than link count accounting.
>   *
>   * This design simplifies metadata management in the copy-on-write 
> environment
>   * and enables more reliable consistency checking. Directory link count
>   * verification is performed during tree checking in 
> check_inode_item(), where
>   * values greater than 1 are treated as corruption.
>   *
>   * For regular files, nlink behaves traditionally and represents the 
> actual
>   * hard link count of the file.
>   */
>
> Thanks,
> Youling.
> > Thanks,
> > Qu
> >
> > >       __le32 nlink;
> > >       __le32 uid;
> > >       __le32 gid;