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 21, 2010 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 SYNOPSIS 39.In archive_entry.h 40.Ft void 41.Fo archive_entry_acl_add_entry 42.Fa "struct archive_entry *a" 43.Fa "int type" 44.Fa "int permset" 45.Fa "int tag" 46.Fa "int qualifier" 47.Fa "const char *name" 48.Fc 49.Ft void 50.Fo archive_entry_acl_add_entry_w 51.Fa "struct archive_entry *a" 52.Fa "int type" 53.Fa "int permset" 54.Fa "int tag" 55.Fa "int qualifier" 56.Fa "const wchar_t *name" 57.Fc 58.Ft void 59.Fn archive_entry_acl_clear "struct archive_entry *a" 60.Ft int 61.Fn archive_entry_acl_count "struct archive_entry *a" "int type" 62.Ft int 63.Fo archive_entry_acl_next 64.Fa "struct archive_entry *a" 65.Fa "int type" 66.Fa "int *ret_type" 67.Fa "int *ret_permset" 68.Fa "int *ret_tag" 69.Fa "int *ret_qual" 70.Fa "const char **ret_name" 71.Fc 72.Ft int 73.Fo archive_entry_acl_next_w 74.Fa "struct archive_entry *a" 75.Fa "int type" 76.Fa "int *ret_type" 77.Fa "int *ret_permset" 78.Fa "int *ret_tag" 79.Fa "int *ret_qual" 80.Fa "const wchar_t **ret_name" 81.Fc 82.Ft int 83.Fn archive_entry_acl_reset "struct archive_entry *a" "int type" 84.Ft const wchar_t * 85.Fn archive_entry_acl_text_w "struct archive_entry *a" "int flags" 86.\" enum? 87.Sh DESCRIPTION 88An 89.Dq Access Control List 90is a generalisation of the classic Unix permission system. 91The ACL interface of 92.Nm libarchive 93is derived from the POSIX.1e draft, but restricted to simplify dealing 94with practical implementations in various Operating Systems and archive formats. 95.Pp 96An ACL consists of a number of independent entries. 97Each entry specifies the permission set as bitmask of basic permissions. 98Valid permissions are: 99.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_EXECUTE" 100.It Dv ARCHIVE_ENTRY_ACL_EXECUTE 101.It Dv ARCHIVE_ENTRY_ACL_WRITE 102.It Dv ARCHIVE_ENTRY_ACL_READ 103.El 104The permissions correspond to the normal Unix permissions. 105.Pp 106The tag specifies the principal to which the permission applies. 107Valid values are: 108.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" 109.It Dv ARCHIVE_ENTRY_ACL_USER 110The user specified by the name field. 111.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ 112The owner of the file. 113.It Dv ARCHIVE_ENTRY_ACL_GROUP 114The group specied by the name field. 115.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 116The group who owns the file. 117.It Dv ARCHIVE_ENTRY_ACL_MASK 118The maximum permissions to be obtained via group permissions. 119.It Dv ARCHIVE_ENTRY_ACL_OTHER 120Any principal who doesn't have a user or group entry. 121.El 122The principals 123.Dv ARCHIVE_ENTRY_ACL_USER_OBJ , 124.Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 125and 126.Dv ARCHIVE_ENTRY_ACL_OTHER 127are equivalent to user, group and other in the classic Unix permission 128model and specify non-extended ACL entries. 129.Pp 130All files have an access ACL 131.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS . 132This specifies the permissions required for access to the file itself. 133Directories have an additional ACL 134.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT , 135which controls the initial access ACL for newly created directory entries. 136.Pp 137.Fn archive_entry_acl_add_entry 138and 139.Fn archive_entry_acl_add_entry_w 140add a single ACL entry. 141For the access ACL and non-extended principals, the classic Unix permissions 142are updated. 143.Pp 144.Fn archive_entry_acl_clear 145removes all ACL entries and resets the enumeration pointer. 146.Pp 147.Fn archive_entry_acl_count 148counts the ACL entries that have the given type mask. 149.Fa type 150can be the bitwise-or of 151.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 152and 153.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT . 154If 155.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 156is included and at least one extended ACL entry is found, 157the three non-extened ACLs are added. 158.Pp 159.Fn archive_entry_acl_next 160and 161.Fn archive_entry_acl_next_w 162return the next entry of the ACL list. 163This functions may only be called after 164.Fn archive_entry_acl_reset 165has indicated the presence of extended ACL entries. 166.Pp 167.Fn archive_entry_acl_reset 168prepare reading the list of ACL entries with 169.Fn archive_entry_acl_next 170or 171.Fn archive_entry_acl_next_w . 172The function returns either 0, if no non-extended ACLs are found. 173In this case, the access permissions should be obtained by 174.Xr archive_entry_mode 3 175or set using 176.Xr chmod 2 . 177Otherwise, the function returns the same value as 178.Fn archive_entry_acl_count . 179.Pp 180.Fn archive_entry_acl_text_w 181converts the ACL entries for the given type mask into a wide string. 182In addition to the normal type flags, 183.Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 184and 185.Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 186can be specified to further customize the result. 187The returned long string is valid until the next call to 188.Fn archive_entry_acl_clear , 189.Fn archive_entry_acl_add_entry , 190.Fn archive_entry_acl_add_entry_w 191or 192.Fn archive_entry_acl_text_w . 193.Sh RETURN VALUES 194.Fn archive_entry_acl_count 195and 196.Fn archive_entry_acl_reset 197returns the number of ACL entries that match the given type mask. 198If the type mask includes 199.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 200and at least one extended ACL entry exists, the three classic Unix 201permissions are counted. 202.Pp 203.Fn archive_entry_acl_next 204and 205.Fn archive_entry_acl_next_w 206return 207.Dv ARCHIVE_OK 208on success, 209.Dv ARCHIVE_EOF 210if no more ACL entries exist 211and 212.Dv ARCHIVE_WARN 213if 214.Fn archive_entry_acl_reset 215has not been called first. 216.Pp 217.Fn archive_entry_text_w 218returns a wide string representation of the ACL entrise matching the 219given type mask. 220The returned long string is valid until the next call to 221.Fn archive_entry_acl_clear , 222.Fn archive_entry_acl_add_entry , 223.Fn archive_entry_acl_add_entry_w 224or 225.Fn archive_entry_acl_text_w . 226.Sh SEE ALSO 227.Xr archive 3 , 228.Xr archive_entry 3 229.Sh BUGS 230.Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 231and 232.Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 233are not documented. 234