From owner-freebsd-doc@FreeBSD.ORG Sat Jan 20 09:40:18 2007 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 910A416A406 for ; Sat, 20 Jan 2007 09:40:18 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [69.147.83.40]) by mx1.freebsd.org (Postfix) with ESMTP id 6C9CB13C467 for ; Sat, 20 Jan 2007 09:40:18 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.4/8.13.4) with ESMTP id l0K9eIFo052444 for ; Sat, 20 Jan 2007 09:40:18 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.4/8.13.4/Submit) id l0K9eIQW052443; Sat, 20 Jan 2007 09:40:18 GMT (envelope-from gnats) Resent-Date: Sat, 20 Jan 2007 09:40:18 GMT Resent-Message-Id: <200701200940.l0K9eIQW052443@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Richard Dawe Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id E369216A402 for ; 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 ; 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 ; 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 To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.0 Cc: Subject: docs/108142: extattr(2) man page incomplete for extattr_list_*() X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 20 Jan 2007 09:40:18 -0000 >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 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: