| .\" 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 2, 2012 |
| .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 LIBRARY |
| Streaming Archive Library (libarchive, -larchive) |
| .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 controls 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. |