PERFORCE change 149014 for review

[Edward Tomasz Napierala]

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

Change 149014 by trasz at trasz_traszkan on 2008/09/01 20:18:09

	Update comments.

Affected files ...

.. //depot/projects/soc2008/trasz_nfs4acl/sys/sys/acl.h#25 edit

Differences ...

==== //depot/projects/soc2008/trasz_nfs4acl/sys/sys/acl.h#25 (text+ko) ====

@@ -50,6 +50,7 @@
 #define	NFS4_ACL_EXTATTR_NAMESPACE		EXTATTR_NAMESPACE_SYSTEM
 #define	NFS4_ACL_EXTATTR_NAME			"nfs4.acl"
 #define	OLDACL_MAX_ENTRIES			32
+
 /*
  * With 204 entries, "struct acl" is exactly one page big.
  * Note that with NFS4 ACLs, the maximum number of ACL entries one
@@ -78,7 +79,6 @@
 };
 typedef struct oldacl_entry	*oldacl_entry_t;
 
-/* internal ACL structure */
 struct oldacl {
 	int			acl_cnt;
 	struct oldacl_entry	acl_entry[OLDACL_MAX_ENTRIES];
@@ -106,16 +106,30 @@
 };
 typedef struct acl_entry	*acl_entry_t;
 
-/* internal ACL structure */
+/*
+ * Internal ACL structure, used in libc, kernel APIs and for on-disk
+ * storage of NFS4 ACLs.  POSIX.1e ACLs use "struct oldacl" for on-disk
+ * storage.
+ */
 struct acl {
 	int			acl_magic;
 	int			acl_cnt;
 	int			acl_length;
+	/*
+	 * acl_brand is for libc internal bookkeeping only.
+	 * Applications should use acl_get_brand_np(3).
+	 * Kernel code should use the "type" argument passed
+	 * to VOP_SETACL, VOP_GETACL or VOP_ACLCHECK calls;
+	 * ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT mean POSIX.1e
+	 * ACL, ACL_TYPE_NFS4 means NFS4 ACL.
+	 */
 	int			acl_brand;
 	struct acl_entry	acl_entry[ACL_MAX_ENTRIES];
 };
 
-/* external ACL structure */
+/*
+ * External ACL structure, used in API for userland applications (acl(3)).
+ */
 struct acl_t_struct {
 	struct acl		ats_acl;
 	int			ats_cur_entry;
@@ -132,7 +146,7 @@
 #define ACL_BRAND_NFS4		2
 
 /*
- * Possible valid values for ae_tag field.
+ * Possible valid values for ae_tag field.  For explanation, see acl(9).
  */
 #define	ACL_UNDEFINED_TAG	0x00000000
 #define	ACL_USER_OBJ		0x00000001
@@ -153,7 +167,8 @@
 #define ACL_EXTENDED_ALARM	0x00000800
 
 /*
- * Possible valid values for acl_type_t arguments.
+ * Possible valid values for acl_type_t arguments.  First two
+ * are provided only for backwards binary compatibility.
  */
 #define	ACL_TYPE_ACCESS_OLD	0x00000000
 #define	ACL_TYPE_DEFAULT_OLD	0x00000001
@@ -223,8 +238,8 @@
  */
 #define ACL_ENTRY_FILE_INHERIT		0x00000001
 #define ACL_ENTRY_DIRECTORY_INHERIT	0x00000002
-#define ACL_ENTRY_LIMIT_INHERIT		0x00000004 /* NO_PROPAGATE_INHERIT */
-#define ACL_ENTRY_ONLY_INHERIT		0x00000008 /* INHERIT_ONLY */
+#define ACL_ENTRY_LIMIT_INHERIT		0x00000004 /* "NO_PROPAGATE_INHERIT" */
+#define ACL_ENTRY_ONLY_INHERIT		0x00000008 /* "INHERIT_ONLY" */
 #define ACL_ENTRY_SUCCESSFUL_ACCESS	0x00000010
 #define ACL_ENTRY_FAILED_ACCESS		0x00000020
 #define ACL_ENTRY_INHERITED		0x00000080 /* Currently unused. */
@@ -234,7 +249,8 @@
     ACL_ENTRY_FAILED_ACCESS)
 
 /*
- * Undefined value in ae_id field
+ * Undefined value in ae_id field.  ae_id should be set to this value
+ * iff ae_tag is ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER or ACL_EVERYONE.
  */
 #define	ACL_UNDEFINED_ID	((uid_t)-1)
 
@@ -256,7 +272,7 @@
 
 #ifdef _KERNEL
 /*
- * File system independent code to move back and forth between POSIX mode and
+ * Filesystem-independent code to move back and forth between POSIX mode and
  * POSIX.1e ACL representations.
  */
 acl_perm_t		acl_posix1e_mode_to_perm(acl_tag_t tag, mode_t mode);
@@ -286,7 +302,7 @@
 			    struct oldacl *dest);
 
 /*
- * File system independent syntax check for a POSIX.1e ACL.
+ * Filesystem-independent syntax check for a POSIX.1e ACL.
  */
 int			acl_posix1e_check(struct acl *acl);
 int 			acl_nfs4_check(const struct acl *aclp, int is_directory);
@@ -298,7 +314,7 @@
 
 /*
  * Syscall interface -- use the library calls instead as the syscalls have
- * strict acl entry ordering requirements.
+ * strict ACL entry ordering requirements.
  */
 __BEGIN_DECLS
 int	__acl_aclcheck_fd(int _filedes, acl_type_t _type, struct acl *_aclp);