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
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
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)
|
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
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
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)
|