git: 6b6542ec8446 - main - open.2: Document the O_NAMEDATTR flag

The branch main has been updated by rmacklem:

URL: https://cgit.FreeBSD.org/src/commit/?id=6b6542ec84462c9d1fceb43bffb832e0fd556661

commit 6b6542ec84462c9d1fceb43bffb832e0fd556661
Author:     Rick Macklem <rmacklem@FreeBSD.org>
AuthorDate: 2025-06-04 22:50:16 +0000
Commit:     Rick Macklem <rmacklem@FreeBSD.org>
CommitDate: 2025-06-04 22:50:16 +0000

    open.2: Document the O_NAMEDATTR flag
    
    Commit 2ec2ba7e232d added support for the O_NAMEDATTR flag to
    the open(2) and openat(2) syscalls for main.
    
    This patch updates the man page for this flag.
    
    Another man page that explains named attributes will
    be introduced in a future commit.
    
    This is a content change.
    
    Reviewed by:    emaste (earlier version), kib (earlier version)
    Differential Revision:  https://reviews.freebsd.org/D49691
    Fixes:  2ec2ba7e232d ("vfs: Add VFS/syscall support for Solaris style extended attributes")
---
 lib/libsys/open.2 | 49 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/lib/libsys/open.2 b/lib/libsys/open.2
index 6200723ed85c..84c4f02fce8a 100644
--- a/lib/libsys/open.2
+++ b/lib/libsys/open.2
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd February 28, 2025
+.Dd April 3, 2025
 .Dt OPEN 2
 .Os
 .Sh NAME
@@ -210,6 +210,8 @@ record only the target path in the opened descriptor
 open file referenced by
 .Fa fd
 if path is empty
+.It Dv O_NAMEDATTR
+open a named attribute or named attribute directory
 .El
 .Pp
 Exactly one of the flags
@@ -506,6 +508,42 @@ and the description of the
 .Dv O_CLOEXEC
 flag.
 .Pp
+When the
+.Dv O_NAMEDATTR
+flag is specified for an
+.Fn openat
+where the
+.Fa fd
+argument is for a file object,
+a named attribute for the file object
+is opened and not the file object itself.
+If the
+.Dv O_CREAT
+flag has been specified as well, the named attribute will be
+created if it does not exist.
+When the
+.Dv O_NAMEDATTR
+flag is specified for a
+.Fn open ,
+a named attribute for the current working directory is opened and
+not the current working directory.
+The
+.Fa path
+argument for this
+.Fn openat
+or
+.Fn open
+must be a single component name with no embedded
+.Ql / .
+If the
+.Fa path
+argument is
+.Ql .\&
+then the named attribute directory for the file object is opened.
+(See
+.Xr named_attribute 7
+for more information.)
+.Pp
 The system imposes a limit on the number of file descriptors
 open simultaneously by one process.
 The
@@ -737,6 +775,10 @@ contains a ".." component, the
 .Dv vfs.lookup_cap_dotdot
 .Xr sysctl 3
 is set, and the process is in capability mode.
+.It Bq Er ENOATTR
+.Dv O_NAMEDATTR
+has been specified and the file object is not a named attribute
+directory or named attribute.
 .El
 .Sh SEE ALSO
 .Xr chmod 2 ,
@@ -752,7 +794,8 @@ is set, and the process is in capability mode.
 .Xr umask 2 ,
 .Xr write 2 ,
 .Xr fopen 3 ,
-.Xr capsicum 4
+.Xr capsicum 4 ,
+.Xr named_attribute 7
 .Sh STANDARDS
 These functions are specified by
 .St -p1003.1-2008 .
@@ -801,6 +844,8 @@ function was introduced in
 .Fx 8.0 .
 .Dv O_DSYNC
 appeared in 13.0.
+.Dv O_NAMEDATTR
+appeared in 15.0.
 .Sh BUGS
 The
 .Fa mode