12288 getfacl and setfacl could stand improvement
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 construt 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)
--- EOF ---