From nobody@FreeBSD.org  Tue Nov  8 19:12:36 2011
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id D986B1065670
	for <freebsd-gnats-submit@FreeBSD.org>; Tue,  8 Nov 2011 19:12:36 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id C998B8FC15
	for <freebsd-gnats-submit@FreeBSD.org>; Tue,  8 Nov 2011 19:12:36 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id pA8JCavD081125
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 8 Nov 2011 19:12:36 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id pA8JCajp081124;
	Tue, 8 Nov 2011 19:12:36 GMT
	(envelope-from nobody)
Message-Id: <201111081912.pA8JCajp081124@red.freebsd.org>
Date: Tue, 8 Nov 2011 19:12:36 GMT
From: Garrett Cooper <yaneurabeya@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Documentation lacking for getfacl/setfacl
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         162380
>Category:       docs
>Synopsis:       Documentation lacking for getfacl/setfacl
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    trasz
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Nov 08 19:20:08 UTC 2011
>Closed-Date:    Mon Sep 17 11:22:27 UTC 2012
>Last-Modified:  Sun Feb 03 22:29:45 UTC 2013
>Originator:     Garrett Cooper
>Release:        9.0-RC1
>Organization:
n/a
>Environment:
FreeBSD bayonetta.local 9.0-RC1 FreeBSD 9.0-RC1 #0: Sat Nov  5 17:19:05 PDT 2011     root@bayonetta.local:/usr/obj/store/freebsd/stable/9/sys/BAYONETTA  amd64
>Description:
getfacl and setfacl are lacking documentation, s.t. it's hard to interpret ACL output from getfacl and it's hard to interpret what inputs need to be provided to setfacl in order to get the desired results in terms of permissions, etc.

Basically, it would be nice if acl(3) said what the print outs meant, and getfacl(1) and setfacl(1) referenced acl(3) so that everything could be tied together appropriately and people could better understand what the utilities do.
>How-To-Repeat:

>Fix:


>Release-Note:
>Audit-Trail:

From: Garrett Cooper <yaneurabeya@gmail.com>
To: bug-followup@FreeBSD.org, yanegomi@gmail.com
Cc:  
Subject: Re: docs/162380: Documentation lacking for getfacl/setfacl
Date: Wed, 11 Jan 2012 16:45:14 -0800

 Here's the code that 'documents' the flags output via getfacl, can be
 set via setfacl, etc:
 
 struct flagnames_struct a_access_masks[] =
     {{ ACL_READ_DATA, "read_data", 'r'},
      { ACL_WRITE_DATA, "write_data", 'w'},
      { ACL_EXECUTE, "execute", 'x'},
      { ACL_APPEND_DATA, "append_data", 'p'},
      { ACL_DELETE_CHILD, "delete_child", 'D'},
      { ACL_DELETE, "delete", 'd'},
      { ACL_READ_ATTRIBUTES, "read_attributes", 'a'},
      { ACL_WRITE_ATTRIBUTES, "write_attributes", 'A'},
      { ACL_READ_NAMED_ATTRS, "read_xattr", 'R'},
      { ACL_WRITE_NAMED_ATTRS, "write_xattr", 'W'},
      { ACL_READ_ACL, "read_acl", 'c'},
      { ACL_WRITE_ACL, "write_acl", 'C'},
      { ACL_WRITE_OWNER, "write_owner", 'o'},
      { ACL_SYNCHRONIZE, "synchronize", 's'},
      { ACL_FULL_SET, "full_set", '\0'},
      { ACL_MODIFY_SET, "modify_set", '\0'},
      { ACL_READ_SET, "read_set", '\0'},
      { ACL_WRITE_SET, "write_set", '\0'},
      { 0, 0, 0}};
 
 The code lives in lib/libc/posix1e/acl_support_nfs4.c
 
 Thanks!
 -Garrett

From: Garrett Cooper <yaneurabeya@gmail.com>
To: bug-followup@FreeBSD.org, yanegomi@gmail.com
Cc:  
Subject: Re: docs/162380: Documentation lacking for getfacl/setfacl
Date: Mon, 16 Jan 2012 12:18:10 -0800

     Correction: the documentation for _get_facl is lacking -- not
 setfacl. setfacl describes everything properly -- minus the
 synchronization flag being the wrong case, e.g. 'S', as opposed to
 's'.
 Thanks,
 -Garrett
Responsible-Changed-From-To: freebsd-doc->trasz 
Responsible-Changed-By: trasz 
Responsible-Changed-When: Mon Sep 3 17:28:16 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

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

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162380: commit references a PR
Date: Mon,  3 Sep 2012 17:26:32 +0000 (UTC)

 Author: trasz
 Date: Mon Sep  3 17:26:20 2012
 New Revision: 240076
 URL: http://svn.freebsd.org/changeset/base/240076
 
 Log:
   Fix compact form of "synchronize" permission in setfacl(1) manual page - it
   should be "s", not "S".
   
   PR:		docs/162380
   MFC after:	2 weeks
 
 Modified:
   head/bin/setfacl/setfacl.1
 
 Modified: head/bin/setfacl/setfacl.1
 ==============================================================================
 --- head/bin/setfacl/setfacl.1	Mon Sep  3 16:51:41 2012	(r240075)
 +++ head/bin/setfacl/setfacl.1	Mon Sep  3 17:26:20 2012	(r240076)
 @@ -26,7 +26,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd April 9, 2011
 +.Dd September 2, 2012
  .Dt SETFACL 1
  .Os
  .Sh NAME
 @@ -337,7 +337,7 @@ read_acl
  write_acl
  .It o
  write_owner
 -.It S
 +.It s
  synchronize
  .El
  .Pp
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->patched 
State-Changed-By: trasz 
State-Changed-When: Tue Sep 4 12:05:46 UTC 2012 
State-Changed-Why:  
Fixed in HEAD. 

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

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162380: commit references a PR
Date: Tue,  4 Sep 2012 12:02:38 +0000 (UTC)

 Author: trasz
 Date: Tue Sep  4 12:02:23 2012
 New Revision: 240085
 URL: http://svn.freebsd.org/changeset/base/240085
 
 Log:
   In getfacl(1) manual page, mention where to read about the ACL syntax.
   PR submitter suggested adding it to acl(3) instead, but I don't think
   pointing ordinary users at section 3 is a good idea.
   
   PR:		docs/162380
   MFC after:	1 month
 
 Modified:
   head/bin/getfacl/getfacl.1
 
 Modified: head/bin/getfacl/getfacl.1
 ==============================================================================
 --- head/bin/getfacl/getfacl.1	Tue Sep  4 11:50:13 2012	(r240084)
 +++ head/bin/getfacl/getfacl.1	Tue Sep  4 12:02:23 2012	(r240085)
 @@ -97,6 +97,10 @@ then
  reads a list of pathnames, each terminated by one newline character,
  from the standard input.
  .El
 +.Pp
 +For an explanation of the ACL syntax, see the
 +.Xr setfacl 1
 +manual page.
  .Sh EXIT STATUS
  .Ex -std
  .Sh EXAMPLES
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: trasz 
State-Changed-When: Mon Sep 17 11:22:27 UTC 2012 
State-Changed-Why:  
MFC-ed to 9-STABLE. 

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

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162380: commit references a PR
Date: Mon, 17 Sep 2012 11:22:08 +0000 (UTC)

 Author: trasz
 Date: Mon Sep 17 11:21:57 2012
 New Revision: 240598
 URL: http://svn.freebsd.org/changeset/base/240598
 
 Log:
   MFC r240076:
   
   Fix compact form of "synchronize" permission in setfacl(1) manual page - it
   should be "s", not "S".
   
   PR:		docs/162380
 
 Modified:
   stable/9/bin/setfacl/setfacl.1
 Directory Properties:
   stable/9/bin/setfacl/   (props changed)
 
 Modified: stable/9/bin/setfacl/setfacl.1
 ==============================================================================
 --- stable/9/bin/setfacl/setfacl.1	Mon Sep 17 09:32:11 2012	(r240597)
 +++ stable/9/bin/setfacl/setfacl.1	Mon Sep 17 11:21:57 2012	(r240598)
 @@ -26,7 +26,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd April 9, 2011
 +.Dd September 2, 2012
  .Dt SETFACL 1
  .Os
  .Sh NAME
 @@ -337,7 +337,7 @@ read_acl
  write_acl
  .It o
  write_owner
 -.It S
 +.It s
  synchronize
  .El
  .Pp
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162380: commit references a PR
Date: Thu,  4 Oct 2012 08:53:18 +0000 (UTC)

 Author: trasz
 Date: Thu Oct  4 08:43:49 2012
 New Revision: 241186
 URL: http://svn.freebsd.org/changeset/base/241186
 
 Log:
   MFC r240085:
   
   In getfacl(1) manual page, mention where to read about the ACL syntax.
   PR submitter suggested adding it to acl(3) instead, but I don't think
   pointing ordinary users at section 3 is a good idea.
   
   PR:		docs/162380
 
 Modified:
   stable/9/bin/getfacl/getfacl.1
 Directory Properties:
   stable/9/bin/getfacl/   (props changed)
 
 Modified: stable/9/bin/getfacl/getfacl.1
 ==============================================================================
 --- stable/9/bin/getfacl/getfacl.1	Thu Oct  4 08:33:46 2012	(r241185)
 +++ stable/9/bin/getfacl/getfacl.1	Thu Oct  4 08:43:49 2012	(r241186)
 @@ -97,6 +97,10 @@ then
  reads a list of pathnames, each terminated by one newline character,
  from the standard input.
  .El
 +.Pp
 +For an explanation of the ACL syntax, see the
 +.Xr setfacl 1
 +manual page.
  .Sh EXIT STATUS
  .Ex -std
  .Sh EXAMPLES
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
>Unformatted:
