1ARCHIVE_ENTRY_ACL(3) BSD Library Functions Manual ARCHIVE_ENTRY_ACL(3) 2 3NAME 4 archive_entry_acl_add_entry, archive_entry_acl_add_entry_w, 5 archive_entry_acl_clear, archive_entry_acl_count, 6 archive_entry_acl_from_text, archive_entry_acl_from_text_w, 7 archive_entry_acl_next, archive_entry_acl_reset, 8 archive_entry_acl_to_text, archive_entry_acl_to_text_w, 9 archive_entry_acl_types — functions for manipulating Access Control Lists 10 in archive entry descriptions 11 12LIBRARY 13 Streaming Archive Library (libarchive, -larchive) 14 15SYNOPSIS 16 #include <archive_entry.h> 17 18 void 19 archive_entry_acl_add_entry(struct archive_entry *a, int type, 20 int permset, int tag, int qualifier, const char *name); 21 22 void 23 archive_entry_acl_add_entry_w(struct archive_entry *a, int type, 24 int permset, int tag, int qualifier, const wchar_t *name); 25 26 void 27 archive_entry_acl_clear(struct archive_entry *a); 28 29 int 30 archive_entry_acl_count(struct archive_entry *a, int type); 31 32 int 33 archive_entry_acl_from_text(struct archive_entry *a, const char *text, 34 int type); 35 36 int 37 archive_entry_acl_from_text_w(struct archive_entry *a, 38 const wchar_t *text, int type); 39 40 int 41 archive_entry_acl_next(struct archive_entry *a, int type, int *ret_type, 42 int *ret_permset, int *ret_tag, int *ret_qual, 43 const char **ret_name); 44 45 int 46 archive_entry_acl_reset(struct archive_entry *a, int type); 47 48 char * 49 archive_entry_acl_to_text(struct archive_entry *a, ssize_t *len_p, 50 int flags); 51 52 wchar_t * 53 archive_entry_acl_to_text_w(struct archive_entry *a, ssize_t *len_p, 54 int flags); 55 56 int 57 archive_entry_acl_types(struct archive_entry *a); 58 59DESCRIPTION 60 The “Access Control Lists (ACLs)” extend the standard Unix permission 61 model. The ACL interface of libarchive supports both POSIX.1e and NFSv4 62 style ACLs. Use of ACLs is restricted by various levels of ACL support 63 in operating systems, file systems and archive formats. 64 65 POSIX.1e Access Control Lists 66 A POSIX.1e ACL consists of a number of independent entries. Each entry 67 specifies the permission set as a bitmask of basic permissions. Valid 68 permissions in the permset are: 69 ARCHIVE_ENTRY_ACL_READ (r) 70 ARCHIVE_ENTRY_ACL_WRITE (w) 71 ARCHIVE_ENTRY_ACL_EXECUTE (x) 72 The permissions correspond to the normal Unix permissions. 73 74 The tag specifies the principal to which the permission applies. Valid 75 values are: 76 ARCHIVE_ENTRY_ACL_USER The user specified by the name field. 77 ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file. 78 ARCHIVE_ENTRY_ACL_GROUP The group specified by the name field. 79 ARCHIVE_ENTRY_ACL_GROUP_OBJ The group which owns the file. 80 ARCHIVE_ENTRY_ACL_MASK The maximum permissions to be obtained 81 via group permissions. 82 ARCHIVE_ENTRY_ACL_OTHER Any principal who is not the file 83 owner or a member of the owning group. 84 85 The principals ARCHIVE_ENTRY_ACL_USER_OBJ, ARCHIVE_ENTRY_ACL_GROUP_OBJ 86 and ARCHIVE_ENTRY_ACL_OTHER are equivalent to user, group and other in 87 the classic Unix permission model and specify non-extended ACL entries. 88 89 All files have an access ACL (ARCHIVE_ENTRY_ACL_TYPE_ACCESS). This spec‐ 90 ifies the permissions required for access to the file itself. Directo‐ 91 ries have an additional ACL (ARCHIVE_ENTRY_ACL_TYPE_DEFAULT), which con‐ 92 trols the initial access ACL for newly-created directory entries. 93 94 NFSv4 Access Control Lists 95 A NFSv4 ACL consists of multiple individual entries called Access Control 96 Entries (ACEs). 97 98 There are four possible types of a NFSv4 ACE: 99 ARCHIVE_ENTRY_ACL_TYPE_ALLOW Allow principal to perform actions re‐ 100 quiring given permissions. 101 ARCHIVE_ENTRY_ACL_TYPE_DENY Prevent principal from performing ac‐ 102 tions requiring given permissions. 103 ARCHIVE_ENTRY_ACL_TYPE_AUDIT Log access attempts by principal which 104 require given permissions. 105 ARCHIVE_ENTRY_ACL_TYPE_ALARM Trigger a system alarm on access at‐ 106 tempts by principal which require 107 given permissions. 108 109 The tag specifies the principal to which the permission applies. Valid 110 values are: 111 ARCHIVE_ENTRY_ACL_USER The user specified by the name field. 112 ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file. 113 ARCHIVE_ENTRY_ACL_GROUP The group specified by the name field. 114 ARCHIVE_ENTRY_ACL_GROUP_OBJ The group which owns the file. 115 ARCHIVE_ENTRY_ACL_EVERYONE Any principal who is not the file 116 owner or a member of the owning group. 117 118 Entries with the ARCHIVE_ENTRY_ACL_USER or ARCHIVE_ENTRY_ACL_GROUP tag 119 store the user and group name in the name string and optionally the user 120 or group ID in the qualifier integer. 121 122 NFSv4 ACE permissions and flags are stored in the same permset bitfield. 123 Some permissions share the same constant and permission character but 124 have different effect on directories than on files. The following ACE 125 permissions are supported: 126 ARCHIVE_ENTRY_ACL_READ_DATA (r) 127 Read data (file). 128 ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (r) 129 List entries (directory). 130 ARCHIVE_ENTRY_ACL_WRITE_DATA (w) 131 Write data (file). 132 ARCHIVE_ENTRY_ACL_ADD_FILE (w) 133 Create files (directory). 134 ARCHIVE_ENTRY_ACL_EXECUTE (x) 135 Execute file or change into a directory. 136 ARCHIVE_ENTRY_ACL_APPEND_DATA (p) 137 Append data (file). 138 ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (p) 139 Create subdirectories (directory). 140 ARCHIVE_ENTRY_ACL_DELETE_CHILD (D) 141 Remove files and subdirectories inside a directory. 142 ARCHIVE_ENTRY_ACL_DELETE (d) 143 Remove file or directory. 144 ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (a) 145 Read file or directory attributes. 146 ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (A) 147 Write file or directory attributes. 148 ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (R) 149 Read named file or directory attributes. 150 ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (W) 151 Write named file or directory attributes. 152 ARCHIVE_ENTRY_ACL_READ_ACL (c) 153 Read file or directory ACL. 154 ARCHIVE_ENTRY_ACL_WRITE_ACL (C) 155 Write file or directory ACL. 156 ARCHIVE_ENTRY_ACL_WRITE_OWNER (o) 157 Change owner of a file or directory. 158 ARCHIVE_ENTRY_ACL_SYNCHRONIZE (s) 159 Use synchronous I/O. 160 161 The following NFSv4 ACL inheritance flags are supported: 162 ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (f) 163 Inherit parent directory ACE to files. 164 ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (d) 165 Inherit parent directory ACE to subdirectories. 166 ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (i) 167 Only inherit, do not apply the permission on the directory 168 itself. 169 ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (n) 170 Do not propagate inherit flags. Only first-level entries 171 inherit ACLs. 172 ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (S) 173 Trigger alarm or audit on successful access. 174 ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (F) 175 Trigger alarm or audit on failed access. 176 ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (I) 177 Mark that ACE was inherited. 178 179 Functions 180 archive_entry_acl_add_entry() and archive_entry_acl_add_entry_w() add a 181 single ACL entry. For the access ACL and non-extended principals, the 182 classic Unix permissions are updated. An archive entry cannot contain 183 both POSIX.1e and NFSv4 ACL entries. 184 185 archive_entry_acl_clear() removes all ACL entries and resets the enumera‐ 186 tion pointer. 187 188 archive_entry_acl_count() counts the ACL entries that have the given type 189 mask. type can be the bitwise-or of 190 ARCHIVE_ENTRY_ACL_TYPE_ACCESS 191 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 192 for POSIX.1e ACLs and 193 ARCHIVE_ENTRY_ACL_TYPE_ALLOW 194 ARCHIVE_ENTRY_ACL_TYPE_DENY 195 ARCHIVE_ENTRY_ACL_TYPE_AUDIT 196 ARCHIVE_ENTRY_ACL_TYPE_ALARM 197 for NFSv4 ACLs. For POSIX.1e ACLs if ARCHIVE_ENTRY_ACL_TYPE_ACCESS is 198 included and at least one extended ACL entry is found, the three non-ex‐ 199 tended ACLs are added. 200 201 archive_entry_acl_from_text() and archive_entry_acl_from_text_w() add new 202 (or merge with existing) ACL entries from (wide) text. The argument type 203 may take one of the following values: 204 ARCHIVE_ENTRY_ACL_TYPE_ACCESS 205 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 206 ARCHIVE_ENTRY_ACL_TYPE_NFS4 207 Supports all formats that can be created with archive_entry_acl_to_text() 208 or respectively archive_entry_acl_to_text_w(). Existing ACL entries are 209 preserved. To get a clean new ACL from text archive_entry_acl_clear() 210 must be called first. Entries prefixed with “default:” are treated as 211 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT unless type is 212 ARCHIVE_ENTRY_ACL_TYPE_NFS4. Invalid entries, non-parseable ACL entries 213 and entries beginning with the ‘#’ character (comments) are skipped. 214 215 archive_entry_acl_next() return the next entry of the ACL list. This 216 functions may only be called after archive_entry_acl_reset() has indi‐ 217 cated the presence of extended ACL entries. 218 219 archive_entry_acl_reset() prepare reading the list of ACL entries with 220 archive_entry_acl_next(). The function returns 0 if no non-extended ACLs 221 are found. In this case, the access permissions should be obtained by 222 archive_entry_mode(3) or set using chmod(2). Otherwise, the function re‐ 223 turns the same value as archive_entry_acl_count(). 224 225 archive_entry_acl_to_text() and archive_entry_acl_to_text_w() convert the 226 ACL entries for the given type into a (wide) string of ACL entries sepa‐ 227 rated by newline. If the pointer len_p is not NULL, then the function 228 shall return the length of the string (not including the NULL terminator) 229 in the location pointed to by len_p. The flag argument is a bitwise-or. 230 231 The following flags are effective only on POSIX.1e ACL: 232 ARCHIVE_ENTRY_ACL_TYPE_ACCESS 233 Output access ACLs. 234 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 235 Output POSIX.1e default ACLs. 236 ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 237 Prefix each default ACL entry with the word “default:”. 238 ARCHIVE_ENTRY_ACL_STYLE_SOLARIS 239 The mask and other ACLs don not contain a double colon. 240 241 The following flags are effecive only on NFSv4 ACL: 242 ARCHIVE_ENTRY_ACL_STYLE_COMPACT 243 Do not output minus characters for unset permissions and 244 flags in NFSv4 ACL permission and flag fields. 245 246 The following flags are effective on both POSIX.1e and NFSv4 ACL: 247 ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 248 Add an additional colon-separated field containing the user 249 or group id. 250 ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA 251 Separate ACL entries with comma instead of newline. 252 253 If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are re‐ 254 turned. It the entry contains POSIX.1e ACLs and none of the flags 255 ARCHIVE_ENTRY_ACL_TYPE_ACCESS or ARCHIVE_ENTRY_ACL_TYPE_DEFAULT are spec‐ 256 ified, both access and default entries are returned and default entries 257 are prefixed with “default:”. 258 259 archive_entry_acl_types() get ACL entry types contained in an archive en‐ 260 try's ACL. As POSIX.1e and NFSv4 ACL entries cannot be mixed, this func‐ 261 tion is a very efficient way to detect if an ACL already contains 262 POSIX.1e or NFSv4 ACL entries. 263 264RETURN VALUES 265 archive_entry_acl_count() and archive_entry_acl_reset() returns the num‐ 266 ber of ACL entries that match the given type mask. For POSIX.1e ACLS if 267 the type mask includes ARCHIVE_ENTRY_ACL_TYPE_ACCESS and at least one ex‐ 268 tended ACL entry exists, the three classic Unix permissions are counted. 269 270 archive_entry_acl_from_text() and archive_entry_acl_from_text_w() return 271 ARCHIVE_OK if all entries were successfully parsed and ARCHIVE_WARN if 272 one or more entries were invalid or non-parseable. 273 274 archive_entry_acl_next() returns ARCHIVE_OK on success, ARCHIVE_EOF if no 275 more ACL entries exist and ARCHIVE_WARN if archive_entry_acl_reset() has 276 not been called first. 277 278 archive_entry_acl_to_text() returns a string representing the ACL entries 279 matching the given type and flags on success or NULL on error. 280 281 archive_entry_acl_to_text_w() returns a wide string representing the ACL 282 entries matching the given type and flags on success or NULL on error. 283 284 archive_entry_acl_types() returns a bitmask of ACL entry types or 0 if 285 archive entry has no ACL entries. 286 287SEE ALSO 288 archive_entry(3), libarchive(3) 289 290BSD February 15, 2017 BSD 291