1 '\" te
   2 .\" Copyright (c) 20068 Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH ACL_TOTEXT 3SEC "Jun 16, 2008"
   7 .SH NAME
   8 acl_totext, acl_fromtext \- convert internal representation  to or from
   9 external representation
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lsec\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <sys/acl.h>
  15 
  16 \fBchar *\fR\fBacl_totext\fR(\fBacl_t *\fR\fIaclp\fR, \fBint\fR \fIflags\fR);
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBint\fR \fBacl_fromtext\fR(\fBchar *\fR\fIacltextp\fR, \fBacl_t **\fR\fIaclp\fR);
  22 .fi
  23 
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBacl_totext()\fR function converts an internal ACL representation pointed
  28 to by \fIaclp\fR into an external ACL representation. The memory for the
  29 external text string is obtained using \fBmalloc\fR(3C). The caller is
  30 responsible for freeing the memory upon completion.
  31 .sp
  32 .LP
  33 The format of the external ACL is controlled by the \fIflags\fR argument.
  34 Values for \fIflags\fR are constructed by a bitwise-inclusive-OR of \fIflags\fR
  35 from the following list, defined in <\fBsys/acl.h\fR>.
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fBACL_COMPACT_FMT\fR\fR
  40 .ad
  41 .RS 19n
  42 For NFSv4 ACLs, the ACL entries will be formatted using the compact ACL format
  43 detailed in \fBls\fR(1) for the \fB-V\fR option.
  44 .RE
  45 
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fBACL_APPEND_ID\fR\fR
  50 .ad
  51 .RS 19n
  52 Append the \fBuid\fR or \fBgid\fR for additional user or group entries.  This
  53 flag is used to construt ACL entries in a manner that is suitable for archive
  54 utilities such as \fBtar\fR(1). When the ACL is translated from the external
  55 format to internal representation using \fBacl_fromtext()\fR, the appended ID
  56 will be used to populate the \fBuid\fR or \fBgid\fR field of the ACL entry when
  57 the user or group name does not exist on the host system. The appended id will
  58 be ignored when the user or group name does exist on the system.
  59 .RE
  60 
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBACL_SID_FMT\fR\fR
  65 .ad
  66 .RS 19n
  67 For NFSv4 ACLs, the ACL entries for user or group entries will use the
  68 \fBusersid\fR or \fBgroupsid\fR format when the "id" field in the ACL entry is
  69 an ephemeral \fBuid\fR or \fBgid\fR.  The raw \fBsid\fR format will only be
  70 used when the "id" cannot be resolved to a windows name.
  71 .RE
  72 
  73 .sp
  74 .LP
  75 The \fBacl_fromtext()\fR function converts an external ACL representation
  76 pointed to by \fIacltextp\fR into an internal ACL representation. The memory
  77 for the list of ACL entries is obtained using \fBmalloc\fR(3C). The caller is
  78 responsible for freeing the memory upon completion. Depending on type of ACLs a
  79 file system supports, one of two external external representations are
  80 possible. For POSIX draft file systems such as ufs, the external representation
  81 is described in \fBacltotext\fR(3SEC). The external ACL representation For
  82 NFSv4-style ACLs is detailed as follows.
  83 .sp
  84 .LP
  85 Each \fBacl_entry\fR contains one ACL entry. The external representation of an
  86 ACL entry contains three, four or five colon separated fields. The first field
  87 contains the ACL entry type. The entry type keywords are defined as:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBeveryone@\fR\fR
  92 .ad
  93 .RS 13n
  94 This ACL entry specifies the access granted to any user or group that does not
  95 match any previous ACL entry.
  96 .RE
  97 
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBgroup\fR\fR
 102 .ad
 103 .RS 13n
 104 This ACL entry with a GID specifies the access granted to a additional group of
 105 the object.
 106 .RE
 107 
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBgroup@\fR\fR
 112 .ad
 113 .RS 13n
 114 This ACL entry with no GID specified in the ACL entry field specifies the
 115 access granted to the owning group of the object.
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBgroupsid\fR\fR
 122 .ad
 123 .RS 13n
 124 This ACL entry with a SID or Windows name specifies the access granted to a
 125 Windows group. This type of entry is for a CIFS server created file.
 126 .RE
 127 
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBowner@\fR\fR
 132 .ad
 133 .RS 13n
 134 This ACL entry with no UID specified in the ACL entry field specifies the
 135 access granted to the owner of the object.
 136 .RE
 137 
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBsid\fR\fR
 142 .ad
 143 .RS 13n
 144 This ACL entry with a SID or Windows name when the entry could be either a
 145 group or a user.
 146 .RE
 147 
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBuser\fR\fR
 152 .ad
 153 .RS 13n
 154 This ACL entry with a UID specifies the access granted to a additional user of
 155 the object.
 156 .RE
 157 
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBusersid\fR\fR
 162 .ad
 163 .RS 13n
 164 This ACL entry with a SID or Windows name specifies the access granted to a
 165 Windows user. This type of entry is for a CIFS server created file.
 166 .RE
 167 
 168 .sp
 169 .LP
 170 The second field contains the ACL entry ID, and is used only for user or group
 171 ACL entries. This field is not used for \fBowner@\fR, \fBgroup@\fR, or
 172 \fBeveryone@\fR entries.
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBuid\fR\fR
 177 .ad
 178 .RS 7n
 179 This field contains a user-name or user-ID. If the user-name cannot be resolved
 180 to a UID, then the entry is assumed to be a numeric UID.
 181 .RE
 182 
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBgid\fR\fR
 187 .ad
 188 .RS 7n
 189 This field contains a group-name or group-ID. If the group-name can't be
 190 resolved to a GID, then the entry is assumed to be a numeric GID.
 191 .RE
 192 
 193 .sp
 194 .LP
 195 The third field contains the discretionary access permissions. The format of
 196 the permissions depends on whether \fBACL_COMPACT_FMT\fR is specified. When the
 197 \fIflags\fR field does not request \fBACL_COMPACT_FMT\fR, the following format
 198 is used with a forward slash (/) separating the permissions.
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBadd_file\fR\fR
 203 .ad
 204 .RS 20n
 205 Add a file to a directory.
 206 .RE
 207 
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBadd_subdirectory\fR\fR
 212 .ad
 213 .RS 20n
 214 Add a subdirectory.
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBappend\fR\fR
 221 .ad
 222 .RS 20n
 223 Append data.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBdelete\fR\fR
 230 .ad
 231 .RS 20n
 232 Delete.
 233 .RE
 234 
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBdelete_child\fR\fR
 239 .ad
 240 .RS 20n
 241 Delete child.
 242 .RE
 243 
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBexecute\fR\fR
 248 .ad
 249 .RS 20n
 250 Execute permission.
 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBlist_directory\fR\fR
 257 .ad
 258 .RS 20n
 259 List a directory.
 260 .RE
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBread_acl\fR\fR
 266 .ad
 267 .RS 20n
 268 Read ACL.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBread_data\fR\fR
 275 .ad
 276 .RS 20n
 277 Read permission.
 278 .RE
 279 
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fBread_attributes\fR\fR
 284 .ad
 285 .RS 20n
 286 Read attributes.
 287 .RE
 288 
 289 .sp
 290 .ne 2
 291 .na
 292 \fB\fBread_xattr\fR\fR
 293 .ad
 294 .RS 20n
 295 Read named attributes.
 296 .RE
 297 
 298 .sp
 299 .ne 2
 300 .na
 301 \fB\fBsynchronize\fR\fR
 302 .ad
 303 .RS 20n
 304 Synchronize.
 305 .RE
 306 
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fBwrite_acl\fR\fR
 311 .ad
 312 .RS 20n
 313 Write ACL.
 314 .RE
 315 
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fBwrite_attributes\fR\fR
 320 .ad
 321 .RS 20n
 322 Write attributes.
 323 .RE
 324 
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fBwrite_data\fR\fR
 329 .ad
 330 .RS 20n
 331 Write permission.
 332 .RE
 333 
 334 .sp
 335 .ne 2
 336 .na
 337 \fB\fBwrite_owner\fR\fR
 338 .ad
 339 .RS 20n
 340 Write owner.
 341 .RE
 342 
 343 .sp
 344 .ne 2
 345 .na
 346 \fB\fBwrite_xattr\fR\fR
 347 .ad
 348 .RS 20n
 349 Write named attributes.
 350 .RE
 351 
 352 .sp
 353 .LP
 354 This format allows permissions to be specified as, for example:
 355 \fBread_data\fR/\fBread_xattr\fR/\fBread_attributes\fR.
 356 .sp
 357 .LP
 358 When \fBACL_COMPACT_FMT\fR is specified, the permissions consist of 14 unique
 359 letters.  A hyphen (-) character is used to indicate that the permission at
 360 that position is not specified.
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fBa\fR\fR
 365 .ad
 366 .RS 5n
 367 read attributes
 368 .RE
 369 
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fBA\fR\fR
 374 .ad
 375 .RS 5n
 376 write attributes
 377 .RE
 378 
 379 .sp
 380 .ne 2
 381 .na
 382 \fB\fBc\fR\fR
 383 .ad
 384 .RS 5n
 385 read ACL
 386 .RE
 387 
 388 .sp
 389 .ne 2
 390 .na
 391 \fB\fBC\fR\fR
 392 .ad
 393 .RS 5n
 394 write ACL
 395 .RE
 396 
 397 .sp
 398 .ne 2
 399 .na
 400 \fB\fBd\fR\fR
 401 .ad
 402 .RS 5n
 403 delete
 404 .RE
 405 
 406 .sp
 407 .ne 2
 408 .na
 409 \fB\fBD\fR\fR
 410 .ad
 411 .RS 5n
 412 delete child
 413 .RE
 414 
 415 .sp
 416 .ne 2
 417 .na
 418 \fB\fBo\fR\fR
 419 .ad
 420 .RS 5n
 421 write owner
 422 .RE
 423 
 424 .sp
 425 .ne 2
 426 .na
 427 \fB\fBp\fR\fR
 428 .ad
 429 .RS 5n
 430 append
 431 .RE
 432 
 433 .sp
 434 .ne 2
 435 .na
 436 \fB\fBr\fR\fR
 437 .ad
 438 .RS 5n
 439 read_data
 440 .RE
 441 
 442 .sp
 443 .ne 2
 444 .na
 445 \fB\fBR\fR\fR
 446 .ad
 447 .RS 5n
 448 read named attributes
 449 .RE
 450 
 451 .sp
 452 .ne 2
 453 .na
 454 \fB\fBs\fR\fR
 455 .ad
 456 .RS 5n
 457 synchronize
 458 .RE
 459 
 460 .sp
 461 .ne 2
 462 .na
 463 \fB\fBw\fR\fR
 464 .ad
 465 .RS 5n
 466 write_data
 467 .RE
 468 
 469 .sp
 470 .ne 2
 471 .na
 472 \fB\fBW\fR\fR
 473 .ad
 474 .RS 5n
 475 write named attributes
 476 .RE
 477 
 478 .sp
 479 .ne 2
 480 .na
 481 \fB\fBx\fR\fR
 482 .ad
 483 .RS 5n
 484 execute
 485 .RE
 486 
 487 .sp
 488 .LP
 489 This format allows compact permissions to be represented as, for example:
 490 \fBrw--d-a-------\fR
 491 .sp
 492 .LP
 493 The fourth field is optional when \fBACL_COMPACT_FMT\fR is not specified, in
 494 which case the field will be present only when the ACL entry has inheritance
 495 flags set. The following is the list of inheritance flags separated by a slash
 496 (/) character.
 497 .sp
 498 .ne 2
 499 .na
 500 \fB\fBdir_inherit\fR\fR
 501 .ad
 502 .RS 16n
 503 \fBACE_DIRECTORY_INHERIT_ACE\fR
 504 .RE
 505 
 506 .sp
 507 .ne 2
 508 .na
 509 \fB\fBfile_inherit\fR\fR
 510 .ad
 511 .RS 16n
 512 \fBACE_FILE_INHERIT_ACE\fR
 513 .RE
 514 
 515 .sp
 516 .ne 2
 517 .na
 518 \fB\fBinherit_only\fR\fR
 519 .ad
 520 .RS 16n
 521 \fBACE_INHERIT_ONLY_ACE\fR
 522 .RE
 523 
 524 .sp
 525 .ne 2
 526 .na
 527 \fB\fBno_propagate\fR\fR
 528 .ad
 529 .RS 16n
 530 \fBACE_NO_PROPAGATE_INHERIT_ACE\fR
 531 .RE
 532 
 533 .sp
 534 .LP
 535 When \fBACL_COMPACT_FMT\fR is specified the inheritance will always be present
 536 and is represented as positional arguments. A hyphen (-) character is used to
 537 indicate that the inheritance flag at that position is not specified.
 538 .sp
 539 .ne 2
 540 .na
 541 \fB\fBd\fR\fR
 542 .ad
 543 .RS 5n
 544 \fBdir_inherit\fR
 545 .RE
 546 
 547 .sp
 548 .ne 2
 549 .na
 550 \fB\fBf\fR\fR
 551 .ad
 552 .RS 5n
 553 \fBfile_inherit\fR
 554 .RE
 555 
 556 .sp
 557 .ne 2
 558 .na
 559 \fB\fBF\fR\fR
 560 .ad
 561 .RS 5n
 562 failed access (not currently supported)
 563 .RE
 564 
 565 .sp
 566 .ne 2
 567 .na
 568 \fB\fBi\fR\fR
 569 .ad
 570 .RS 5n
 571 \fBinherit_only\fR
 572 .RE
 573 
 574 .sp
 575 .ne 2
 576 .na
 577 \fB\fBn\fR\fR
 578 .ad
 579 .RS 5n
 580 \fBno_propagate\fR
 581 .RE
 582 
 583 .sp
 584 .ne 2
 585 .na
 586 \fB\fBS\fR\fR
 587 .ad
 588 .RS 5n
 589 successful access (not currently supported)
 590 .RE
 591 
 592 .sp
 593 .LP
 594 The fifth field contains the type of the ACE (\fBallow\fR or \fBdeny\fR):
 595 .sp
 596 .ne 2
 597 .na
 598 \fB\fBallow\fR\fR
 599 .ad
 600 .RS 9n
 601 The mask specified in field three should be allowed.
 602 .RE
 603 
 604 .sp
 605 .ne 2
 606 .na
 607 \fB\fBdeny\fR\fR
 608 .ad
 609 .RS 9n
 610 The mask specified in field three should be denied.
 611 .RE
 612 
 613 .SH RETURN VALUES
 614 .sp
 615 .LP
 616 Upon successful completion, the \fBacl_totext()\fR function returns a pointer
 617 to a text string. Otherwise, it returns \fINULL\fR.
 618 .sp
 619 .LP
 620 Upon successful completion, the \fBacl_fromtext()\fR function returns 0.
 621 Otherwise, the return value is set to one of the following:
 622 .sp
 623 .ne 2
 624 .na
 625 \fB\fBEACL_FIELD_NOT_BLANK\fR\fR
 626 .ad
 627 .RS 28n
 628 A field that should be blank is not blank.
 629 .RE
 630 
 631 .sp
 632 .ne 2
 633 .na
 634 \fB\fBEACL_FLAGS_ERROR\fR\fR
 635 .ad
 636 .RS 28n
 637 An invalid ACL flag was specified.
 638 .RE
 639 
 640 .sp
 641 .ne 2
 642 .na
 643 \fB\fBEACL_INHERIT_ERROR\fR\fR
 644 .ad
 645 .RS 28n
 646 An invalid inheritance field was specified.
 647 .RE
 648 
 649 .sp
 650 .ne 2
 651 .na
 652 \fB\fBEACL_INVALID_ACCESS_TYPE\fR\fR
 653 .ad
 654 .RS 28n
 655 An invalid access type was specified.
 656 .RE
 657 
 658 .sp
 659 .ne 2
 660 .na
 661 \fB\fBEACL_INVALID_STR\fR\fR
 662 .ad
 663 .RS 28n
 664 The string is \fINULL\fR.
 665 .RE
 666 
 667 .sp
 668 .ne 2
 669 .na
 670 \fB\fBEACL_INVALID_USER_GROUP\fR\fR
 671 .ad
 672 .RS 28n
 673 The required user or group name not found.
 674 .RE
 675 
 676 .sp
 677 .ne 2
 678 .na
 679 \fB\fBEACL_MISSING_FIELDS\fR\fR
 680 .ad
 681 .RS 28n
 682 The ACL needs more fields to be specified.
 683 .RE
 684 
 685 .sp
 686 .ne 2
 687 .na
 688 \fB\fBEACL_PERM_MASK_ERROR\fR\fR
 689 .ad
 690 .RS 28n
 691 The permission mask is invalid.
 692 .RE
 693 
 694 .sp
 695 .ne 2
 696 .na
 697 \fB\fBEACL_UNKNOWN_DATA\fR\fR
 698 .ad
 699 .RS 28n
 700 Unknown data was found in the ACL.
 701 .RE
 702 
 703 .SH EXAMPLES
 704 .LP
 705 \fBExample 1 \fRExamples of permissions when \fBACL_COMPACT_FMT\fR is not
 706 specified.
 707 .sp
 708 .in +2
 709 .nf
 710 user:joe:read_data/write_data:file_inherit/dir_inherit:allow
 711 .fi
 712 .in -2
 713 .sp
 714 
 715 .sp
 716 .in +2
 717 .nf
 718 owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny
 719 .fi
 720 .in -2
 721 .sp
 722 
 723 .LP
 724 \fBExample 2 \fRExamples of permissions when \fBACL_COMPACT_FMT\fR is
 725 specified.
 726 .sp
 727 .in +2
 728 .nf
 729 user:joe:rw------------:fd----:allow
 730 .fi
 731 .in -2
 732 .sp
 733 
 734 .sp
 735 .in +2
 736 .nf
 737 owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny
 738 .fi
 739 .in -2
 740 .sp
 741 
 742 .SH ATTRIBUTES
 743 .sp
 744 .LP
 745 See \fBattributes\fR(5) for descriptions of the following attributes:
 746 .sp
 747 
 748 .sp
 749 .TS
 750 box;
 751 c | c
 752 l | l .
 753 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 754 _
 755 Interface Stability     Committed
 756 _
 757 MT-Level        Safe
 758 .TE
 759 
 760 .SH SEE ALSO
 761 .sp
 762 .LP
 763 \fBls\fR(1), \fBtar\fR(1), \fBacl\fR(2), \fBmalloc\fR(3C),
 764 \fBaclfromtext\fR(3SEC), \fBacl\fR(5), \fBattributes\fR(5)