PERFORCE change 147103 for review
Edward Tomasz Napierala
trasz at FreeBSD.org
Sun Aug 10 20:15:06 UTC 2008
http://perforce.freebsd.org/chv.cgi?CH=147103
Change 147103 by trasz at trasz_traszkan on 2008/08/10 20:14:19
Manual pages.
Affected files ...
.. //depot/projects/soc2008/trasz_nfs4acl/TODO#36 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/Makefile.inc#6 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_add_flag_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_clear_flags_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_create_entry.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_delete_entry.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_delete_flag_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_extended_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_flag_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_get_flagset_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_is_trivial_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_extended_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_flagset_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_qualifier.3#2 edit
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_strip_np.3#1 add
.. //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_to_text.3#2 edit
Differences ...
==== //depot/projects/soc2008/trasz_nfs4acl/TODO#36 (text+ko) ====
@@ -6,13 +6,11 @@
to ACL_READ_NAMED_ATTRS, so there is no need for translation
between the two in kern/subr_acl_nfs4.c.
-- Either add or extend existing manual pages for new API routines:
- acl_add_flag_np, acl_clear_flags_np, acl_create_entry_np, acl_delete_entry_np,
- acl_delete_flag_np, acl_get_extended_np, acl_get_flag_np, acl_get_flagset_np,
- acl_set_extended_np, acl_set_flagset_np, acl_to_text_np, acl_is_trivial_np,
- acl_strip_np.
+- Enhance fstest with checks for NFS4 ACL functionality.
+
+- Update acl(9) manual page.
-- Enhance fstest with checks for NFS4 ACL functionality.
+- Put more content into the manual pages.
- Make 'struct acl' variable size.
==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/Makefile.inc#6 (text+ko) ====
@@ -31,28 +31,38 @@
SYM_MAPS+=${.CURDIR}/posix1e/Symbol.map
MAN+= acl.3 \
+ acl_add_flag_np.3 \
acl_add_perm.3 \
acl_calc_mask.3 \
+ acl_clear_flags_np.3 \
acl_clear_perms.3 \
acl_copy_entry.3 \
acl_create_entry.3 \
acl_delete.3 \
acl_delete_entry.3 \
+ acl_delete_flag_np.3 \
acl_delete_perm.3 \
acl_dup.3 \
acl_free.3 \
acl_from_text.3 \
acl_get.3 \
acl_get_entry.3 \
+ acl_get_extended_np.3 \
+ acl_get_flagset_np.3 \
+ acl_get_flag_np.3 \
acl_get_permset.3 \
acl_get_perm_np.3 \
acl_get_qualifier.3 \
acl_get_tag_type.3 \
acl_init.3 \
+ acl_is_trivial_np.3 \
acl_set.3 \
+ acl_set_extended_np.3 \
+ acl_set_flagset_np.3 \
acl_set_permset.3 \
acl_set_qualifier.3 \
acl_set_tag_type.3 \
+ acl_strip_np.3 \
acl_to_text.3 \
acl_valid.3 \
extattr.3 \
@@ -66,15 +76,18 @@
mac_text.3 \
posix1e.3
-MLINKS+=acl_delete.3 acl_delete_def_file.3 \
+MLINKS+=acl_create_entry.3 acl_create_entry_np.3\
+ acl_delete.3 acl_delete_def_file.3 \
acl_delete.3 acl_delete_file_np.3 \
acl_delete.3 acl_delete_fd_np.3 \
+ acl_delete_entry.3 acl_delete_entry_np.3\
acl_get.3 acl_get_file.3 \
acl_get.3 acl_get_fd.3 \
acl_get.3 acl_get_fd_np.3 \
acl_set.3 acl_set_file.3 \
acl_set.3 acl_set_fd.3 \
acl_set.3 acl_set_fd_np.3 \
+ acl_to_text.3 acl_to_text_np.3 \
acl_valid.3 acl_valid_file_np.3 \
acl_valid.3 acl_valid_fd_np.3 \
extattr.3 extattr_namespace_to_string.3 \
==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl.3#2 (text+ko) ====
@@ -48,7 +48,7 @@
and validate ACLs associated with file objects.
As well as the POSIX.1e routines, there are a number of non-portable
extensions defined that allow for alternative ACL semantics than the
-POSIX.1e semantics, such as AFS, NTFS, Coda, and NWFS semantics.
+POSIX.1e semantics, such as NFS4, AFS, NTFS, Coda, and NWFS semantics.
Where routines are non-standard, they are suffixed with _np to indicate that
they are not portable.
.Pp
@@ -59,6 +59,10 @@
.Pp
Available functions, sorted by behavior, include:
.Bl -tag -width indent
+.It Fn acl_add_flag_np
+This function is described in
+.Xr acl_add_flag_np 3 ,
+and may be used to add flags to a flagset.
.It Fn acl_add_perm
This function is described in
.Xr acl_add_perm 3 ,
@@ -70,6 +74,10 @@
the
.Dv ACL_MASK
entry.
+.It Fn acl_clear_flags_np
+This function is described in
+.Xr acl_clear_flags_np 3 ,
+and may be used to clear all flags from a flagset.
.It Fn acl_clear_perms
This function is described in
.Xr acl_clear_perms 3 ,
@@ -78,8 +86,11 @@
This function is described in
.Xr acl_copy_entry 3 ,
and may be used to copy the contents of an ACL entry.
-.It Fn acl_create_entry
-This function is described in
+.It Xo
+.Fn acl_create_entry ,
+.Fn acl_create_entry_np
+.Xc
+These functions are described in
.Xr acl_create_entry 3 ,
and may be used to create an empty entry in an ACL.
.It Xo
@@ -92,10 +103,17 @@
These functions are described in
.Xr acl_delete 3 ,
and may be used to delete ACLs from file system objects.
-.It Fn acl_delete_entry
-This function is described in
+.It Xo
+.Fn acl_delete_entry ,
+.Fn acl_delete_entry_np ,
+.Xc
+This functions are described in
.Xr acl_delete_entry 3 ,
and may be used to delete an entry from an ACL.
+.It Fn acl_delete_flag_np
+This function is described in
+.Xr acl_delete_flag_np 3 ,
+and may be used to delete flags from a flagset.
.It Fn acl_delete_perm
This function is described in
.Xr acl_delete_perm 3 ,
@@ -126,6 +144,14 @@
These functions are described in
.Xr acl_get 3 ,
and may be used to retrieve ACLs from file system objects.
+.It Fn acl_get_extended_np
+This function is described in
+.Xr acl_get_extended_np 3 ,
+and may be used to retrieve an ACL type from an ACL entry.
+.It Fn acl_get_flagset_np
+This function is described in
+.Xr acl_get_flagset_np 3 ,
+and may be used to retrieve a flagset from an ACL entry.
.It Fn acl_get_permset
This function is described in
.Xr acl_get_permset 3 ,
@@ -142,6 +168,10 @@
This function is described in
.Xr acl_init 3 ,
and may be used to allocate a fresh (empty) ACL structure.
+.It Fn acl_is_trivial_np
+This function is described in
+.Xr acl_is_trivial_np 3 ,
+and may be used to find out whether ACL is trivial.
.It Xo
.Fn acl_set_fd ,
.Fn acl_set_fd_np ,
@@ -151,6 +181,14 @@
These functions are described in
.Xr acl_set 3 ,
and may be used to assign an ACL to a file system object.
+.It Fn acl_set_extended_np
+This function is described in
+.Xr acl_set_extended_np 3 ,
+and may be used to set the ACL type of an ACL entry.
+.It Fn acl_set_flagset_np
+This function is described in
+.Xr acl_set_flagset_np 3 ,
+and may be used to set the flags of an ACL entry from a flagset.
.It Fn acl_set_permset
This function is described in
.Xr acl_set_permset 3 ,
@@ -163,8 +201,15 @@
This function is described in
.Xr acl_set_tag_type 3 ,
and may be used to set the tag type of an ACL.
-.It Fn acl_to_text
-This function is described in
+.It Fn acl_strip_np
+This function is describe din
+.Xr acl-strip_np 3 ,
+and may be used to remove extended entries from an ACL.
+.It Xo
+.Fn acl_to_text ,
+.Fn acl_to_text_np
+.Xc
+These functions are described in
.Xr acl_to_text 3 ,
and may be used to generate a text-form of a POSIX.1e semantics ACL.
.It Xo
@@ -189,25 +234,34 @@
.Sh SEE ALSO
.Xr getfacl 1 ,
.Xr setfacl 1 ,
+.Xr acl_add_flag_np 3 ,
.Xr acl_add_perm 3 ,
.Xr acl_calc_mask 3 ,
+.Xr acl_clear_flags_np 3 ,
.Xr acl_clear_perms 3 ,
.Xr acl_copy_entry 3 ,
.Xr acl_create_entry 3 ,
.Xr acl_delete_entry 3 ,
+.Xr acl_delete_flag_np 3 ,
.Xr acl_delete_perm 3 ,
.Xr acl_dup 3 ,
.Xr acl_free 3 ,
.Xr acl_from_text 3 ,
.Xr acl_get 3 ,
+.Xr acl_get_extended_np 3 ,
+.Xr acl_get_flagset_np 3 ,
.Xr acl_get_permset 3 ,
.Xr acl_get_qualifier 3 ,
.Xr acl_get_tag_type 3 ,
.Xr acl_init 3 ,
+.Xr acl_is_trivial_np 3 ,
.Xr acl_set 3 ,
+.Xr acl_set_extended_np 3 ,
+.Xr acl_set_flagset_np 3 ,
.Xr acl_set_permset 3 ,
.Xr acl_set_qualifier 3 ,
.Xr acl_set_tag_type 3 ,
+.Xr acl_strip_np 3 ,
.Xr acl_to_text 3 ,
.Xr acl_valid 3 ,
.Xr posix1e 3 ,
==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_create_entry.3#2 (text+ko) ====
@@ -30,6 +30,7 @@
.Os
.Sh NAME
.Nm acl_create_entry
+.Nm acl_create_entry_np
.Nd create a new ACL entry
.Sh LIBRARY
.Lb libc
@@ -38,6 +39,8 @@
.In sys/acl.h
.Ft int
.Fn acl_create_entry "acl_t *acl_p" "acl_entry_t *entry_p"
+.Ft int
+.Fn acl_create_entry_np "acl_t *acl_p" "acl_entry_t *entry_p" "int index"
.Sh DESCRIPTION
The
.Fn acl_create_entry
@@ -45,6 +48,16 @@
is a POSIX.1e call that creates a new ACL entry in the ACL
pointed to by
.Fa acl_p .
+The
+.Fn acl_create_entry_np
+function is a non-portable version that creates the ACL entry
+at position
+.Fa index .
+Positions are numbered starting from zero, i.e. calling
+.Fn acl_create_entry_np
+with
+.Fa index
+argument equal to zero will prepend the entry to the ACL.
.Sh RETURN VALUES
.Rv -std acl_create_entry
.Sh ERRORS
@@ -56,6 +69,9 @@
Argument
.Fa acl_p
does not point to a pointer to a valid ACL.
+Argument
+.Fa index
+is out of bounds.
.It Bq Er ENOMEM
The ACL working storage requires more memory than is
allowed by the hardware or system-imposed memory
==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_delete_entry.3#2 (text+ko) ====
@@ -29,7 +29,8 @@
.Dt ACL_DELETE_ENTRY 3
.Os
.Sh NAME
-.Nm acl_delete_entry
+.Nm acl_delete_entry ,
+.Nm acl_delete_entry_np ,
.Nd delete an ACL entry from an ACL
.Sh LIBRARY
.Lb libc
@@ -38,6 +39,8 @@
.In sys/acl.h
.Ft int
.Fn acl_delete_entry "acl_t acl" "acl_entry_t entry_d"
+.Ft int
+.Fn acl_delete_entry_np "acl_t acl" "int index"
.Sh DESCRIPTION
The
.Fn acl_delete_entry
@@ -46,6 +49,18 @@
.Fa entry_d
from ACL
.Fa acl .
+The
+.Fn acl_delete_entry_np
+function is a non-portable version that removes the ACL entry
+at position
+.Fa index
+from ACL
+.Fa acl .
+Positions are numbered starting from zero, i.e. calling
+.Fn acl_delete_entry_np
+with
+.Fa index
+argument equal to zero will remove the first ACL entry.
.Sh RETURN VALUES
.Rv -std acl_delete_entry
.Sh ERRORS
@@ -61,6 +76,9 @@
.Fa entry_d
is not a valid descriptor for an ACL entry in
.Fa acl .
+Argument
+.Fa index
+is out of bounds.
.El
.Sh SEE ALSO
.Xr acl 3 ,
==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_set_qualifier.3#2 (text+ko) ====
@@ -42,7 +42,7 @@
The
.Fn acl_set_qualifier
function
-is a POSIX.1e call that sets the qualifier of the tag for the ACl entry
+is a POSIX.1e call that sets the qualifier of the tag for the ACL entry
.Fa entry_d
to the value referred to by
.Fa tag_qualifier_p .
==== //depot/projects/soc2008/trasz_nfs4acl/lib/libc/posix1e/acl_to_text.3#2 (text+ko) ====
@@ -31,7 +31,8 @@
.Dt ACL_TO_TEXT 3
.Os
.Sh NAME
-.Nm acl_to_text
+.Nm acl_to_text ,
+.Nm acl_to_text_np
.Nd convert an ACL to text
.Sh LIBRARY
.Lb libc
@@ -40,10 +41,14 @@
.In sys/acl.h
.Ft char *
.Fn acl_to_text "acl_t acl" "ssize_t *len_p"
+.Ft char *
+.Fn acl_to_text_np "acl_t acl" "ssize_t *len_p" "int flags"
.Sh DESCRIPTION
The
.Fn acl_to_text
-function translates the ACL pointed to by argument
+and
+.Fn acl_to_text_np
+functions translate the ACL pointed to by argument
.Va acl
into a NULL terminated character string.
If the pointer
@@ -51,9 +56,22 @@
is not NULL, then the function shall return the length of the string (not
including the NULL terminator) in the location pointed to by
.Va len_p .
-The format of the text string returned by
+If the ACL is POSIX, the format of the text string returned by
.Fn acl_to_text
-shall be the POSIX.1e long ACL form.
+shall be the POSIX.1e long ACL form. If the ACL is NFS4, the format
+of the text string shall be the compact form, unless the
+.Va ACL_TEXT_VERBOSE
+flag is given.
+.Pp
+The flags specified are formed by
+.Em or Ns 'ing
+the following values
+.Pp
+.Bd -literal -offset indent -compact
+ACL_TEXT_VERBOSE format ACL using verbose form
+ACL_TEXT_NUMERIC_IDS do not resolve IDs into user or group names
+ACL_TEXT_APPEND_ID in addition to user and group names, append numeric IDs
+.Ed
.Pp
This function allocates any memory necessary to contain the string and
returns a pointer to the string.
More information about the p4-projects
mailing list