1 '\" te
   2 .\" Copyright (c) 2001, Sun Microsystems, Inc.
   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 ACLTOTEXT 3SEC "Dec 10, 2001"
   7 .SH NAME
   8 acltotext, aclfromtext \- convert internal representation to or from external
   9 representation
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsec\fR [ \fIlibrary\fR... ]
  14 #include <sys/acl.h>
  15 
  16 \fBchar *\fR\fBacltotext\fR(\fBaclent_t *\fR\fIaclbufp\fR, \fBint\fR \fIaclcnt\fR);
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBaclent_t *\fR\fBaclfromtext\fR(\fBchar *\fR\fIacltextp\fR, \fBint *\fR\fIaclcnt\fR);
  22 .fi
  23 
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBacltotext()\fR function converts an internal \fBACL\fR representation
  28 pointed to by \fIaclbufp\fR into an external \fBACL\fR representation. The
  29 space for the external text string is obtained using \fBmalloc\fR(3C). The
  30 caller is responsible for freeing the space upon completion..
  31 .sp
  32 .LP
  33 The \fBaclfromtext()\fR function converts an external \fBACL\fR representation
  34 pointed to by \fIacltextp\fR into an internal \fBACL\fR representation.  The
  35 space for the list of \fBACL\fR entries is obtained using \fBmalloc\fR(3C). The
  36 caller is responsible for freeing the space upon completion. The \fIaclcnt\fR
  37 argument indicates the number of \fBACL\fR entries found.
  38 .sp
  39 .LP
  40 An external \fBACL\fR representation is defined as follows:
  41 .sp
  42 .LP
  43 <acl_entry>[,<acl_entry>]\|.\|.\|.
  44 .sp
  45 .LP
  46 Each <acl_entry> contains one \fBACL\fR entry. The external representation of
  47 an \fBACL\fR entry contains two or three colon-separated fields. The first
  48 field contains the \fBACL\fR entry tag type. The entry type keywords are
  49 defined as:
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBuser\fR\fR
  54 .ad
  55 .RS 17n
  56 This \fBACL\fR entry with no \fBUID\fR specified in the \fBACL\fR entry
  57 \fBID\fR field specifies the access granted to the owner of the object.
  58 Otherwise, this \fBACL\fR entry specifies the access granted to a specific
  59 user-name or user-id number.
  60 .RE
  61 
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBgroup\fR\fR
  66 .ad
  67 .RS 17n
  68 This \fBACL\fR entry with no \fBGID\fR specified in the \fBACL\fR entry
  69 \fBID\fR field specifies the access granted to the owning group of the object.
  70 Otherwise, this \fBACL\fR entry specifies the access granted to a specific
  71 group-name or group-id number.
  72 .RE
  73 
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBother\fR\fR
  78 .ad
  79 .RS 17n
  80 This \fBACL\fR entry specifies the access granted to any user or group that
  81 does not match any other \fBACL\fR entry.
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBmask\fR\fR
  88 .ad
  89 .RS 17n
  90 This \fBACL\fR entry specifies the maximum access granted to user or group
  91 entries.
  92 .RE
  93 
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBdefault:user\fR\fR
  98 .ad
  99 .RS 17n
 100 This \fBACL\fR entry with no uid specified in the \fBACL\fR entry \fBID\fR
 101 field specifies the default access granted to the owner of the object.
 102 Otherwise, this \fBACL\fR entry specifies the default access granted to a
 103 specific user-name or user-\fBID\fR number.
 104 .RE
 105 
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBdefault:group\fR\fR
 110 .ad
 111 .RS 17n
 112 This \fBACL\fR entry with no gid specified in the \fBACL\fR entry \fBID\fR
 113 field specifies the default access granted to the owning group of the object.
 114 Otherwise, this \fBACL\fR entry specifies the default access granted to a
 115 specific group-name or group-\fBID\fR number.
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBdefault:other\fR\fR
 122 .ad
 123 .RS 17n
 124 This \fBACL\fR entry specifies the default access for other entry.
 125 .RE
 126 
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBdefault:mask\fR\fR
 131 .ad
 132 .RS 17n
 133 This \fBACL\fR entry specifies the default access for mask entry.
 134 .RE
 135 
 136 .sp
 137 .LP
 138 The second field contains the \fBACL\fR entry \fBID\fR, as follows:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBuid\fR\fR
 143 .ad
 144 .RS 9n
 145 This field specifies a user-name, or user-\fBID\fR if there is no user-name
 146 associated with the user-\fBID\fR number.
 147 .RE
 148 
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBgid\fR\fR
 153 .ad
 154 .RS 9n
 155 This field specifies a group-name, or group-\fBID\fR if there is no group-name
 156 associated with the group-\fBID\fR number.
 157 .RE
 158 
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBempty\fR\fR
 163 .ad
 164 .RS 9n
 165 This field is used by the user and group \fBACL\fR entry types.
 166 .RE
 167 
 168 .sp
 169 .LP
 170 The third field contains the following symbolic discretionary access
 171 permissions:
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBr\fR\fR
 176 .ad
 177 .RS 9n
 178 read permission
 179 .RE
 180 
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBw\fR\fR
 185 .ad
 186 .RS 9n
 187 write permission
 188 .RE
 189 
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBx\fR\fR
 194 .ad
 195 .RS 9n
 196 execute/search permission
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fB\(mi\fR \fR
 203 .ad
 204 .RS 9n
 205 no access
 206 .RE
 207 
 208 .SH RETURN VALUES
 209 .sp
 210 .LP
 211 Upon successful completion, the \fBacltotext()\fR function returns a pointer to
 212 a text string. Otherwise, it returns \fBNULL\fR.
 213 .sp
 214 .LP
 215 Upon successful completion, the \fBaclfromtext()\fR function returns a pointer
 216 to a list of \fBACL\fR entries. Otherwise, it returns \fBNULL\fR.
 217 .SH ATTRIBUTES
 218 .sp
 219 .LP
 220 See \fBattributes\fR(5) for descriptions of the following attributes:
 221 .sp
 222 
 223 .sp
 224 .TS
 225 box;
 226 c | c
 227 l | l .
 228 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 229 _
 230 Interface Stability     Evolving
 231 _
 232 MT-Level        Unsafe
 233 .TE
 234 
 235 .SH SEE ALSO
 236 .sp
 237 .LP
 238 \fBacl\fR(2), \fBmalloc\fR(3C), \fBattributes\fR(5)