PERFORCE change 147230 for review

Tue Aug 12 12:55:31 UTC 2008

http://perforce.freebsd.org/chv.cgi?CH=147230

Change 147230 by trasz at trasz_traszkan on 2008/08/12 12:55:07

	Improve manual pages.

Affected files ...

.. //depot/projects/soc2008/trasz_nfs4acl/TODO#41 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_add_flag_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_add_perm.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_clear_flags_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_brand_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_extended_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_flagset_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_extended_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_flagset_np.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_tag_type.3#2 edit

Differences ...

==== //depot/projects/soc2008/trasz_nfs4acl/TODO#41 (text+ko) ====

@@ -8,10 +8,6 @@
 
 - Enhance fstest with checks for NFS4 ACL functionality.
 
-- Add the information about branding to manual pages.
-
-- Add the information about correct constants to the manual pages.
-
 - Make 'struct acl' variable size.
 
 - Benchmark things.

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_add_flag_np.3#2 (text+ko) ====

@@ -49,6 +49,15 @@
 .Pp
 Note: it is not considered an error to attempt to add flags
 that already exist in the flagset.
+.Pp
+Valid values are:
+.Pp
+.Bd -literal -offset indent -compact
+ACL_ENTRY_FILE_INHERIT		Will be inherited by files.
+ACL_ENTRY_DIRECTORY_INHERIT	Will be inherited by directories.
+ACL_ENTRY_LIMIT_INHERIT		Will not propagate.
+ACL_ENTRY_ONLY_INHERIT		Inherit-only.
+.Ed
 .Sh RETURN VALUES
 .Rv -std acl_add_flag_np
 .Sh ERRORS

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_add_perm.3#2 (text+ko) ====

@@ -49,6 +49,46 @@
 .Pp
 Note: it is not considered an error to attempt to add permissions
 that already exist in the permission set.
+.Pp
+For POSIX.1e ACLs, valid values are:
+.Pp
+.Bd -literal -offset indent -compact
+ACL_EXECUTE		Execute permission.
+ACL_WRITE		Write permission.
+ACL_READ		Read permission.
+.Ed
+.Pp
+For NFS4 ACLs, valid values are:
+.Pp
+.Bd -literal -offset indent -compact
+ACL_READ_DATA		Read permission.
+ACL_LIST_DIRECTORY	Same as ACL_READ_DATA.
+ACL_WRITE_DATA		Write permission, or permission to create files.
+ACL_ADD_FILE		Same as ACL_READ_DATA.
+ACL_APPEND_DATA		Permission to create directories.  Unused for files.
+ACL_ADD_SUBDIRECTORY	Same as ACL_APPEND_DATA.
+ACL_READ_NAMED_ATTRS	Unused.
+ACL_WRITE_NAMED_ATTRS	Unused.
+ACL_EXECUTE		Execute permission.
+ACL_DELETE_CHILD	Permission to delete files and subdirectories.
+ACL_READ_ATTRIBUTES	Permission to read basic attributes.
+ACL_WRITE_ATTRIBUTES	Permission to change basic attributes.
+ACL_DELETE		Permission to delete the object this ACL is placed on.
+ACL_READ_ACL		Permission to read ACL.
+ACL_WRITE_ACL		Permission to change the ACL and file mode.
+ACL_SYNCHRONIZE		Unused.
+.Ed
+.Pp
+Calling
+.Fn acl_add_perm
+with
+.Fa perm
+equal to ACL_WRITE or ACL_READ brands the ACL as POSIX.
+Calling it with ACL_READ_DATA, ACL_LIST_DIRECTORY, ACL_WRITE_DATA,
+ACL_ADD_FILE, ACL_APPEND_DATA, ACL_ADD_SUBDIRECTORY, ACL_READ_NAMED_ATTRS,
+ACL_WRITE_NAMED_ATTRS, ACL_DELETE_CHILD, ACL_READ_ATTRIBUTES,
+ACL_WRITE_ATTRIBUTES, ACL_DELETE, ACL_READ_ACL, ACL_WRITE_ACL
+or ACL_SYNCHRONIZE brands the ACL as NFS4.
 .Sh RETURN VALUES
 .Rv -std acl_add_perm
 .Sh ERRORS
@@ -65,11 +105,13 @@
 does not contain a valid
 .Vt acl_perm_t
 value.
+ACL is already branded differently.
 .El
 .Sh SEE ALSO
 .Xr acl 3 ,
 .Xr acl_clear_perms 3 ,
 .Xr acl_delete_perm 3 ,
+.Xr acl_get_brand_np 3 ,
 .Xr acl_get_permset 3 ,
 .Xr acl_set_permset 3 ,
 .Xr posix1e 3

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_clear_flags_np.3#2 (text+ko) ====


==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_brand_np.3#2 (text+ko) ====

@@ -48,6 +48,12 @@
 .Fa brand_p
 will be set to the ACL brand of the ACL
 .Fa acl .
+.Pp
+Branding is an internal mechanism intended to prevent mixing POSIX.1e
+and NFS4 entries by mistake.
+The first call to function that is specific for one particular brand - POSIX
+or NFS4 - "brands" the ACL.  Calling another function specific to another
+brand will result in error.
 .Sh RETURN VALUES
 .Rv -std acl_get_brand_np
 .Sh ERRORS

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_extended_np.3#2 (text+ko) ====

@@ -30,7 +30,7 @@
 .Os
 .Sh NAME
 .Nm acl_get_extended_np
-.Nd retrieve the ACL type from an ACL entry
+.Nd retrieve the ACL type from an NFS4 ACL entry
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -42,7 +42,7 @@
 The
 .Fn acl_get_extended_np
 function
-is a non-portable call that returns the ACL type for the ACL entry
+is a non-portable call that returns the ACL type for the NFS4 ACL entry
 .Fa entry_d .
 Upon successful completion, the location referred to by the argument
 .Fa extended_p
@@ -58,7 +58,7 @@
 .It Bq Er EINVAL
 Argument
 .Fa entry_d
-is not a valid descriptor for an ACL entry;
+is not a valid descriptor for an NFS4 ACL entry;
 .El
 .Sh SEE ALSO
 .Xr acl 3 ,

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_flagset_np.3#2 (text+ko) ====

@@ -30,7 +30,7 @@
 .Os
 .Sh NAME
 .Nm acl_get_flagset_np
-.Nd retrieve flagset from an ACL entry
+.Nd retrieve flagset from an NFS4 ACL entry
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_extended_np.3#2 (text+ko) ====

@@ -30,7 +30,7 @@
 .Os
 .Sh NAME
 .Nm acl_set_extended_np
-.Nd set ACL type
+.Nd set NFS4 ACL entry type
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -46,6 +46,15 @@
 .Fa entry_d
 to the value referred to by
 .Fa extended .
+.Pp
+Valid values are:
+.Pp
+.Bd -literal -offset indent -compact
+ACL_EXTENDED_ALLOW	"allow" type entry
+ACL_EXTENDED_DENY	"deny" type entry
+.Ed
+.Pp
+This call brands the ACL as NFS4.
 .Sh RETURN VALUES
 .Rv -std acl_set_extended_np
 .Sh ERRORS
@@ -57,22 +66,17 @@
 Argument
 .Fa entry_d
 is not a valid descriptor for an ACL entry.
-The tag type of the
-ACL entry
-.Fa entry_d
-is not
-.Dv ACL_USER
-or
-.Dv ACL_GROUP .
 The value pointed to by
 .Fa extended
 is not valid.
+ACL is already branded as POSIX.
 .It Bq Er ENOMEM
 The value to be returned requires more memory than is allowed
 by the hardware or system-imposed memory management constraints.
 .El
 .Sh SEE ALSO
 .Xr acl 3 ,
+.Xr acl_get_brand_np 3 ,
 .Xr acl_get_extended_np 3 ,
 .Xr posix1e 3
 .Sh STANDARDS

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_flagset_np.3#2 (text+ko) ====

@@ -30,7 +30,7 @@
 .Os
 .Sh NAME
 .Nm acl_set_flagset_np
-.Nd set the flags of an ACL entry
+.Nd set the flags of an NFS4 ACL entry
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -46,6 +46,8 @@
 .Fa entry_d
 with the flags contained in
 .Fa flagset_d .
+.Pp
+This call brands the ACL as NFS4.
 .Sh RETURN VALUES
 .Rv -std acl_set_flagset_np
 .Sh ERRORS
@@ -57,10 +59,12 @@
 Argument
 .Fa entry_d
 is not a valid descriptor for an ACL entry.
+ACL is already branded as POSIX.
 .El
 .Sh SEE ALSO
 .Xr acl 3 ,
 .Xr acl_add_flag_np 3 ,
+.Xr acl_get_brand_np 3 ,
 .Xr acl_clear_flags_np 3 ,
 .Xr acl_delete_flag_np 3 ,
 .Xr acl_get_flagset_np 3 ,

==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_tag_type.3#2 (text+ko) ====

@@ -46,6 +46,26 @@
 .Fa entry_d
 to the value of
 .Fa tag_type .
+.Pp
+Valid values are:
+.Pp
+.Bd -literal -offset indent -compact
+ACL_USER_OBJ		Permissions apply to file owner.
+ACL_USER		Permissions apply to user specified by qualifier.
+ACL_GROUP_OBJ		Permissions apply to file owning group.
+ACL_GROUP		Permissions apply to group specified by qualifier.
+ACL_MASK		Permissions specify mask.
+ACL_OTHER		Permissions apply to "other".
+ACL_OTHER_OBJ		Same as ACL_OTHER
+ACL_EVERYONE		Permissions apply to "everyone@".
+.Ed
+.Pp
+Calling
+.Fn acl_set_tag_type
+with
+.Fa tag_type
+equal to ACL_MASK, ACL_OTHER or ACL_OTHER_OBJ brands the ACL as POSIX.
+Calling it with ACL_EVERYONE brands the ACL as NFS4.
 .Sh RETURN VALUES
 .Rv -std acl_set_tag_type
 .Sh ERRORS
@@ -60,9 +80,11 @@
 Argument
 .Fa tag_type
 is not a valid ACL tag type.
+ACL is already branded differently.
 .El
 .Sh SEE ALSO
 .Xr acl 3 ,
+.Xr acl_get_brand_np 3 ,
 .Xr acl_get_tag_type 3 ,
 .Xr posix1e 3
 .Sh STANDARDS
