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

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

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).
  *
  * 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;
>