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

[Youling Tang <youling.tang@linux.dev>]

On 9/28/25 13:16, Qu Wenruo wrote:

>
>
> 在 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@kylinos.cn>
>>>>
>>>> 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@kylinos.cn>
>>>> ---
>>>>   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?
>
I have examined ext4, XFS, and bcachefs. In these filesystems,
when performing the following operations:
```
  # mkdir -p a/b
  # cd a/b
  # ls -la
  drwxr-xr-x 2 root root  6 Sep 28 14:45 .
  drwxr-xr-x 3 root root 15 Sep 28 14:45 ..
```

In btrfs:
```
  # ls -la
  drwxr-xr-x 1 root root 0 Sep 28 14:48 .
  drwxr-xr-x 1 root root 2 Sep 28 14:48 ..
```

In filesystems like ext4, we can see that the link counts for
directory 'a' and 'b' are 3 and 2 respectively:
a: The directory itself + "." pointing to itself + ".." from directory b 
pointing to it
b: The directory itself + "." pointing to itself


nlink changes during directory creation in ext4:
```
ext4_mkdir
     ext4_init_new_dir
         set_nlink(inode, 2) //Initial inode->i_nlink value for new 
directory
     ext4_inc_count(dir) //Increase parent directory's nlink by 1 (for "..")
```

In ext4, when the DIR_NLINK feature is enabled, if a directory's link
count exceeds EXT4_LINK_MAX, it will be permanently set to 1.


nlink changes during directory creation in bcachefs:
```
bch2_mkdir
     bch2_mknod
         __bch2_create
             bch2_create_trans
                 dir_u->bi_nlink++ //If creating a directory, increase 
parent's nlink
             bch2_inode_update_after_write
                 set_nlink(&inode->v, bch2_inode_nlink_get(bi))
                     bch2_inode_nlink_get //If directory, nlink 
increased by 2
```


In XFS, the xfs_create function contains the following comment:
/*
  * A newly created regular or special file just has one directory
  * entry pointing to them, but a directory also the "." entry
  * pointing to itself.
  */

Thanks,
Youling.

> 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;
>>>
>