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