o Update some of the kernel man pages associated with extended attributes

  to reflect EA API change to explicit namespacing.

Obtained from:	TrustedBSD Project

3 files changed, 60 insertions, 27 deletions

diff --git a/share/man/man9/VOP_GETEXTATTR.9 b/share/man/man9/VOP_GETEXTATTR.9
index 97d45ea..e68734d 100644
--- a/share/man/man9/VOP_GETEXTATTR.9
+++ b/share/man/man9/VOP_GETEXTATTR.9
@@ -1,5 +1,5 @@
 .\"-
-.\" Copyright (c) 1999 Robert N. M. Watson
+.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"       $FreeBSD$
+.\" $FreeBSD$
 .\"
 .Dd December 23, 1999
 .Os
@@ -36,7 +36,7 @@
 .Fd #include <sys/vnode.h>
 .Fd #include <sys/extattr.h>
 .Ft int
-.Fn VOP_GETEXTATTR "struct vnode *vp" "const char *name" "struct uio *uio" "struct ucred *cred" "struct proc *p"
+.Fn VOP_GETEXTATTR "struct vnode *vp" "int namespace" "const char *name" "struct uio *uio" "struct ucred *cred" "struct proc *p"
 .Sh DESCRIPTION
 This vnode call may be used to retrieve a specific named extended attribute
 from a file or directory.
@@ -45,6 +45,9 @@ Its arguments are:
 .Bl -tag -width type
 .It Ar vp
 the vnode of the file or directory
+.It Ar namespace
+integer constant indicating which extended attribute namespace the attribute
+name is present in
 .It Ar name
 pointer to a null-terminated character string containing the attribute name
 .It Ar uio
@@ -58,9 +61,10 @@ the process requesting the extended attribute
 The
 .Fa cred
 pointer may be NULL to indicate that access control checks are not to be
-performed, of possible.  This cred setting might be used to allow the 
-kernel to authorize extended attribute retrieval that the active process
-might not be permitted to do.
+performed, if possible.  This
+.Fa cred
+setting might be used to allow the kernel to authorize extended attribute
+retrieval that the active process might not be permitted to do.
 .Pp
 Extended attribute semantics may vary by file system implementing the call.
 More information on extended attributes may be found in
diff --git a/share/man/man9/VOP_SETEXTATTR.9 b/share/man/man9/VOP_SETEXTATTR.9
index 30fc2ca..5083716 100644
--- a/share/man/man9/VOP_SETEXTATTR.9
+++ b/share/man/man9/VOP_SETEXTATTR.9
@@ -1,5 +1,5 @@
 .\"-
-.\" Copyright (c) 1999 Robert N. M. Watson
+.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"       $FreeBSD$
+.\" $FreeBSD$
 .\"
 .Dd December 23, 1999
 .Os
@@ -36,7 +36,7 @@
 .Fd #include <sys/vnode.h>
 .Fd #include <sys/extattr.h>
 .Ft int
-.Fn VOP_SETEXTATTR "struct vnode *vp" "const char *name" "struct uio *uio" "struct ucred *cred" "struct proc *p"
+.Fn VOP_SETEXTATTR "struct vnode *vp" "int namespace" "const char *name" "struct uio *uio" "struct ucred *cred" "struct proc *p"
 .Sh DESCRIPTION
 This vnode call may be used to set specific named extended attribute for a
 file or directory.
@@ -45,6 +45,9 @@ Its arguments are:
 .Bl -tag -width type
 .It Ar vp
 the vnode of the file or directory
+.It Ar namespace
+integer constant indicating which extended attribute namespace the attribute
+name is present in
 .It Ar name
 pointer to a null-terminated character string containing the attribute name
 .It Ar uio
@@ -69,9 +72,10 @@ should be deleted.
 The
 .Fa cred
 pointer may be NULL to indicate that access control checks are not to be
-performed, of possible.  This cred setting might be used to allow the 
-kernel to authorize extended attribute changes that the active process might
-not be permitted to make.
+performed, of possible.  This
+.Fa cred
+setting might be used to allow the kernel to authorize extended attribute
+changes that the active process might not be permitted to make.
 .Pp
 Extended attribute semantics may vary by file system implementing the call.
 More information on extended attributes may be found in
diff --git a/share/man/man9/extattr.9 b/share/man/man9/extattr.9
index 894f791..de41864 100644
--- a/share/man/man9/extattr.9
+++ b/share/man/man9/extattr.9
@@ -1,5 +1,5 @@
 .\"-
-.\" Copyright (c) 1999 Robert N. M. Watson
+.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"       $FreeBSD$
+.\" $FreeBSD$
 .\"
 .Dd December 23, 1999
 .Os
@@ -37,31 +37,56 @@
 .Fd #include <sys/extattr.h>
 .Sh DESCRIPTION
 Named extended attributes allow additional meta-data to be associated
-with vnodes representing files and directories.  The semantics of this
-additional data is that of a "name=value" pair, where a name may
-be defined or undefined, and if defined, associated with zero or more
-bytes of arbitrary binary data.  Reads of this data may return specific
-contiguous regions of the meta-data, in the style of
+with vnodes representing files and directories.
+The semantics of this additional data is that of a "name=value" pair, where
+a name may be defined or undefined, and if defined, associated with zero or
+more bytes of arbitrary binary data.
+Extended attribute names exist within a set of namespaces; each operation
+on an extended attribute is required to provide the namespace to which to
+operation refers.
+If the same name is present in multiple namespaces, the extended attributes
+associated with the names are stored and manipulated independently.
+The following two namespaces are defined universally, although individual
+file systems may implement additional namespaces, or not implement
+these namespaces: EXTATTR_NAMESPACE_USER, EXTATTR_NAMESPACE_SYSTEM.
+The semantics of these attributes are intended to be as follows: user
+attribute data is protected according the the normal discretionary
+and mandatory protections associated with the data in the file or
+directory; system attribute data is protected such that appropriate
+privilege is required to directly access or manipulate these attributes.
+
+Reads of extended attribute data may return specific contiguous regions of
+the meta-data, in the style of
 .Xr VOP_READ 9 ,
 but writes will replace the entire current "value" associated with
-a given name.  As there are a plethora of file systems with differing
-extended attributes, availability and functionality of these functions
-may be limited, and they should be used with awareness of the underlying
-semantics of the supporting file system.  Authorization schemes for
-extended attribute data may also vary by file system, as well as
-maximum attribute size, and whether or not any or specific new attributes
-may be defined.
+a given name.
+As there are a plethora of file systems with differing extended attributes,
+availability and functionality of these functions may be limited, and they
+should be used with awareness of the underlying semantics of the supporting
+file system.
+Authorization schemes for extended attribute data may also vary by file
+system, as well as maximum attribute size, and whether or not any or
+specific new attributes may be defined.
 .Pp
 Extended attributes are named using a null-terminated character string.
-Depending on file system semantics, this name may or may not be
+Depending on underlying file system semantics, this name may or may not be
 case-sensitive.  Appropriate vnode extended attribute calls are:
 .Xr VOP_GETEXTATTR 9 
 and
 .Xr VOP_SETEXTATTR 9 .
 .Sh SEE ALSO
 .Xr VFS 9 ,
+.Xr VFS_EXTATTRCTL 9 ,
 .Xr VOP_GETEXTATTR 9 ,
 .Xr VOP_SETEXTATTR 9
 .Sh AUTHORS
 This man page was written by
 .An Robert Watson .
+.Sh BUGS
+The extended attribute access interface is currently unable to return
+the total size of the attribute, or indicate that the buffer space provided
+by the caller is insufficient to hold all available data.
+In addition, the interface does not provide a mechanism to retrieve
+the current set of available attributes; it has been suggested that
+providing a NULL attribute name should cause a list of defined attributes
+for the passed file or directory, but this is not currently implemented.