1acl_totext(3SEC) File Access Control Library Functions acl_totext(3SEC)
2
6 acl_totext, acl_fromtext - convert internal representation to or from
7 external representation
8
10 cc [ flag... ] file... -lsec [ library... ]
11 #include <sys/acl.h>
12 char *acl_totext(acl_t *aclp, int flags);
14 int acl_fromtext(char *acltextp, acl_t **aclp);
17
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 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 ACL_COMPACT_FMT For NFSv4 ACLs, the ACL entries will be formatted
31 using the compact ACL format detailed in ls(1) for
32 the -V option.
33 ACL_APPEND_ID Append the uid or gid for additional user or group
36 entries. This flag is used to construt ACL entries
37 in a manner that is suitable for archive utilities
38 such as tar(1). When the ACL is translated from the
39 external format to internal representation using
40 acl_fromtext(), the appended ID will be used to pop‐
41 ulate the uid or gid field of the ACL entry when the
42 user or group name does not exist on the host sys‐
43 tem. The appended id will be ignored when the user
44 or group name does exist on the system.
45 ACL_SID_FMT For NFSv4 ACLs, the ACL entries for user or group
48 entries will use the usersid or groupsid format when
49 the "id" field in the ACL entry is an ephemeral uid
50 or gid. The raw sid format will only be used when
51 the "id" cannot be resolved to a windows name.
52 The acl_fromtext() function converts an external ACL representation
56 pointed to by acltextp into an internal ACL representation. The memory
57 for the list of ACL entries is obtained using malloc(3C). The caller is
58 responsible for freeing the memory upon completion. Depending on type
59 of ACLs a file system supports, one of two external external represen‐
60 tations are possible. For POSIX draft file systems such as ufs, the
61 external representation is described in acltotext(3SEC). The external
62 ACL representation For NFSv4-style ACLs is detailed as follows.
63 Each acl_entry contains one ACL entry. The external representation of
66 an ACL entry contains three, four or five colon separated fields. The
67 first field contains the ACL entry type. The entry type keywords are
68 defined as:
69 everyone@ This ACL entry specifies the access granted to any user or
71 group that does not match any previous ACL entry.
72 group This ACL entry with a GID specifies the access granted to
75 a additional group of the object.
76 group@ This ACL entry with no GID specified in the ACL entry
79 field specifies the access granted to the owning group of
80 the object.
81 groupsid This ACL entry with a SID or Windows name specifies the
84 access granted to a Windows group. This type of entry is
85 for a CIFS server created file.
86 owner@ This ACL entry with no UID specified in the ACL entry
89 field specifies the access granted to the owner of the
90 object.
91 sid This ACL entry with a SID or Windows name when the entry
94 could be either a group or a user.
95 user This ACL entry with a UID specifies the access granted to
98 a additional user of the object.
99 usersid This ACL entry with a SID or Windows name specifies the
102 access granted to a Windows user. This type of entry is
103 for a CIFS server created file.
104 The second field contains the ACL entry ID, and is used only for user
108 or group ACL entries. This field is not used for owner@, group@, or
109 everyone@ entries.
110 uid This field contains a user-name or user-ID. If the user-name
112 cannot be resolved to a UID, then the entry is assumed to be a
113 numeric UID.
114 gid This field contains a group-name or group-ID. If the group-name
117 can't be resolved to a GID, then the entry is assumed to be a
118 numeric GID.
119 The third field contains the discretionary access permissions. The for‐
123 mat of the permissions depends on whether ACL_COMPACT_FMT is specified.
124 When the flags field does not request ACL_COMPACT_FMT, the following
125 format is used with a forward slash (/) separating the permissions.
126 add_file Add a file to a directory.
128 add_subdirectory Add a subdirectory.
131 append Append data.
134 delete Delete.
137 delete_child Delete child.
140 execute Execute permission.
143 list_directory List a directory.
146 read_acl Read ACL.
149 read_data Read permission.
152 read_attributes Read attributes.
155 read_xattr Read named attributes.
158 synchronize Synchronize.
161 write_acl Write ACL.
164 write_attributes Write attributes.
167 write_data Write permission.
170 write_owner Write owner.
173 write_xattr Write named attributes.
176 This format allows permissions to be specified as, for example:
180 read_data/read_xattr/read_attributes.
181 When ACL_COMPACT_FMT is specified, the permissions consist of 14 unique
184 letters. A hyphen (-) character is used to indicate that the permis‐
185 sion at that position is not specified.
186 a read attributes
188 A write attributes
191 c read ACL
194 C write ACL
197 d delete
200 D delete child
203 o write owner
206 p append
209 r read_data
212 R read named attributes
215 s synchronize
218 w write_data
221 W write named attributes
224 x execute
227 This format allows compact permissions to be represented as, for exam‐
231 ple: rw--d-a-------
232 The fourth field is optional when ACL_COMPACT_FMT is not specified, in
235 which case the field will be present only when the ACL entry has inher‐
236 itance flags set. The following is the list of inheritance flags sepa‐
237 rated by a slash (/) character.
238 dir_inherit ACE_DIRECTORY_INHERIT_ACE
240 file_inherit ACE_FILE_INHERIT_ACE
243 inherit_only ACE_INHERIT_ONLY_ACE
246 no_propagate ACE_NO_PROPAGATE_INHERIT_ACE
249 When ACL_COMPACT_FMT is specified the inheritance will always be
253 present and is represented as positional arguments. A hyphen (-) char‐
254 acter is used to indicate that the inheritance flag at that position is
255 not specified.
256 d dir_inherit
258 f file_inherit
261 F failed access (not currently supported)
264 i inherit_only
267 n no_propagate
270 S successful access (not currently supported)
273 The fifth field contains the type of the ACE (allow or deny):
277 allow The mask specified in field three should be allowed.
279 deny The mask specified in field three should be denied.
282
285 Upon successful completion, the acl_totext() function returns a pointer
286 to a text string. Otherwise, it returns NULL.
287 Upon successful completion, the acl_fromtext() function returns 0. Oth‐
290 erwise, the return value is set to one of the following:
291 EACL_FIELD_NOT_BLANK A field that should be blank is not blank.
293 EACL_FLAGS_ERROR An invalid ACL flag was specified.
296 EACL_INHERIT_ERROR An invalid inheritance field was specified.
299 EACL_INVALID_ACCESS_TYPE An invalid access type was specified.
302 EACL_INVALID_STR The string is NULL.
305 EACL_INVALID_USER_GROUP The required user or group name not found.
308 EACL_MISSING_FIELDS The ACL needs more fields to be specified.
311 EACL_PERM_MASK_ERROR The permission mask is invalid.
314 EACL_UNKNOWN_DATA Unknown data was found in the ACL.
317
320 Example 1 Examples of permissions when ACL_COMPACT_FMT is not speci‐
321 fied.
322 user:joe:read_data/write_data:file_inherit/dir_inherit:allow
324 owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny
328 Example 2 Examples of permissions when ACL_COMPACT_FMT is specified.
332 user:joe:rw------------:fd----:allow
334 owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny
338
342 See attributes(5) for descriptions of the following attributes:
343 ┌─────────────────────────────┬─────────────────────────────┐
348 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
349 ├─────────────────────────────┼─────────────────────────────┤
350 │Interface Stability │Committed │
351 ├─────────────────────────────┼─────────────────────────────┤
352 │MT-Level │Safe │
353 └─────────────────────────────┴─────────────────────────────┘
354
356 ls(1), tar(1), acl(2), malloc(3C), aclfromtext(3SEC), acl(5),
357 attributes(5)
358SunOS 5.11 16 Jun 2008 acl_totext(3SEC)