From nobody@FreeBSD.org  Sat Jan 20 09:39:53 2007
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id E369216A402
	for <freebsd-gnats-submit@FreeBSD.org>; Sat, 20 Jan 2007 09:39:53 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [69.147.83.33])
	by mx1.freebsd.org (Postfix) with ESMTP id 9FB7B13C459
	for <freebsd-gnats-submit@FreeBSD.org>; Sat, 20 Jan 2007 09:39:53 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id l0K9drsf014873
	for <freebsd-gnats-submit@FreeBSD.org>; Sat, 20 Jan 2007 09:39:53 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id l0K9drGv014872;
	Sat, 20 Jan 2007 09:39:53 GMT
	(envelope-from nobody)
Message-Id: <200701200939.l0K9drGv014872@www.freebsd.org>
Date: Sat, 20 Jan 2007 09:39:53 GMT
From: Richard Dawe<rich@phekda.gotadsl.co.uk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: extattr(2) man page incomplete for extattr_list_*()
X-Send-Pr-Version: www-3.0

>Number:         108142
>Category:       docs
>Synopsis:       [patch] extattr(2) man page incomplete for extattr_list_*()
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Jan 20 09:40:17 GMT 2007
>Closed-Date:    Thu Aug 28 00:29:32 UTC 2008
>Last-Modified:  Thu Aug 28 00:30:01 UTC 2008
>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:
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Jan 29 18:15:58 UTC 2008 
State-Changed-Why:  
Patched in HEAD, thanks for the submission! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Jan 29 18:15:58 UTC 2008 
Responsible-Changed-Why:  
Over to me, MFC reminder. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=108142 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/108142: commit references a PR
Date: Tue, 29 Jan 2008 18:15:45 +0000 (UTC)

 trhodes     2008-01-29 18:15:38 UTC
 
   FreeBSD src repository
 
   Modified files:
     lib/libc/sys         extattr_get_file.2 
   Log:
   Update this manual page to describe the extattr_list_file() and the
   extattr_list_fd() functions.
   
   PR:             108142
   Submitted by:   Richard Dawe <rich@phekda.gotadsl.co.uk>
   Reviewed by:    kientzle
   
   Revision  Changes    Path
   1.19      +13 -6     src/lib/libc/sys/extattr_get_file.2
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/108142: commit references a PR
Date: Sun,  3 Aug 2008 19:00:27 +0000 (UTC)

 trhodes     2008-08-03 18:59:56 UTC
 
   FreeBSD src repository
 
   Modified files:        (Branch: RELENG_7)
     lib/libc/sys         extattr_get_file.2 
   Log:
   SVN rev 181259 on 2008-08-03 18:59:56Z by trhodes
   
   MFC r175798:
   
   Update this manual page to describe the extattr_list_file() and the
   extattr_list_fd() functions.
   
   PR:             108142
   Submitted by:   Richard Dawe <rich@phekda.gotadsl.co.uk>
   Reviewed by:    kientzle
   
   Revision  Changes    Path
   1.18.2.1  +13 -6     src/lib/libc/sys/extattr_get_file.2
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Thu Aug 28 00:28:57 UTC 2008 
State-Changed-Why:  
Final merge completed, thanks for the submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=108142 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/108142: commit references a PR
Date: Thu, 28 Aug 2008 00:28:53 +0000 (UTC)

 trhodes     2008-08-28 00:28:29 UTC
 
   FreeBSD src repository
 
   Modified files:        (Branch: RELENG_6)
     lib/libc/sys         extattr_get_file.2 
   Log:
   SVN rev 182313 on 2008-08-28 00:28:29Z by trhodes
   
   MFC r175798:
   
   Update this manual page to describe the extattr_list_file() and the
   extattr_list_fd() functions.
   
   PR:             108142
   Submitted by:   Richard Dawe <rich@phekda.gotadsl.co.uk>
   Reviewed by:    kientzle
   
   Revision  Changes    Path
   1.17.2.1  +13 -6     src/lib/libc/sys/extattr_get_file.2
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
