Date: Sat, 20 Jan 2007 09:39:53 GMT From: Richard Dawe<rich@phekda.gotadsl.co.uk> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/108142: extattr(2) man page incomplete for extattr_list_*() Message-ID: <200701200939.l0K9drGv014872@www.freebsd.org> Resent-Message-ID: <200701200940.l0K9eIQW052443@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200701200939.l0K9drGv014872>