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