Part III: Update extended attribute system call interface documentation.

Obtained from:	TrustedBSD Project
Sponsored by:	DARPA, NAI Labs

1 files changed, 39 insertions, 18 deletions

diff --git a/lib/libc/sys/extattr_get_file.2 b/lib/libc/sys/extattr_get_file.2
index ba83572..23a0e00 100644
--- a/lib/libc/sys/extattr_get_file.2
+++ b/lib/libc/sys/extattr_get_file.2
@@ -42,16 +42,16 @@
 .In sys/types.h
 .In sys/extattr.h
 .In sys/uio.h
+.Ft ssize_t
+.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
 .Ft int
-.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "struct iovec *iovp" "unsigned iovcnt"
-.Ft int
-.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "struct iovec *iovp" "unsigned iovcnt"
+.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
 .Ft int
 .Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
+.Ft ssize_t
+.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
 .Ft int
-.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "struct iovec *iovp" "unsigned iovcnt"
-.Ft int
-.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "struct iovec *iovp" "unsigned iovcnt"
+.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
 .Ft int
 .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
 .Sh DESCRIPTION
@@ -63,12 +63,16 @@ pairs within a set of namespaces.
 The
 .Fn extattr_get_file
 call retrieves the value of the specified extended attribute into
-.Fa iovp .
+a buffer pointed to by
+.Fa data
+of size
+.Fa nbytes
+.
 The
 .Fn extattr_set_file
 call sets the value of the specified extended attribute to the data
 described by
-.Fa iovp .
+.Fa data .
 The
 .Fn extattr_delete_file
 call deletes the extended attribute specified.
@@ -77,14 +81,23 @@ The
 and
 .Fn extattr_set_file
 calls consume the
-.Fa iovp
+.Fa data
 and
-.Fa iovcnt
+.Fa nbytes
 arguments in the style of
-.Xr readv 2
+.Xr read 2
 and
-.Xr writev 2 ,
+.Xr write 2 ,
 respectively.
+If
+.Fa data
+is
+.Dv NULL
+in a call to
+.Fn extattr_get_file
+then the size of defined extended attribute data will be returned, rather
+than the quantity read, permitting applications to test the size of the
+data without performing a read.
 .Pp
 The
 .Fn extatttr_get_fd ,
@@ -114,7 +127,7 @@ the name of the extended attribute
 Named extended attribute semantics vary by filesystem implementing the call.
 Not all operations may be supported for a particular attribute.
 Additionally, the format of the data in
-.Fa iovp
+.Fa data
 is attribute-specific.
 .Pp
 For more information on named extended attributes, please see
@@ -130,8 +143,14 @@ and
 .Fn extattr_set_file
 calls return the number of bytes
 that were read or written from the
-.Fa iovp ,
-respectively.
+.Fa data ,
+respectively, or if
+.Fa data
+was
+.Dv NULL ,
+then
+.Fn extattr_get_file
+returns the number of bytes available to read.
 If any of the calls are unsuccessful, the value \-1 is returned
 and the global variable
 .Va errno
@@ -146,9 +165,11 @@ other errors it desires.
 .It Bq Er EFAULT
 .Fa attrnamespace ,
 .Fa attrname ,
-or
-.Fa iovp
-point outside the process's allocated address space.
+or the memory range defined by
+.Fa data
+and
+.Fa nbytes
+points outside the process's allocated address space.
 .It Bq Er ENAMETOOLONG
 The attribute name was longer than
 .Dv EXTATTR_MAXNAMELEN .