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

  to reflect EA API change to explicit namespacing.

Obtained from:	TrustedBSD Project

1 files changed, 40 insertions, 15 deletions

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.