git: 3a6c62e69597 - main - named_attribute.7: Add an explanation for a quirk

The branch main has been updated by rmacklem:

URL: https://cgit.FreeBSD.org/src/commit/?id=3a6c62e69597b012589e1f2f5465747e37ab0f13

commit 3a6c62e69597b012589e1f2f5465747e37ab0f13
Author:     Rick Macklem <rmacklem@FreeBSD.org>
AuthorDate: 2025-08-07 21:12:37 +0000
Commit:     Rick Macklem <rmacklem@FreeBSD.org>
CommitDate: 2025-08-07 21:12:37 +0000

    named_attribute.7: Add an explanation for a quirk
    
    I thought I would be able to come up with a
    ZFS patch to avoid the possibility of there
    being two attributes with the same name for
    a file. This can only occur if the two attributes
    are created when xattr=sa and xattr=dir respectively.
    
    I have not been able to fix this, so this patch
    documents this quirk.
    
    Reviewed by:    kib
    Differential Revision:  https://reviews.freebsd.org/D51751
---
 share/man/man7/named_attribute.7 | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/share/man/man7/named_attribute.7 b/share/man/man7/named_attribute.7
index 4080dfce2fab..a0599ef71496 100644
--- a/share/man/man7/named_attribute.7
+++ b/share/man/man7/named_attribute.7
@@ -3,7 +3,7 @@
 .\"
 .\" SPDX-License-Identifier: BSD-2-Clause
 .\"
-.Dd July 20, 2025
+.Dd August 5, 2025
 .Dt NAMED_ATTRIBUTE 7
 .Os
 .Sh NAME
@@ -153,6 +153,31 @@ property to
 will make the attribute(s) visible as both named attributes
 and via
 .Xr extattr 2 .
+.It
+For ZFS, it is also possible to create two attributes with the same
+name by creating one when the ZFS
+.Dv xattr
+property is set to
+.Dq sa
+and then creating another one with the same name after the ZFS
+property
+.Dv xattr
+has been changed to
+.Dq dir .
+The one created when the ZFS
+.Dv xattr
+property is set to
+.Dq sa
+may be removed via
+.Xr rmextattr 8 .
+.It
+To avoid these issues for ZFS, it is strongly recommended that the ZFS
+property
+.Dv xattr
+be set to
+.Dq dir
+as soon as the file system is created, if named attributes
+are to be used on the file system.
 .El
 .Pp
 The named attribute mechanism/system call interface provides certain
@@ -288,7 +313,8 @@ enters the named attribute directory for the file object
 .Xr truncate 2 ,
 .Xr unlinkat 2 ,
 .Xr write 2 ,
-.Xr zfsprops 7
+.Xr zfsprops 7 ,
+.Xr rmextattr 8
 .Sh HISTORY
 This interface first appeared in
 .Fx 15.0 .