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)