docs/108142: extattr(2) man page incomplete for extattr_list_*()

[Richard Dawe]

>Number:         108142
>Category:       docs
>Synopsis:       extattr(2) man page incomplete for extattr_list_*()
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Jan 20 09:40:17 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator:     Richard Dawe
>Release:        6.1
>Organization:
>Environment:
I don't have access to the box right now. I apologise for that. The documentation is also incomplete in CVS in 6.2-RELEASE, 7-RELEASE and HEAD.
>Description:
The man page for extattr(2) does not describe the extattr_list_file() or extattr_list_fd() functions fully. Specifically:

* It is not described what happens when data == NULL.
* They are not mentioned in the RETURN VALUES section.
* They are not mentioned in the ERRORS section.
>How-To-Repeat:

>Fix:
Browsing the source tree (src/sys/ufs/ufs/ufs_extattr.c, src/sys/kern/vfs_syscalls.c) shows that extattr_list_*() return the size when data == NULL, as with extattr_get_*(). I tested and used this when porting File::ExtAttr <http://search.cpan.org/dist/File-ExtAttr/> to FreeBSD, so it works in practice. ;)

I've attached a patch to the extattr(2) man page to fix these issues.

Patch attached with submission follows:

--- src/lib/libc/sys/extattr_get_file.2.orig	2007-01-20 09:21:31.000000000 +0000
+++ src/lib/libc/sys/extattr_get_file.2	2007-01-20 09:31:10.000000000 +0000
@@ -120,6 +120,8 @@ is
 .Dv NULL
 in a call to
 .Fn extattr_get_file
+and
+.Fn extattr_list_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.
@@ -134,8 +136,9 @@ they do not follow symlinks.
 The
 .Fn extattr_get_fd ,
 .Fn extattr_set_fd ,
+.Fn extattr_delete_fd ,
 and
-.Fn extattr_delete_fd
+.Fn extattr_list_fd ,
 calls are identical to their
 .Qq Li _file
 counterparts except for the first argument.
@@ -170,9 +173,10 @@ change as applications are adapted to us
 Developers are discouraged from relying on its stability.
 .Sh RETURN VALUES
 If successful, the
-.Fn extattr_get_file
+.Fn extattr_get_file ,
+.Fn extattr_set_file ,
 and
-.Fn extattr_set_file
+.Fn extattr_list_file
 calls return the number of bytes
 that were read or written from the
 .Fa data ,
@@ -182,7 +186,9 @@ was
 .Dv NULL ,
 then
 .Fn extattr_get_file
-returns the number of bytes available to read.
+and
+.Fn extattr_list_file
+return 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
@@ -213,8 +219,9 @@ The attribute name was longer than
 The
 .Fn extattr_get_fd ,
 .Fn extattr_set_fd ,
+.Fn extattr_delete_fd ,
 and
-.Fn extattr_delete_fd
+.Fn extattr_list_fd
 system calls may also fail if:
 .Bl -tag -width Er
 .It Bq Er EBADF

>Release-Note:
>Audit-Trail:
>Unformatted: