1 '\" te
   2 .\" Copyright (c) 2020 Peter Tribble.
   3 .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
   4 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH ACL 5 "Feb 8, 2020"
   9 .SH NAME
  10 acl \- Access Control Lists
  11 .SH DESCRIPTION
  12 Access control lists (ACLs) are discretionary access control mechanisms that
  13 grant and deny access to files and directories. Two different ACL models are
  14 supported in this release: POSIX-draft ACLs and NFSv4 ACLs.
  15 .sp
  16 .LP
  17 The older, POSIX-draft model is supported by the UFS file system. This model is
  18 based on a withdrawn ACL POSIX specification that was never standardized. It
  19 was subsequently withdrawn by the POSIX committee.
  20 .sp
  21 .LP
  22 The other model is based on the standards of the NFSv4 working group and is an
  23 approved standard from the Internet Engineering Task Force (IETF). The ZFS file
  24 system uses the NFSv4 model, and provides richer semantics and finer grained
  25 permission capabilities than the POSIX-draft model.
  26 .SS "POSIX-draft ACLs"
  27 POSIX-draft ACLs provide an alternative security mechanism to basic UNIX file
  28 permissions. Their purpose is to further restrict access
  29 to files and directories or to extend permissions to a particular user. ACLs
  30 can be used to change the permissions for the standard owner, group and other
  31 class bits of a file's mode. ACLs can give additional users and groups access
  32 to the file. A directory can also have a special kind of ACL called a
  33 \fBdefault\fR ACL, which defines ACL entries to be inherited by descendents of
  34 the directory. POSIX-draft ACLs have an ACL entry called \fBmask\fR. The mask
  35 defines the maximum permissions that can be granted to additional user and
  36 group entries. Whenever a file is created or its mode is changed by
  37 \fBchmod\fR(1) or \fBchmod\fR(2), the mask is recomputed. It is recomputed to
  38 be the group permission defined in the mode passed to \fBchmod\fR(2).
  39 .sp
  40 .LP
  41 The POSIX-draft ACL model uses the standard \fBrwx\fR model of traditional UNIX
  42 permissions.
  43 .sp
  44 .LP
  45 An ACL is represented as follows:
  46 .sp
  47 .in +2
  48 .nf
  49 \fIacl_entry\fR[,\fIacl_entry\fR]...
  50 .fi
  51 .in -2
  52 .sp
  53 
  54 .sp
  55 .LP
  56 Each \fIacl_entry\fR contains one ACL entry. An ACL entry is represented by two
  57 or three colon-separated(\fB:\fR) fields.
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIuser\fR:[\fIuid\fR]:\fIperms\fR\fR
  62 .ad
  63 .RS 21n
  64 If \fIuid\fR blank, it represents the file owner.
  65 .RE
  66 
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIgroup\fR:[\fIgid\fR]:\fIperms\fR\fR
  71 .ad
  72 .RS 21n
  73 If \fIgid\fR is blank, it represents the owning group.
  74 .RE
  75 
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fIother\fR:\fIperms\fR\fR
  80 .ad
  81 .RS 21n
  82 Represents the file other class.
  83 .RE
  84 
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fImask\fR:\fIperms\fR\fR
  89 .ad
  90 .RS 21n
  91 Defines the \fBMAX\fR permission to hand out.
  92 .RE
  93 
  94 .sp
  95 .LP
  96 For example to give user \fBjoe\fR read and write permissions, the ACL entry is
  97 specified as:
  98 .sp
  99 .in +2
 100 .nf
 101 user:joe:rw-
 102 .fi
 103 .in -2
 104 .sp
 105 
 106 .SS "NFSv4 ACLs"
 107 The NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4 ACLs
 108 provide a much richer ACL model than POSIX-draft ACLs.
 109 .sp
 110 .LP
 111 The major differences between NFSv4 and POSIX-draft ACLs are as follows:
 112 .RS +4
 113 .TP
 114 .ie t \(bu
 115 .el o
 116 NFSv4 ACLs provide finer grained permissions than the \fBrwx\fR model.
 117 .RE
 118 .RS +4
 119 .TP
 120 .ie t \(bu
 121 .el o
 122 NFSv4 ACLs allow for both \fBALLOW\fR and \fBDENY\fR entries.
 123 .RE
 124 .RS +4
 125 .TP
 126 .ie t \(bu
 127 .el o
 128 NFSv4 ACLs provide a rich set of inheritance semantics. POSIX ACLs also have
 129 inheritance, but with the NFSv4 model you can control the following inheritance
 130 features:
 131 .RS +4
 132 .TP
 133 .ie t \(bu
 134 .el o
 135 Whether inheritance cascades to both files and directories or only to files or
 136 directories.
 137 .RE
 138 .RS +4
 139 .TP
 140 .ie t \(bu
 141 .el o
 142 In the case of directories, you can indicate whether inheritance is applied to
 143 the directory itself, to just one level of subdirectories, or cascades to all
 144 subdirectories of the directory.
 145 .RE
 146 .RE
 147 .RS +4
 148 .TP
 149 .ie t \(bu
 150 .el o
 151 NFSv4 ACLs provide a mechanism for hooking into a system's audit trail.
 152 Currently, illumos does not support this mechanism.
 153 .RE
 154 .RS +4
 155 .TP
 156 .ie t \(bu
 157 .el o
 158 NFSv4 ACLs enable administrators to specify the order in which ACL entries are
 159 checked. With POSIX-draft ACLs the file system reorders ACL entries into a well
 160 defined, strict access, checking order.
 161 .RE
 162 .sp
 163 .LP
 164 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However, only some
 165 NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
 166 .sp
 167 .LP
 168 Permissions can be specified in three different \fBchmod\fR ACL formats:
 169 verbose, compact, or positional. The verbose format uses words to indicate that
 170 the permissions are separated with a forward slash (\fB/\fR) character. Compact
 171 format uses the permission letters and positional format uses the permission
 172 letters or the hyphen (\fB-\fR) to identify no permissions.
 173 .sp
 174 .LP
 175 The permissions for verbose mode and their abbreviated form in parentheses for
 176 compact and positional mode are described as follows:
 177 .sp
 178 .ne 2
 179 .na
 180 \fBread_data (\fBr\fR)\fR
 181 .ad
 182 .RS 24n
 183 Permission to read the data of the file
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .na
 189 \fBlist_directory (\fBr\fR)\fR
 190 .ad
 191 .RS 24n
 192 Permission to list the contents of a directory.
 193 .RE
 194 
 195 .sp
 196 .ne 2
 197 .na
 198 \fBwrite_data (\fBw\fR)\fR
 199 .ad
 200 .RS 24n
 201 Permission to modify a file's data anywhere in the file's offset range. This
 202 includes the ability to grow the file or write to any arbitrary offset.
 203 .RE
 204 
 205 .sp
 206 .ne 2
 207 .na
 208 \fBadd_file (\fBw\fR)\fR
 209 .ad
 210 .RS 24n
 211 Permission to add a new file to a directory.
 212 .RE
 213 
 214 .sp
 215 .ne 2
 216 .na
 217 \fBappend_data (\fBp\fR)\fR
 218 .ad
 219 .RS 24n
 220 The ability to modify the file's data, but only starting at EOF. Currently,
 221 this permission is not supported.
 222 .RE
 223 
 224 .sp
 225 .ne 2
 226 .na
 227 \fBadd_subdirectory (\fBp\fR)\fR
 228 .ad
 229 .RS 24n
 230 Permission to create a subdirectory to a directory.
 231 .RE
 232 
 233 .sp
 234 .ne 2
 235 .na
 236 \fBread_xattr (\fBR\fR)\fR
 237 .ad
 238 .RS 24n
 239 The ability to read the extended attributes of a file or do a lookup in the
 240 extended attributes directory.
 241 .RE
 242 
 243 .sp
 244 .ne 2
 245 .na
 246 \fBwrite_xattr (\fBW\fR)\fR
 247 .ad
 248 .RS 24n
 249 The ability to create extended attributes or write to the extended attributes
 250 directory.
 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fBexecute (\fBx\fR)\fR
 257 .ad
 258 .RS 24n
 259 Permission to execute a file.
 260 .RE
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fBread_attributes (\fBa\fR)\fR
 266 .ad
 267 .RS 24n
 268 The ability to read basic attributes (non-ACLs) of a file. Basic attributes are
 269 considered to be the stat level attributes. Allowing this access mask bit means
 270 that the entity can execute \fBls\fR(1) and \fBstat\fR(2).
 271 .RE
 272 
 273 .sp
 274 .ne 2
 275 .na
 276 \fBwrite_attributes (\fBA\fR)\fR
 277 .ad
 278 .RS 24n
 279 Permission to change the times associated with a file or directory to an
 280 arbitrary value.
 281 .RE
 282 
 283 .sp
 284 .ne 2
 285 .na
 286 \fBdelete (\fBd\fR)\fR
 287 .ad
 288 .RS 24n
 289 Permission to delete the file.
 290 .RE
 291 
 292 .sp
 293 .ne 2
 294 .na
 295 \fBdelete_child (\fBD\fR)\fR
 296 .ad
 297 .RS 24n
 298 Permission to delete a file within a directory.
 299 .RE
 300 
 301 .sp
 302 .ne 2
 303 .na
 304 \fBread_acl (\fBc\fR)\fR
 305 .ad
 306 .RS 24n
 307 Permission to read the ACL.
 308 .RE
 309 
 310 .sp
 311 .ne 2
 312 .na
 313 \fBwrite_acl (\fBC\fR)\fR
 314 .ad
 315 .RS 24n
 316 Permission to write the ACL or the ability to execute \fBchmod\fR(1) or
 317 \fBsetfacl\fR(1).
 318 .RE
 319 
 320 .sp
 321 .ne 2
 322 .na
 323 \fBwrite_owner (\fBo\fR)\fR
 324 .ad
 325 .RS 24n
 326 Permission to change the owner or the ability to execute \fBchown\fR(1) or
 327 \fBchgrp\fR(1).
 328 .RE
 329 
 330 .sp
 331 .ne 2
 332 .na
 333 \fBsynchronize (\fBs\fR)\fR
 334 .ad
 335 .RS 24n
 336 Permission to access a file locally at the server with synchronous reads and
 337 writes. Currently, this permission is not supported.
 338 .RE
 339 
 340 .sp
 341 .LP
 342 The following inheritance flags are supported by NFSv4 ACLs:
 343 .sp
 344 .ne 2
 345 .na
 346 \fBfile_inherit (\fBf\fR)\fR
 347 .ad
 348 .RS 26n
 349 Inherit to all newly created files in a directory.
 350 .RE
 351 
 352 .sp
 353 .ne 2
 354 .na
 355 \fBdir_inherit (\fBd\fR)\fR
 356 .ad
 357 .RS 26n
 358 Inherit to all newly created directories in a directory.
 359 .RE
 360 
 361 .sp
 362 .ne 2
 363 .na
 364 \fBinherit_only (\fBi\fR)\fR
 365 .ad
 366 .RS 26n
 367 Placed on a directory, but does not apply to the directory itself, only to
 368 newly created files and directories. This flag requires file_inherit
 369 and/or dir_inherit to indicate what to inherit.
 370 .RE
 371 
 372 .sp
 373 .ne 2
 374 .na
 375 \fBno_propagate (\fBn\fR)\fR
 376 .ad
 377 .RS 26n
 378 Placed on directories and indicates that ACL entries should only be inherited
 379 one level of the tree. This flag requires file_inherit and/or dir_inherit to
 380 indicate what to inherit.
 381 .RE
 382 
 383 .sp
 384 .ne 2
 385 .na
 386 \fBsuccessful_access (\fBS\fR)\fR
 387 .ad
 388 .RS 26n
 389 Indicates whether an alarm or audit record should be initiated upon successful
 390 accesses. Used with audit/alarm ACE types.
 391 .RE
 392 
 393 .sp
 394 .ne 2
 395 .na
 396 \fBfailed_access (\fBF\fR)\fR
 397 .ad
 398 .RS 26n
 399 Indicates whether an alarm or audit record should be initiated when access
 400 fails. Used with audit/alarm ACE types.
 401 .RE
 402 
 403 .sp
 404 .ne 2
 405 .na
 406 \fBinherited (\fBI\fR)\fR
 407 .ad
 408 .RS 26n
 409 ACE was inherited.
 410 .RE
 411 
 412 .sp
 413 .ne 2
 414 .na
 415 \fB\fB-\fR\fR
 416 .ad
 417 .RS 26n
 418 No permission granted.
 419 .RE
 420 
 421 .sp
 422 .LP
 423 An NFSv4 ACL is expressed using the following syntax:
 424 .sp
 425 .in +2
 426 .nf
 427 \fIacl_entry\fR[,\fIacl_entry\fR]...
 428 
 429     owner@:<perms>[:inheritance flags]:<allow|deny>
 430     group@:<perms>[:inheritance flags]:<allow|deny>
 431     everyone@:<perms>[:inheritance flags]:<allow|deny>
 432     user:<username>:<perms>[:inheritance flags]:<allow|deny>
 433     usersid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
 434     group:<groupname>:<perms>[:inheritance flags]:<allow|deny>
 435     groupsid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
 436     sid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
 437 .fi
 438 .in -2
 439 
 440 .sp
 441 .ne 2
 442 .na
 443 \fBowner@\fR
 444 .ad
 445 .RS 10n
 446 File owner
 447 .RE
 448 
 449 .sp
 450 .ne 2
 451 .na
 452 \fBgroup@\fR
 453 .ad
 454 .RS 10n
 455 Group owner
 456 .RE
 457 
 458 .sp
 459 .ne 2
 460 .na
 461 \fBuser\fR
 462 .ad
 463 .RS 10n
 464 Permissions for a specific user
 465 .RE
 466 
 467 .sp
 468 .ne 2
 469 .na
 470 \fBgroup\fR
 471 .ad
 472 .RS 10n
 473 Permissions for a specific group
 474 .RE
 475 
 476 .sp
 477 .LP
 478 Permission and inheritance flags are separated by a \fB/\fR character.
 479 .sp
 480 .LP
 481 ACL specification examples:
 482 .sp
 483 .in +2
 484 .nf
 485 user:fred:read_data/write_data/read_attributes:file_inherit:allow
 486 owner@:read_data:allow,group@:read_data:allow,user:tom:read_data:deny
 487 .fi
 488 .in -2
 489 .sp
 490 
 491 .sp
 492 .LP
 493 Using the compact ACL format, permissions are specified by using 14 unique
 494 letters to indicate permissions.
 495 .sp
 496 .LP
 497 Using the positional ACL format, permissions are specified as positional
 498 arguments similar to the \fBls -V\fR format. The hyphen (\fB-\fR), which
 499 indicates that no permission is granted at that position, can be omitted and
 500 only the required letters have to be specified.
 501 .sp
 502 .LP
 503 The letters above are listed in the order they would be specified in positional
 504 notation.
 505 .sp
 506 .LP
 507 With these letters you can specify permissions in the following equivalent
 508 ways.
 509 .sp
 510 .in +2
 511 .nf
 512 user:fred:rw------R------:file_inherit:allow
 513 .fi
 514 .in -2
 515 .sp
 516 
 517 .sp
 518 .LP
 519 Or you can remove the \fB-\fR and scrunch it together.
 520 .sp
 521 .in +2
 522 .nf
 523 user:fred:rwR:file_inherit:allow
 524 .fi
 525 .in -2
 526 .sp
 527 
 528 .sp
 529 .LP
 530 The inheritance flags can also be specified in a more compact manner, as
 531 follows:
 532 .sp
 533 .in +2
 534 .nf
 535 user:fred:rwR:f:allow
 536 user:fred:rwR:f------:allow
 537 .fi
 538 .in -2
 539 .sp
 540 
 541 .SS "Shell-level API"
 542 Several utilities support the manipulation of ACLs. The following
 543 utilities accommodate both ACL models:
 544 .sp
 545 .ne 2
 546 .na
 547 \fB\fBchmod\fR\fR
 548 .ad
 549 .RS 12n
 550 The \fBchmod\fR utility has been enhanced to allow for the setting and deleting
 551 of ACLs. This is achieved by extending the symbolic-mode argument to support
 552 ACL manipulation. See \fBchmod\fR(1) for details.
 553 .RE
 554 
 555 .sp
 556 .ne 2
 557 .na
 558 \fB\fBcompress\fR\fR
 559 .ad
 560 .RS 12n
 561 When a file is compressed any ACL associated with the original file is
 562 preserved with the compressed file.
 563 .RE
 564 
 565 .sp
 566 .ne 2
 567 .na
 568 \fB\fBcp\fR\fR
 569 .ad
 570 .RS 12n
 571 By default, \fBcp\fR ignores ACLs, unless the \fB-p\fR option is specified.
 572 When \fB-p\fR is specified the owner and group id, permission modes,
 573 modification and access times, ACLs, and extended attributes if applicable are
 574 preserved.
 575 .RE
 576 
 577 .sp
 578 .ne 2
 579 .na
 580 \fB\fBcpio\fR\fR
 581 .ad
 582 .RS 12n
 583 ACLs are preserved when the \fB-P\fR option is specified.
 584 .RE
 585 
 586 .sp
 587 .ne 2
 588 .na
 589 \fB\fBfind\fR\fR
 590 .ad
 591 .RS 12n
 592 Find locates files with ACLs when the \fB-acl\fR flag is specified.
 593 .RE
 594 
 595 .sp
 596 .ne 2
 597 .na
 598 \fB\fBls\fR\fR
 599 .ad
 600 .RS 12n
 601 By default \fBls\fR does not display ACL information. When the \fB-v\fR option
 602 is specified, a file's ACL is displayed.
 603 .RE
 604 
 605 .sp
 606 .ne 2
 607 .na
 608 \fB\fBmv\fR\fR
 609 .ad
 610 .RS 12n
 611 When a file is moved, all attributes are carried along with the renamed file.
 612 When a file is moved across a file system boundary, the ACLs are replicated. If
 613 the ACL information cannot be replicated, the move fails and the source file is
 614 not removed.
 615 .RE
 616 
 617 .sp
 618 .ne 2
 619 .na
 620 \fB\fBpack\fR\fR
 621 .ad
 622 .RS 12n
 623 When a file is packed, any ACL associated with the original file is preserved
 624 with the packed file.
 625 .RE
 626 
 627 .sp
 628 .ne 2
 629 .na
 630 \fB\fBrcp\fR\fR
 631 .ad
 632 .RS 12n
 633 \fBrcp\fR has been enhanced to support copying. A file's ACL is only preserved
 634 when the remote host supports ACLs.
 635 .RE
 636 
 637 .sp
 638 .ne 2
 639 .na
 640 \fB\fBtar\fR\fR
 641 .ad
 642 .RS 12n
 643 ACLs are preserved when the \fB-p\fR option is specified.
 644 .RE
 645 
 646 .sp
 647 .ne 2
 648 .na
 649 \fB\fBunpack\fR\fR
 650 .ad
 651 .RS 12n
 652 When a file with an ACL is unpacked, the unpacked file retains the ACL
 653 information.
 654 .RE
 655 
 656 .SS "Application-level API"
 657 The primary interfaces required to access file system ACLs at the programmatic
 658 level are the \fBacl_get()\fR and \fBacl_set()\fR functions. These functions
 659 support both POSIX-draft ACLs and NFSv4 ACLs.
 660 .SS "Retrieving a file's ACL"
 661 .in +2
 662 .nf
 663 int acl_get(const char *path, int flag, acl_t **aclp);
 664 int facl_get(int fd, int flag, acl_t **aclp);
 665 .fi
 666 .in -2
 667 
 668 .sp
 669 .LP
 670 The \fBacl_get\fR(3SEC) and \fBfacl_get\fR(3SEC) functions retrieve an ACL on
 671 a file whose name is given by path or referenced by the open file descriptor
 672 fd. The flag argument specifies whether a trivial ACL should be retrieved. When
 673 the flag argument equals \fBACL_NO_TRIVIAL\fR only ACLs that are not
 674 trivial are retrieved. The ACL is returned in the \fBaclp\fR argument.
 675 .SS "Freeing ACL structure"
 676 .in +2
 677 .nf
 678 void acl_free(acl_t *aclp);
 679 .fi
 680 .in -2
 681 
 682 .sp
 683 .LP
 684 The \fBacl_free()\fR function frees up memory allocated for the argument
 685 \fBaclp\fR.
 686 .SS "Setting an ACL on a file"
 687 .in +2
 688 .nf
 689 int acl_set(const char *path, acl_t *aclp);
 690 int facl_set(int fd, acl_t *aclp);
 691 .fi
 692 .in -2
 693 
 694 .sp
 695 .LP
 696 The \fBacl_set\fR(3SEC) and \fBfacl_get\fR(3SEC) functions are used for setting
 697 an ACL on a file whose name is given by path or referenced by the open file
 698 descriptor \fBfd\fR. The \fBaclp\fR argument specifies the ACL to set. The
 699 \fBacl_set\fR(3SEC) function translates a POSIX-draft ACL into a NFSv4 ACL when
 700 the target file system supports NFSv4 ACLs. No translation is performed when
 701 trying to set an NFSv4 ACL on a POSIX-draft ACL supported file system.
 702 .SS "Determining an ACL's trivialness"
 703 .in +2
 704 .nf
 705 int acl_trivial(const char *path);
 706 .fi
 707 .in -2
 708 
 709 .sp
 710 .LP
 711 The \fBacl_trivial()\fR function is used to determine whether a file has a
 712 trivial ACL.
 713 .SS "Removing all ACLs from a file"
 714 .in +2
 715 .nf
 716 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
 717 .fi
 718 .in -2
 719 
 720 .sp
 721 .LP
 722 The \fBacl_strip()\fR function removes all ACLs from a file and replaces them
 723 with a trivial ACL based off of the passed in argument mode. After replacing
 724 the ACL the owner and group of the file are set to the values specified in the
 725 uid and gid parameters.
 726 .SS "Converting ACLs to/from external representation"
 727 .in +2
 728 .nf
 729 int acl_fromtext(const char *path, acl_t **aclp);
 730 char *acl_totext(acl_t *aclp, int flags);
 731 .fi
 732 .in -2
 733 
 734 .sp
 735 .LP
 736 The \fBacl_totext()\fR function converts an internal ACL representation pointed
 737 to by aclp into an external representation. See \fBDESCRIPTION\fR for details
 738 about external representation.
 739 .sp
 740 .LP
 741 The \fBacl_fromtext()\fR function converts an external representation into an
 742 internal representation. See \fBDESCRIPTION\fR for details about external
 743 representation.
 744 .SH EXAMPLES
 745 The following examples demonstrate how the API can be used to perform basic
 746 operations on ACLs.
 747 .LP
 748 \fBExample 1 \fRRetrieving and Setting an ACL
 749 .sp
 750 .LP
 751 Use the following to retrieve an ACL and set it on another file:
 752 
 753 .sp
 754 .in +2
 755 .nf
 756 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
 757 
 758 if (error == 0 && aclp != NULL) {
 759 .in +8
 760 error = acl_set("file2", aclp);
 761 acl_free(aclp);
 762 .in -8
 763 }
 764 \&...
 765 .fi
 766 .in -2
 767 
 768 .LP
 769 \fBExample 2 \fRRetrieving and Setting Any ACLs
 770 .sp
 771 .LP
 772 Use the following to retrieve any ACL, including trivial ACLs, and set it on
 773 another file:
 774 
 775 .sp
 776 .in +2
 777 .nf
 778 error = acl_get("file3", 0, &aclp);
 779 if (error == 0) {
 780 .in +8
 781 error = acl_set("file4", aclp);
 782 acl_free(aclp);
 783 .in -8
 784 }
 785 \&...
 786 .fi
 787 .in -2
 788 
 789 .LP
 790 \fBExample 3 \fRDetermining if a File has a Trivial ACL
 791 .sp
 792 .LP
 793 Use the following to determine if a file has a trivial ACL:
 794 
 795 .sp
 796 .in +2
 797 .nf
 798 char *file = "file5";
 799 istrivial = acl_trivial(file);
 800 
 801 if (istrivial == 0)
 802 .in +8
 803 printf("file %s has a trivial ACL\en", file);
 804 .in -8
 805 else
 806 .in +8
 807 printf("file %s has a NON-trivial ACL\en", file);
 808 .in -8
 809 \&...
 810 .fi
 811 .in -2
 812 
 813 .LP
 814 \fBExample 4 \fRRemoving all ACLs from a File
 815 .sp
 816 .LP
 817 Use the following to remove all ACLs from a file, and set a new mode, owner,
 818 and group:
 819 
 820 .sp
 821 .in +2
 822 .nf
 823 error = acl_strip("file", 10, 100, 0644);
 824 \&...
 825 .fi
 826 .in -2
 827 
 828 .SH SEE ALSO
 829 \fBchgrp\fR(1), \fBchmod\fR(1), \fBchown\fR(1), \fBcp\fR(1), \fBcpio\fR(1),
 830 \fBfind\fR(1), \fBls\fR(1), \fBmv\fR(1), \fBtar\fR(1), \fBsetfacl\fR(1),
 831 \fBchmod\fR(2), \fBacl\fR(2), \fBstat\fR(2), \fBacl_get\fR(3SEC),
 832 \fBaclsort\fR(3SEC), \fBacl_fromtext\fR(3SEC), \fBacl_free\fR(3SEC),
 833 \fBacl_strip\fR(3SEC), \fBacl_trivial\fR(3SEC)