1ARCHIVE_ENTRY_ACL(3) manual page 2== NAME == 3'''archive_entry_acl_add_entry''', 4'''archive_entry_acl_add_entry_w''', 5'''archive_entry_acl_clear''', 6'''archive_entry_acl_count''', 7'''archive_entry_acl_from_text''', 8'''archive_entry_acl_from_text_w''', 9'''archive_entry_acl_next''', 10'''archive_entry_acl_reset''', 11'''archive_entry_acl_to_text''', 12'''archive_entry_acl_to_text_w''', 13'''archive_entry_acl_types''' 14- functions for manipulating Access Control Lists in archive entry descriptions 15== LIBRARY == 16Streaming Archive Library (libarchive, -larchive) 17== SYNOPSIS == 18'''<nowiki>#include <archive_entry.h></nowiki>''' 19<br> 20''void'' 21<br> 22'''archive_entry_acl_add_entry'''(''struct archive_entry *a'', ''int type'', ''int permset'', ''int tag'', ''int qualifier'', ''const char *name''); 23<br> 24''void'' 25<br> 26'''archive_entry_acl_add_entry_w'''(''struct archive_entry *a'', ''int type'', ''int permset'', ''int tag'', ''int qualifier'', ''const wchar_t *name''); 27<br> 28''void'' 29<br> 30'''archive_entry_acl_clear'''(''struct archive_entry *a''); 31<br> 32''int'' 33<br> 34'''archive_entry_acl_count'''(''struct archive_entry *a'', ''int type''); 35<br> 36''int'' 37<br> 38'''archive_entry_acl_from_text'''(''struct archive_entry *a'', ''const char *text'', ''int type''); 39<br> 40''int'' 41<br> 42'''archive_entry_acl_from_text_w'''(''struct archive_entry *a'', ''const wchar_t *text'', ''int type''); 43<br> 44''int'' 45<br> 46'''archive_entry_acl_next'''(''struct archive_entry *a'', ''int type'', ''int *ret_type'', ''int *ret_permset'', ''int *ret_tag'', ''int *ret_qual'', ''const char **ret_name''); 47<br> 48''int'' 49<br> 50'''archive_entry_acl_reset'''(''struct archive_entry *a'', ''int type''); 51<br> 52''char *'' 53<br> 54'''archive_entry_acl_to_text'''(''struct archive_entry *a'', ''ssize_t *len_p'', ''int flags''); 55<br> 56''wchar_t *'' 57<br> 58'''archive_entry_acl_to_text_w'''(''struct archive_entry *a'', ''ssize_t *len_p'', ''int flags''); 59<br> 60''int'' 61<br> 62'''archive_entry_acl_types'''(''struct archive_entry *a''); 63== DESCRIPTION == 64The 65"Access Control Lists (ACLs)" 66extend the standard Unix permission model. 67The ACL interface of 68'''libarchive''' 69supports both POSIX.1e and NFSv4 style ACLs. 70Use of ACLs is restricted by 71various levels of ACL support in operating systems, file systems and archive 72formats. 73=== POSIX.1e Access Control Lists=== 74A POSIX.1e ACL consists of a number of independent entries. 75Each entry specifies the permission set as a bitmask of basic permissions. 76Valid permissions in the 77are: 78<dl> 79<dt></dt><dd> 80ARCHIVE_ENTRY_ACL_READ (.B r ) 81</dd><dt></dt><dd> 82ARCHIVE_ENTRY_ACL_WRITE (.B w ) 83</dd><dt></dt><dd> 84ARCHIVE_ENTRY_ACL_EXECUTE (.B x ) 85</dd></dl> 86The permissions correspond to the normal Unix permissions. 87 88The 89specifies the principal to which the permission applies. 90Valid values are: 91<dt></dt><dd> 92ARCHIVE_ENTRY_ACL_USER 93The user specified by the name field. 94</dd><dt></dt><dd> 95ARCHIVE_ENTRY_ACL_USER_OBJ 96The owner of the file. 97</dd><dt></dt><dd> 98ARCHIVE_ENTRY_ACL_GROUP 99The group specified by the name field. 100</dd><dt></dt><dd> 101ARCHIVE_ENTRY_ACL_GROUP_OBJ 102The group which owns the file. 103</dd><dt></dt><dd> 104ARCHIVE_ENTRY_ACL_MASK 105The maximum permissions to be obtained via group permissions. 106</dd><dt></dt><dd> 107ARCHIVE_ENTRY_ACL_OTHER 108Any principal who is not the file owner or a member of the owning group. 109</dd> 110 111The principals 112ARCHIVE_ENTRY_ACL_USER_OBJ, 113ARCHIVE_ENTRY_ACL_GROUP_OBJ 114and 115ARCHIVE_ENTRY_ACL_OTHER 116are equivalent to user, group and other in the classic Unix permission 117model and specify non-extended ACL entries. 118 119All files have an access ACL 120() 121ARCHIVE_ENTRY_ACL_TYPE_ACCESS. 122This specifies the permissions required for access to the file itself. 123Directories have an additional ACL 124() 125ARCHIVE_ENTRY_ACL_TYPE_DEFAULT, 126which controls the initial access ACL for newly-created directory entries. 127=== NFSv4 Access Control Lists=== 128A NFSv4 ACL consists of multiple individual entries called Access Control 129Entries (ACEs). 130 131There are four possible types of a NFSv4 ACE: 132<dt></dt><dd> 133ARCHIVE_ENTRY_ACL_TYPE_ALLOW 134Allow principal to perform actions requiring given permissions. 135</dd><dt></dt><dd> 136ARCHIVE_ENTRY_ACL_TYPE_DENY 137Prevent principal from performing actions requiring given permissions. 138</dd><dt></dt><dd> 139ARCHIVE_ENTRY_ACL_TYPE_AUDIT 140Log access attempts by principal which require given permissions. 141</dd><dt></dt><dd> 142ARCHIVE_ENTRY_ACL_TYPE_ALARM 143Trigger a system alarm on access attempts by principal which require given 144permissions. 145</dd> 146 147The 148specifies the principal to which the permission applies. 149Valid values are: 150<dt></dt><dd> 151ARCHIVE_ENTRY_ACL_USER 152The user specified by the name field. 153</dd><dt></dt><dd> 154ARCHIVE_ENTRY_ACL_USER_OBJ 155The owner of the file. 156</dd><dt></dt><dd> 157ARCHIVE_ENTRY_ACL_GROUP 158The group specified by the name field. 159</dd><dt></dt><dd> 160ARCHIVE_ENTRY_ACL_GROUP_OBJ 161The group which owns the file. 162</dd><dt></dt><dd> 163ARCHIVE_ENTRY_ACL_EVERYONE 164Any principal who is not the file owner or a member of the owning group. 165</dd> 166 167Entries with the 168ARCHIVE_ENTRY_ACL_USER 169or 170ARCHIVE_ENTRY_ACL_GROUP 171tag store the user and group name in the 172string and optionally the user or group ID in the 173integer. 174 175NFSv4 ACE permissions and flags are stored in the same 176bitfield. 177Some permissions share the same constant and permission character 178but have different effect on directories than on files. 179The following ACE permissions are supported: 180<dl> 181<dt></dt><dd> 182ARCHIVE_ENTRY_ACL_READ_DATA (.B r ) 183Read data (file). 184</dd><dt></dt><dd> 185ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (.B r ) 186List entries (directory). 187</dd><dt>ARCHIVE_ENTRY_ACL_WRITE_DATA (.B w )</dt><dd> 188Write data (file). 189</dd><dt>ARCHIVE_ENTRY_ACL_ADD_FILE (.B w )</dt><dd> 190Create files (directory). 191</dd><dt></dt><dd> 192ARCHIVE_ENTRY_ACL_EXECUTE (.B x ) 193Execute file or change into a directory. 194</dd><dt></dt><dd> 195ARCHIVE_ENTRY_ACL_APPEND_DATA (.B p ) 196Append data (file). 197</dd><dt></dt><dd> 198ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (.B p ) 199Create subdirectories (directory). 200</dd><dt></dt><dd> 201ARCHIVE_ENTRY_ACL_DELETE_CHILD (.B D ) 202Remove files and subdirectories inside a directory. 203</dd><dt></dt><dd> 204ARCHIVE_ENTRY_ACL_DELETE (.B d ) 205Remove file or directory. 206</dd><dt></dt><dd> 207ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (.B a ) 208Read file or directory attributes. 209</dd><dt></dt><dd> 210ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (.B A ) 211Write file or directory attributes. 212</dd><dt></dt><dd> 213ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (.B R ) 214Read named file or directory attributes. 215</dd><dt></dt><dd> 216ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (.B W ) 217Write named file or directory attributes. 218</dd><dt></dt><dd> 219ARCHIVE_ENTRY_ACL_READ_ACL (.B c ) 220Read file or directory ACL. 221</dd><dt></dt><dd> 222ARCHIVE_ENTRY_ACL_WRITE_ACL (.B C ) 223Write file or directory ACL. 224</dd><dt></dt><dd> 225ARCHIVE_ENTRY_ACL_WRITE_OWNER (.B o ) 226Change owner of a file or directory. 227</dd><dt></dt><dd> 228ARCHIVE_ENTRY_ACL_SYNCHRONIZE (.B s ) 229Use synchronous I/O. 230</dd></dl> 231 232The following NFSv4 ACL inheritance flags are supported: 233<dl> 234<dt></dt><dd> 235ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (.B f ) 236Inherit parent directory ACE to files. 237</dd><dt></dt><dd> 238ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (.B d ) 239Inherit parent directory ACE to subdirectories. 240</dd><dt></dt><dd> 241ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (.B i ) 242Only inherit, do not apply the permission on the directory itself. 243</dd><dt></dt><dd> 244ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (.B n ) 245Do not propagate inherit flags. 246Only first-level entries inherit ACLs. 247</dd><dt></dt><dd> 248ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (.B S ) 249Trigger alarm or audit on successful access. 250</dd><dt></dt><dd> 251ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (.B F ) 252Trigger alarm or audit on failed access. 253</dd><dt></dt><dd> 254ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (.B I ) 255Mark that ACE was inherited. 256</dd></dl> 257=== Functions=== 258'''archive_entry_acl_add_entry'''() 259and 260'''archive_entry_acl_add_entry_w'''() 261add a single ACL entry. 262For the access ACL and non-extended principals, the classic Unix permissions 263are updated. 264An archive entry cannot contain both POSIX.1e and NFSv4 ACL entries. 265 266'''archive_entry_acl_clear'''() 267removes all ACL entries and resets the enumeration pointer. 268 269'''archive_entry_acl_count'''() 270counts the ACL entries that have the given type mask. 271can be the bitwise-or of 272<dl> 273<dt></dt><dd> 274ARCHIVE_ENTRY_ACL_TYPE_ACCESS 275</dd><dt></dt><dd> 276ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 277</dd></dl> 278for POSIX.1e ACLs and 279<dl> 280<dt></dt><dd> 281ARCHIVE_ENTRY_ACL_TYPE_ALLOW 282</dd><dt></dt><dd> 283ARCHIVE_ENTRY_ACL_TYPE_DENY 284</dd><dt></dt><dd> 285ARCHIVE_ENTRY_ACL_TYPE_AUDIT 286</dd><dt></dt><dd> 287ARCHIVE_ENTRY_ACL_TYPE_ALARM 288</dd></dl> 289for NFSv4 ACLs. 290For POSIX.1e ACLs if 291ARCHIVE_ENTRY_ACL_TYPE_ACCESS 292is included and at least one extended ACL entry is found, 293the three non-extended ACLs are added. 294 295'''archive_entry_acl_from_text'''() 296and 297'''archive_entry_acl_from_text_w'''() 298add new 299(or merge with existing) 300ACL entries from 301(wide) 302text. 303The argument 304may take one of the following values: 305<dl> 306<dt></dt><dd> 307ARCHIVE_ENTRY_ACL_TYPE_ACCESS 308</dd><dt></dt><dd> 309ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 310</dd><dt></dt><dd> 311ARCHIVE_ENTRY_ACL_TYPE_NFS4 312</dd></dl> 313Supports all formats that can be created with 314'''archive_entry_acl_to_text'''() 315or respectively 316'''archive_entry_acl_to_text_w'''(). 317Existing ACL entries are preserved. 318To get a clean new ACL from text 319'''archive_entry_acl_clear'''() 320must be called first. 321Entries prefixed with 322"default:" 323are treated as 324ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 325unless 326is 327ARCHIVE_ENTRY_ACL_TYPE_NFS4. 328Invalid entries, non-parseable ACL entries and entries beginning with 329the 330Sq # 331character 332(comments) 333are skipped. 334 335'''archive_entry_acl_next'''() 336return the next entry of the ACL list. 337This functions may only be called after 338'''archive_entry_acl_reset'''() 339has indicated the presence of extended ACL entries. 340 341'''archive_entry_acl_reset'''() 342prepare reading the list of ACL entries with 343'''archive_entry_acl_next'''(). 344The function returns 0 if no non-extended ACLs are found. 345In this case, the access permissions should be obtained by 346[[ManPageArchiveEntryMode3]] 347or set using 348[[chmod(2)|http://www.freebsd.org/cgi/man.cgi?query=chmod&sektion=2]]. 349Otherwise, the function returns the same value as 350'''archive_entry_acl_count'''(). 351 352'''archive_entry_acl_to_text'''() 353and 354'''archive_entry_acl_to_text_w'''() 355convert the ACL entries for the given type into a 356(wide) 357string of ACL entries separated by newline. 358If the pointer 359is not NULL, then the function shall return the length of the string 360(not including the NULL terminator) 361in the location pointed to by 362. 363The 364argument is a bitwise-or. 365 366The following flags are effective only on POSIX.1e ACL: 367<dl> 368<dt></dt><dd> 369ARCHIVE_ENTRY_ACL_TYPE_ACCESS 370Output access ACLs. 371</dd><dt></dt><dd> 372ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 373Output POSIX.1e default ACLs. 374</dd><dt></dt><dd> 375ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 376Prefix each default ACL entry with the word 377"default:". 378</dd><dt></dt><dd> 379ARCHIVE_ENTRY_ACL_STYLE_SOLARIS 380The mask and other ACLs don not contain a double colon. 381</dd></dl> 382 383The following flags are effecive only on NFSv4 ACL: 384<dl> 385<dt></dt><dd> 386ARCHIVE_ENTRY_ACL_STYLE_COMPACT 387Do not output minus characters for unset permissions and flags in NFSv4 ACL 388permission and flag fields. 389</dd></dl> 390 391The following flags are effective on both POSIX.1e and NFSv4 ACL: 392<dl> 393<dt></dt><dd> 394ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 395Add an additional colon-separated field containing the user or group id. 396</dd><dt></dt><dd> 397ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA 398Separate ACL entries with comma instead of newline. 399</dd></dl> 400 401If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are returned. 402It the entry contains POSIX.1e ACLs and none of the flags 403ARCHIVE_ENTRY_ACL_TYPE_ACCESS 404or 405ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 406are specified, both access and default entries are returned and default entries 407are prefixed with 408"default:". 409 410'''archive_entry_acl_types'''() 411get ACL entry types contained in an archive entry's ACL. 412As POSIX.1e and NFSv4 413ACL entries cannot be mixed, this function is a very efficient way to detect if 414an ACL already contains POSIX.1e or NFSv4 ACL entries. 415== RETURN VALUES == 416'''archive_entry_acl_count'''() 417and 418'''archive_entry_acl_reset'''() 419returns the number of ACL entries that match the given type mask. 420For POSIX.1e ACLS if the type mask includes 421ARCHIVE_ENTRY_ACL_TYPE_ACCESS 422and at least one extended ACL entry exists, the three classic Unix 423permissions are counted. 424 425'''archive_entry_acl_from_text'''() 426and 427'''archive_entry_acl_from_text_w'''() 428return 429ARCHIVE_OK 430if all entries were successfully parsed and 431ARCHIVE_WARN 432if one or more entries were invalid or non-parseable. 433 434'''archive_entry_acl_next'''() 435returns 436ARCHIVE_OK 437on success, 438ARCHIVE_EOF 439if no more ACL entries exist 440and 441ARCHIVE_WARN 442if 443'''archive_entry_acl_reset'''() 444has not been called first. 445 446'''archive_entry_acl_to_text'''() 447returns a string representing the ACL entries matching the given type and 448flags on success or NULL on error. 449 450'''archive_entry_acl_to_text_w'''() 451returns a wide string representing the ACL entries matching the given type 452and flags on success or NULL on error. 453 454'''archive_entry_acl_types'''() 455returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries. 456== SEE ALSO == 457[[ManPageArchiveEntry3]], 458[[ManPageLibarchive3]] 459