diff options
Diffstat (limited to 'Utilities/cmlibarchive/libarchive/archive_entry_acl.3')
| -rw-r--r-- | Utilities/cmlibarchive/libarchive/archive_entry_acl.3 | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/Utilities/cmlibarchive/libarchive/archive_entry_acl.3 b/Utilities/cmlibarchive/libarchive/archive_entry_acl.3 new file mode 100644 index 000000000..93906e798 --- /dev/null +++ b/Utilities/cmlibarchive/libarchive/archive_entry_acl.3 @@ -0,0 +1,233 @@ +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 21, 2010 +.Dt ARCHIVE_ENTRY_ACL 3 +.Os +.Sh NAME +.Nm archive_entry_acl_add_entry , +.Nm archive_entry_acl_add_entry_w , +.Nm archive_entry_acl_clear , +.Nm archive_entry_acl_count , +.Nm archive_entry_acl_next , +.Nm archive_entry_acl_next_w , +.Nm archive_entry_acl_reset , +.Nm archive_entry_acl_text_w +.Nd functions for manipulating Access Control Lists in archive entry descriptions +.Sh SYNOPSIS +.In archive_entry.h +.Ft void +.Fo archive_entry_acl_add_entry +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int permset" +.Fa "int tag" +.Fa "int qualifier" +.Fa "const char *name" +.Fc +.Ft void +.Fo archive_entry_acl_add_entry_w +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int permset" +.Fa "int tag" +.Fa "int qualifier" +.Fa "const wchar_t *name" +.Fc +.Ft void +.Fn archive_entry_acl_clear "struct archive_entry *a" +.Ft int +.Fn archive_entry_acl_count "struct archive_entry *a" "int type" +.Ft int +.Fo archive_entry_acl_next +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int *ret_type" +.Fa "int *ret_permset" +.Fa "int *ret_tag" +.Fa "int *ret_qual" +.Fa "const char **ret_name" +.Fc +.Ft int +.Fo archive_entry_acl_next_w +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int *ret_type" +.Fa "int *ret_permset" +.Fa "int *ret_tag" +.Fa "int *ret_qual" +.Fa "const wchar_t **ret_name" +.Fc +.Ft int +.Fn archive_entry_acl_reset "struct archive_entry *a" "int type" +.Ft const wchar_t * +.Fn archive_entry_acl_text_w "struct archive_entry *a" "int flags" +.\" enum? +.Sh DESCRIPTION +An +.Dq Access Control List +is a generalisation of the classic Unix permission system. +The ACL interface of +.Nm libarchive +is derived from the POSIX.1e draft, but restricted to simplify dealing +with practical implementations in various Operating Systems and archive formats. +.Pp +An ACL consists of a number of independent entries. +Each entry specifies the permission set as bitmask of basic permissions. +Valid permissions are: +.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_EXECUTE" +.It Dv ARCHIVE_ENTRY_ACL_EXECUTE +.It Dv ARCHIVE_ENTRY_ACL_WRITE +.It Dv ARCHIVE_ENTRY_ACL_READ +.El +The permissions correspond to the normal Unix permissions. +.Pp +The tag specifies the principal to which the permission applies. +Valid values are: +.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" +.It Dv ARCHIVE_ENTRY_ACL_USER +The user specified by the name field. +.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ +The owner of the file. +.It Dv ARCHIVE_ENTRY_ACL_GROUP +The group specied by the name field. +.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ +The group who owns the file. +.It Dv ARCHIVE_ENTRY_ACL_MASK +The maximum permissions to be obtained via group permissions. +.It Dv ARCHIVE_ENTRY_ACL_OTHER +Any principal who doesn't have a user or group entry. +.El +The principals +.Dv ARCHIVE_ENTRY_ACL_USER_OBJ , +.Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ +and +.Dv ARCHIVE_ENTRY_ACL_OTHER +are equivalent to user, group and other in the classic Unix permission +model and specify non-extended ACL entries. +.Pp +All files have an access ACL +.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS . +This specifies the permissions required for access to the file itself. +Directories have an additional ACL +.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT , +which controlls the initial access ACL for newly created directory entries. +.Pp +.Fn archive_entry_acl_add_entry +and +.Fn archive_entry_acl_add_entry_w +add a single ACL entry. +For the access ACL and non-extended principals, the classic Unix permissions +are updated. +.Pp +.Fn archive_entry_acl_clear +removes all ACL entries and resets the enumeration pointer. +.Pp +.Fn archive_entry_acl_count +counts the ACL entries that have the given type mask. +.Fa type +can be the bitwise-or of +.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +and +.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT . +If +.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +is included and at least one extended ACL entry is found, +the three non-extened ACLs are added. +.Pp +.Fn archive_entry_acl_next +and +.Fn archive_entry_acl_next_w +return the next entry of the ACL list. +This functions may only be called after +.Fn archive_entry_acl_reset +has indicated the presence of extended ACL entries. +.Pp +.Fn archive_entry_acl_reset +prepare reading the list of ACL entries with +.Fn archive_entry_acl_next +or +.Fn archive_entry_acl_next_w . +The function returns either 0, if no non-extended ACLs are found. +In this case, the access permissions should be obtained by +.Xr archive_entry_mode 3 +or set using +.Xr chmod 2 . +Otherwise, the function returns the same value as +.Fn archive_entry_acl_count . +.Pp +.Fn archive_entry_acl_text_w +converts the ACL entries for the given type mask into a wide string. +In addition to the normal type flags, +.Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID +and +.Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT +can be specified to further customize the result. +The returned long string is valid until the next call to +.Fn archive_entry_acl_clear , +.Fn archive_entry_acl_add_entry , +.Fn archive_entry_acl_add_entry_w +or +.Fn archive_entry_acl_text_w . +.Sh RETURN VALUES +.Fn archive_entry_acl_count +and +.Fn archive_entry_acl_reset +returns the number of ACL entries that match the given type mask. +If the type mask includes +.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +and at least one extended ACL entry exists, the three classic Unix +permissions are counted. +.Pp +.Fn archive_entry_acl_next +and +.Fn archive_entry_acl_next_w +return +.Dv ARCHIVE_OK +on success, +.Dv ARCHIVE_EOF +if no more ACL entries exist +and +.Dv ARCHIVE_WARN +if +.Fn archive_entry_acl_reset +has not been called first. +.Pp +.Fn archive_entry_text_w +returns a wide string representation of the ACL entrise matching the +given type mask. +The returned long string is valid until the next call to +.Fn archive_entry_acl_clear , +.Fn archive_entry_acl_add_entry , +.Fn archive_entry_acl_add_entry_w +or +.Fn archive_entry_acl_text_w . +.Sh SEE ALSO +.Xr archive 3 , +.Xr archive_entry 3 +.Sh BUGS +.Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID +and +.Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT +are not documented. |