1 ACL_TOTEXT(3SEC) File Access Control Library Functions ACL_TOTEXT(3SEC) 2 3 4 5 NAME 6 acl_totext, acl_fromtext - convert internal representation to or from 7 external representation 8 9 SYNOPSIS 10 cc [ flag... ] file... -lsec [ library... ] 11 #include <sys/acl.h> 12 13 char *acl_totext(acl_t *aclp, int flags); 14 15 16 int acl_fromtext(char *acltextp, acl_t **aclp); 17 18 19 DESCRIPTION 20 The acl_totext() function converts an internal ACL representation 21 pointed to by aclp into an external ACL representation. The memory for 22 the external text string is obtained using malloc(3C). The caller is 23 responsible for freeing the memory upon completion. 24 25 26 The format of the external ACL is controlled by the flags argument. 27 Values for flags are constructed by a bitwise-inclusive-OR of flags 28 from the following list, defined in <sys/acl.h>. 29 30 ACL_COMPACT_FMT 31 For NFSv4 ACLs, the ACL entries will be formatted 32 using the compact ACL format detailed in ls(1) for 33 the -V option. 34 35 36 ACL_APPEND_ID 37 Append the uid or gid for additional user or group 38 entries. This flag is used to construct ACL entries 39 in a manner that is suitable for archive utilities 40 such as tar(1). When the ACL is translated from the 41 external format to internal representation using 42 acl_fromtext(), the appended ID will be used to 43 populate the uid or gid field of the ACL entry when 44 the user or group name does not exist on the host 45 system. The appended id will be ignored when the 46 user or group name does exist on the system. 47 48 49 ACL_SID_FMT 50 For NFSv4 ACLs, the ACL entries for user or group 51 entries will use the usersid or groupsid format when 52 the "id" field in the ACL entry is an ephemeral uid 53 or gid. The raw sid format will only be used when 54 the "id" cannot be resolved to a windows name. 55 56 57 58 The acl_fromtext() function converts an external ACL representation 59 pointed to by acltextp into an internal ACL representation. The memory 60 for the list of ACL entries is obtained using malloc(3C). The caller is 61 responsible for freeing the memory upon completion. Depending on type 62 of ACLs a file system supports, one of two external external 63 representations are possible. For POSIX draft file systems such as ufs, 64 the external representation is described in acltotext(3SEC). The 65 external ACL representation For NFSv4-style ACLs is detailed as 66 follows. 67 68 69 Each acl_entry contains one ACL entry. The external representation of 70 an ACL entry contains three, four or five colon separated fields. The 71 first field contains the ACL entry type. The entry type keywords are 72 defined as: 73 74 everyone@ 75 This ACL entry specifies the access granted to any user or 76 group that does not match any previous ACL entry. 77 78 79 group 80 This ACL entry with a GID specifies the access granted to 81 a additional group of the object. 82 83 84 group@ 85 This ACL entry with no GID specified in the ACL entry 86 field specifies the access granted to the owning group of 87 the object. 88 89 90 groupsid 91 This ACL entry with a SID or Windows name specifies the 92 access granted to a Windows group. This type of entry is 93 for a CIFS server created file. 94 95 96 owner@ 97 This ACL entry with no UID specified in the ACL entry 98 field specifies the access granted to the owner of the 99 object. 100 101 102 sid 103 This ACL entry with a SID or Windows name when the entry 104 could be either a group or a user. 105 106 107 user 108 This ACL entry with a UID specifies the access granted to 109 a additional user of the object. 110 111 112 usersid 113 This ACL entry with a SID or Windows name specifies the 114 access granted to a Windows user. This type of entry is 115 for a CIFS server created file. 116 117 118 119 The second field contains the ACL entry ID, and is used only for user 120 or group ACL entries. This field is not used for owner@, group@, or 121 everyone@ entries. 122 123 uid 124 This field contains a user-name or user-ID. If the user-name 125 cannot be resolved to a UID, then the entry is assumed to be a 126 numeric UID. 127 128 129 gid 130 This field contains a group-name or group-ID. If the group-name 131 can't be resolved to a GID, then the entry is assumed to be a 132 numeric GID. 133 134 135 136 The third field contains the discretionary access permissions. The 137 format of the permissions depends on whether ACL_COMPACT_FMT is 138 specified. When the flags field does not request ACL_COMPACT_FMT, the 139 following format is used with a forward slash (/) separating the 140 permissions. 141 142 add_file 143 Add a file to a directory. 144 145 146 add_subdirectory 147 Add a subdirectory. 148 149 150 append 151 Append data. 152 153 154 delete 155 Delete. 156 157 158 delete_child 159 Delete child. 160 161 162 execute 163 Execute permission. 164 165 166 list_directory 167 List a directory. 168 169 170 read_acl 171 Read ACL. 172 173 174 read_data 175 Read permission. 176 177 178 read_attributes 179 Read attributes. 180 181 182 read_xattr 183 Read named attributes. 184 185 186 synchronize 187 Synchronize. 188 189 190 write_acl 191 Write ACL. 192 193 194 write_attributes 195 Write attributes. 196 197 198 write_data 199 Write permission. 200 201 202 write_owner 203 Write owner. 204 205 206 write_xattr 207 Write named attributes. 208 209 210 211 This format allows permissions to be specified as, for example: 212 read_data/read_xattr/read_attributes. 213 214 215 When ACL_COMPACT_FMT is specified, the permissions consist of 14 unique 216 letters. A hyphen (-) character is used to indicate that the 217 permission at that position is not specified. 218 219 a 220 read attributes 221 222 223 A 224 write attributes 225 226 227 c 228 read ACL 229 230 231 C 232 write ACL 233 234 235 d 236 delete 237 238 239 D 240 delete child 241 242 243 o 244 write owner 245 246 247 p 248 append 249 250 251 r 252 read_data 253 254 255 R 256 read named attributes 257 258 259 s 260 synchronize 261 262 263 w 264 write_data 265 266 267 W 268 write named attributes 269 270 271 x 272 execute 273 274 275 276 This format allows compact permissions to be represented as, for 277 example: rw--d-a------- 278 279 280 The fourth field is optional when ACL_COMPACT_FMT is not specified, in 281 which case the field will be present only when the ACL entry has 282 inheritance flags set. The following is the list of inheritance flags 283 separated by a slash (/) character. 284 285 dir_inherit 286 ACE_DIRECTORY_INHERIT_ACE 287 288 289 file_inherit 290 ACE_FILE_INHERIT_ACE 291 292 293 inherit_only 294 ACE_INHERIT_ONLY_ACE 295 296 297 no_propagate 298 ACE_NO_PROPAGATE_INHERIT_ACE 299 300 301 302 When ACL_COMPACT_FMT is specified the inheritance will always be 303 present and is represented as positional arguments. A hyphen (-) 304 character is used to indicate that the inheritance flag at that 305 position is not specified. 306 307 d 308 dir_inherit 309 310 311 f 312 file_inherit 313 314 315 F 316 failed access (not currently supported) 317 318 319 i 320 inherit_only 321 322 323 n 324 no_propagate 325 326 327 S 328 successful access (not currently supported) 329 330 331 332 The fifth field contains the type of the ACE (allow or deny): 333 334 allow 335 The mask specified in field three should be allowed. 336 337 338 deny 339 The mask specified in field three should be denied. 340 341 342 RETURN VALUES 343 Upon successful completion, the acl_totext() function returns a pointer 344 to a text string. Otherwise, it returns NULL. 345 346 347 Upon successful completion, the acl_fromtext() function returns 0. 348 Otherwise, the return value is set to one of the following: 349 350 EACL_FIELD_NOT_BLANK 351 A field that should be blank is not blank. 352 353 354 EACL_FLAGS_ERROR 355 An invalid ACL flag was specified. 356 357 358 EACL_INHERIT_ERROR 359 An invalid inheritance field was specified. 360 361 362 EACL_INVALID_ACCESS_TYPE 363 An invalid access type was specified. 364 365 366 EACL_INVALID_STR 367 The string is NULL. 368 369 370 EACL_INVALID_USER_GROUP 371 The required user or group name not found. 372 373 374 EACL_MISSING_FIELDS 375 The ACL needs more fields to be specified. 376 377 378 EACL_PERM_MASK_ERROR 379 The permission mask is invalid. 380 381 382 EACL_UNKNOWN_DATA 383 Unknown data was found in the ACL. 384 385 386 EXAMPLES 387 Example 1 Examples of permissions when ACL_COMPACT_FMT is not 388 specified. 389 390 user:joe:read_data/write_data:file_inherit/dir_inherit:allow 391 392 393 394 owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny 395 396 397 398 Example 2 Examples of permissions when ACL_COMPACT_FMT is specified. 399 400 user:joe:rw------------:fd----:allow 401 402 403 404 owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny 405 406 407 408 ATTRIBUTES 409 See attributes(5) for descriptions of the following attributes: 410 411 412 413 414 +--------------------+-----------------+ 415 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 416 +--------------------+-----------------+ 417 |Interface Stability | Committed | 418 +--------------------+-----------------+ 419 |MT-Level | Safe | 420 +--------------------+-----------------+ 421 422 SEE ALSO 423 ls(1), tar(1), acl(2), malloc(3C), aclfromtext(3SEC), acl(5), 424 attributes(5) 425 426 427 428 June 16, 2008 ACL_TOTEXT(3SEC)