[prev in list] [next in list] [prev in thread] [next in thread] 

List:       freebsd-doc
Subject:    docs/108142: extattr(2) man page incomplete for extattr_list_*()
From:       Richard Dawe<rich () phekda ! gotadsl ! co ! uk>
Date:       2007-01-20 9:39:53
Message-ID: 200701200939.l0K9drGv014872 () www ! freebsd ! org
[Download RAW message or body]


> 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:
_______________________________________________
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscribe@freebsd.org"


[prev in list] [next in list] [prev in thread] [next in thread]