1.\" Copyright (c) 2010 Joerg Sonnenberger 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd February 2, 2012 26.Dt ARCHIVE_ENTRY_ACL 3 27.Os 28.Sh NAME 29.Nm archive_entry_acl_add_entry , 30.Nm archive_entry_acl_add_entry_w , 31.Nm archive_entry_acl_clear , 32.Nm archive_entry_acl_count , 33.Nm archive_entry_acl_next , 34.Nm archive_entry_acl_next_w , 35.Nm archive_entry_acl_reset , 36.Nm archive_entry_acl_text_w 37.Nd functions for manipulating Access Control Lists in archive entry descriptions 38.Sh LIBRARY 39Streaming Archive Library (libarchive, -larchive) 40.Sh SYNOPSIS 41.In archive_entry.h 42.Ft void 43.Fo archive_entry_acl_add_entry 44.Fa "struct archive_entry *a" 45.Fa "int type" 46.Fa "int permset" 47.Fa "int tag" 48.Fa "int qualifier" 49.Fa "const char *name" 50.Fc 51.Ft void 52.Fo archive_entry_acl_add_entry_w 53.Fa "struct archive_entry *a" 54.Fa "int type" 55.Fa "int permset" 56.Fa "int tag" 57.Fa "int qualifier" 58.Fa "const wchar_t *name" 59.Fc 60.Ft void 61.Fn archive_entry_acl_clear "struct archive_entry *a" 62.Ft int 63.Fn archive_entry_acl_count "struct archive_entry *a" "int type" 64.Ft int 65.Fo archive_entry_acl_next 66.Fa "struct archive_entry *a" 67.Fa "int type" 68.Fa "int *ret_type" 69.Fa "int *ret_permset" 70.Fa "int *ret_tag" 71.Fa "int *ret_qual" 72.Fa "const char **ret_name" 73.Fc 74.Ft int 75.Fo archive_entry_acl_next_w 76.Fa "struct archive_entry *a" 77.Fa "int type" 78.Fa "int *ret_type" 79.Fa "int *ret_permset" 80.Fa "int *ret_tag" 81.Fa "int *ret_qual" 82.Fa "const wchar_t **ret_name" 83.Fc 84.Ft int 85.Fn archive_entry_acl_reset "struct archive_entry *a" "int type" 86.Ft const wchar_t * 87.Fn archive_entry_acl_text_w "struct archive_entry *a" "int flags" 88.\" enum? 89.Sh DESCRIPTION 90An 91.Dq Access Control List 92is a generalisation of the classic Unix permission system. 93The ACL interface of 94.Nm libarchive 95is derived from the POSIX.1e draft, but restricted to simplify dealing 96with practical implementations in various Operating Systems and archive formats. 97.Pp 98An ACL consists of a number of independent entries. 99Each entry specifies the permission set as bitmask of basic permissions. 100Valid permissions are: 101.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_EXECUTE" 102.It Dv ARCHIVE_ENTRY_ACL_EXECUTE 103.It Dv ARCHIVE_ENTRY_ACL_WRITE 104.It Dv ARCHIVE_ENTRY_ACL_READ 105.El 106The permissions correspond to the normal Unix permissions. 107.Pp 108The tag specifies the principal to which the permission applies. 109Valid values are: 110.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" 111.It Dv ARCHIVE_ENTRY_ACL_USER 112The user specified by the name field. 113.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ 114The owner of the file. 115.It Dv ARCHIVE_ENTRY_ACL_GROUP 116The group specied by the name field. 117.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 118The group who owns the file. 119.It Dv ARCHIVE_ENTRY_ACL_MASK 120The maximum permissions to be obtained via group permissions. 121.It Dv ARCHIVE_ENTRY_ACL_OTHER 122Any principal who doesn't have a user or group entry. 123.El 124The principals 125.Dv ARCHIVE_ENTRY_ACL_USER_OBJ , 126.Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 127and 128.Dv ARCHIVE_ENTRY_ACL_OTHER 129are equivalent to user, group and other in the classic Unix permission 130model and specify non-extended ACL entries. 131.Pp 132All files have an access ACL 133.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS . 134This specifies the permissions required for access to the file itself. 135Directories have an additional ACL 136.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT , 137which controls the initial access ACL for newly created directory entries. 138.Pp 139.Fn archive_entry_acl_add_entry 140and 141.Fn archive_entry_acl_add_entry_w 142add a single ACL entry. 143For the access ACL and non-extended principals, the classic Unix permissions 144are updated. 145.Pp 146.Fn archive_entry_acl_clear 147removes all ACL entries and resets the enumeration pointer. 148.Pp 149.Fn archive_entry_acl_count 150counts the ACL entries that have the given type mask. 151.Fa type 152can be the bitwise-or of 153.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 154and 155.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT . 156If 157.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 158is included and at least one extended ACL entry is found, 159the three non-extened ACLs are added. 160.Pp 161.Fn archive_entry_acl_next 162and 163.Fn archive_entry_acl_next_w 164return the next entry of the ACL list. 165This functions may only be called after 166.Fn archive_entry_acl_reset 167has indicated the presence of extended ACL entries. 168.Pp 169.Fn archive_entry_acl_reset 170prepare reading the list of ACL entries with 171.Fn archive_entry_acl_next 172or 173.Fn archive_entry_acl_next_w . 174The function returns either 0, if no non-extended ACLs are found. 175In this case, the access permissions should be obtained by 176.Xr archive_entry_mode 3 177or set using 178.Xr chmod 2 . 179Otherwise, the function returns the same value as 180.Fn archive_entry_acl_count . 181.Pp 182.Fn archive_entry_acl_text_w 183converts the ACL entries for the given type mask into a wide string. 184In addition to the normal type flags, 185.Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 186and 187.Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 188can be specified to further customize the result. 189The returned long string is valid until the next call to 190.Fn archive_entry_acl_clear , 191.Fn archive_entry_acl_add_entry , 192.Fn archive_entry_acl_add_entry_w 193or 194.Fn archive_entry_acl_text_w . 195.Sh RETURN VALUES 196.Fn archive_entry_acl_count 197and 198.Fn archive_entry_acl_reset 199returns the number of ACL entries that match the given type mask. 200If the type mask includes 201.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 202and at least one extended ACL entry exists, the three classic Unix 203permissions are counted. 204.Pp 205.Fn archive_entry_acl_next 206and 207.Fn archive_entry_acl_next_w 208return 209.Dv ARCHIVE_OK 210on success, 211.Dv ARCHIVE_EOF 212if no more ACL entries exist 213and 214.Dv ARCHIVE_WARN 215if 216.Fn archive_entry_acl_reset 217has not been called first. 218.Pp 219.Fn archive_entry_text_w 220returns a wide string representation of the ACL entrise matching the 221given type mask. 222The returned long string is valid until the next call to 223.Fn archive_entry_acl_clear , 224.Fn archive_entry_acl_add_entry , 225.Fn archive_entry_acl_add_entry_w 226or 227.Fn archive_entry_acl_text_w . 228.Sh SEE ALSO 229.Xr archive_entry 3 230.Xr libarchive 3 , 231.Sh BUGS 232.Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 233and 234.Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 235are not documented. 236