12288 getfacl and setfacl could stand improvement
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
71 .LP
72 The \fBacl_fromtext()\fR function converts an external ACL representation
73 pointed to by \fIacltextp\fR into an internal ACL representation. The memory
74 for the list of ACL entries is obtained using \fBmalloc\fR(3C). The caller is
75 responsible for freeing the memory upon completion. Depending on type of ACLs a
76 file system supports, one of two external external representations are
77 possible. For POSIX draft file systems such as ufs, the external representation
78 is described in \fBacltotext\fR(3SEC). The external ACL representation For
79 NFSv4-style ACLs is detailed as follows.
80 .sp
81 .LP
82 Each \fBacl_entry\fR contains one ACL entry. The external representation of an
83 ACL entry contains three, four or five colon separated fields. The first field
84 contains the ACL entry type. The entry type keywords are defined as:
85 .sp
86 .ne 2
87 .na
88 \fB\fBeveryone@\fR\fR
89 .ad
90 .RS 13n
91 This ACL entry specifies the access granted to any user or group that does not
92 match any previous ACL entry.
93 .RE
94
95 .sp
96 .ne 2
97 .na
98 \fB\fBgroup\fR\fR
99 .ad
100 .RS 13n
101 This ACL entry with a GID specifies the access granted to a additional group of
102 the object.
103 .RE
104
105 .sp
106 .ne 2
107 .na
108 \fB\fBgroup@\fR\fR
109 .ad
110 .RS 13n
111 This ACL entry with no GID specified in the ACL entry field specifies the
112 access granted to the owning group of the object.
113 .RE
114
115 .sp
116 .ne 2
117 .na
118 \fB\fBgroupsid\fR\fR
119 .ad
120 .RS 13n
121 This ACL entry with a SID or Windows name specifies the access granted to a
122 Windows group. This type of entry is for a CIFS server created file.
123 .RE
124
125 .sp
126 .ne 2
127 .na
128 \fB\fBowner@\fR\fR
129 .ad
130 .RS 13n
131 This ACL entry with no UID specified in the ACL entry field specifies the
132 access granted to the owner of the object.
133 .RE
134
135 .sp
136 .ne 2
137 .na
138 \fB\fBsid\fR\fR
139 .ad
140 .RS 13n
141 This ACL entry with a SID or Windows name when the entry could be either a
142 group or a user.
143 .RE
144
145 .sp
146 .ne 2
147 .na
148 \fB\fBuser\fR\fR
149 .ad
150 .RS 13n
151 This ACL entry with a UID specifies the access granted to a additional user of
152 the object.
153 .RE
154
155 .sp
156 .ne 2
157 .na
158 \fB\fBusersid\fR\fR
159 .ad
160 .RS 13n
161 This ACL entry with a SID or Windows name specifies the access granted to a
162 Windows user. This type of entry is for a CIFS server created file.
163 .RE
164
165 .sp
166 .LP
167 The second field contains the ACL entry ID, and is used only for user or group
168 ACL entries. This field is not used for \fBowner@\fR, \fBgroup@\fR, or
169 \fBeveryone@\fR entries.
170 .sp
171 .ne 2
172 .na
173 \fB\fBuid\fR\fR
174 .ad
175 .RS 7n
176 This field contains a user-name or user-ID. If the user-name cannot be resolved
177 to a UID, then the entry is assumed to be a numeric UID.
178 .RE
179
180 .sp
181 .ne 2
182 .na
183 \fB\fBgid\fR\fR
184 .ad
185 .RS 7n
186 This field contains a group-name or group-ID. If the group-name can't be
187 resolved to a GID, then the entry is assumed to be a numeric GID.
188 .RE
189
190 .sp
191 .LP
192 The third field contains the discretionary access permissions. The format of
193 the permissions depends on whether \fBACL_COMPACT_FMT\fR is specified. When the
194 \fIflags\fR field does not request \fBACL_COMPACT_FMT\fR, the following format
195 is used with a forward slash (/) separating the permissions.
196 .sp
197 .ne 2
198 .na
199 \fB\fBadd_file\fR\fR
200 .ad
201 .RS 20n
202 Add a file to a directory.
203 .RE
204
205 .sp
206 .ne 2
207 .na
208 \fB\fBadd_subdirectory\fR\fR
209 .ad
210 .RS 20n
211 Add a subdirectory.
212 .RE
213
214 .sp
215 .ne 2
216 .na
217 \fB\fBappend\fR\fR
218 .ad
219 .RS 20n
220 Append data.
221 .RE
222
223 .sp
224 .ne 2
225 .na
226 \fB\fBdelete\fR\fR
227 .ad
228 .RS 20n
229 Delete.
230 .RE
231
232 .sp
233 .ne 2
234 .na
235 \fB\fBdelete_child\fR\fR
236 .ad
237 .RS 20n
238 Delete child.
239 .RE
240
241 .sp
242 .ne 2
243 .na
244 \fB\fBexecute\fR\fR
245 .ad
246 .RS 20n
247 Execute permission.
248 .RE
249
250 .sp
251 .ne 2
252 .na
253 \fB\fBlist_directory\fR\fR
254 .ad
255 .RS 20n
256 List a directory.
257 .RE
258
259 .sp
260 .ne 2
261 .na
262 \fB\fBread_acl\fR\fR
263 .ad
264 .RS 20n
265 Read ACL.
266 .RE
267
268 .sp
269 .ne 2
270 .na
271 \fB\fBread_data\fR\fR
272 .ad
273 .RS 20n
274 Read permission.
275 .RE
276
277 .sp
278 .ne 2
279 .na
280 \fB\fBread_attributes\fR\fR
281 .ad
282 .RS 20n
283 Read attributes.
284 .RE
285
286 .sp
287 .ne 2
288 .na
289 \fB\fBread_xattr\fR\fR
290 .ad
291 .RS 20n
292 Read named attributes.
293 .RE
294
295 .sp
296 .ne 2
297 .na
298 \fB\fBsynchronize\fR\fR
299 .ad
300 .RS 20n
301 Synchronize.
302 .RE
303
304 .sp
305 .ne 2
306 .na
307 \fB\fBwrite_acl\fR\fR
308 .ad
309 .RS 20n
310 Write ACL.
311 .RE
312
313 .sp
314 .ne 2
315 .na
316 \fB\fBwrite_attributes\fR\fR
317 .ad
318 .RS 20n
319 Write attributes.
320 .RE
321
322 .sp
323 .ne 2
324 .na
325 \fB\fBwrite_data\fR\fR
326 .ad
327 .RS 20n
328 Write permission.
329 .RE
330
331 .sp
332 .ne 2
333 .na
334 \fB\fBwrite_owner\fR\fR
335 .ad
336 .RS 20n
337 Write owner.
338 .RE
339
340 .sp
341 .ne 2
342 .na
343 \fB\fBwrite_xattr\fR\fR
344 .ad
345 .RS 20n
346 Write named attributes.
347 .RE
348
349 .sp
350 .LP
351 This format allows permissions to be specified as, for example:
352 \fBread_data\fR/\fBread_xattr\fR/\fBread_attributes\fR.
353 .sp
354 .LP
355 When \fBACL_COMPACT_FMT\fR is specified, the permissions consist of 14 unique
356 letters. A hyphen (-) character is used to indicate that the permission at
357 that position is not specified.
358 .sp
359 .ne 2
360 .na
361 \fB\fBa\fR\fR
362 .ad
363 .RS 5n
364 read attributes
365 .RE
366
367 .sp
368 .ne 2
369 .na
370 \fB\fBA\fR\fR
371 .ad
372 .RS 5n
373 write attributes
374 .RE
375
376 .sp
377 .ne 2
378 .na
379 \fB\fBc\fR\fR
380 .ad
381 .RS 5n
382 read ACL
383 .RE
384
385 .sp
386 .ne 2
387 .na
388 \fB\fBC\fR\fR
389 .ad
390 .RS 5n
391 write ACL
392 .RE
393
394 .sp
395 .ne 2
396 .na
397 \fB\fBd\fR\fR
398 .ad
399 .RS 5n
400 delete
401 .RE
402
403 .sp
404 .ne 2
405 .na
406 \fB\fBD\fR\fR
407 .ad
408 .RS 5n
409 delete child
410 .RE
411
412 .sp
413 .ne 2
414 .na
415 \fB\fBo\fR\fR
416 .ad
417 .RS 5n
418 write owner
419 .RE
420
421 .sp
422 .ne 2
423 .na
424 \fB\fBp\fR\fR
425 .ad
426 .RS 5n
427 append
428 .RE
429
430 .sp
431 .ne 2
432 .na
433 \fB\fBr\fR\fR
434 .ad
435 .RS 5n
436 read_data
437 .RE
438
439 .sp
440 .ne 2
441 .na
442 \fB\fBR\fR\fR
443 .ad
444 .RS 5n
445 read named attributes
446 .RE
447
448 .sp
449 .ne 2
450 .na
451 \fB\fBs\fR\fR
452 .ad
453 .RS 5n
454 synchronize
455 .RE
456
457 .sp
458 .ne 2
459 .na
460 \fB\fBw\fR\fR
461 .ad
462 .RS 5n
463 write_data
464 .RE
465
466 .sp
467 .ne 2
468 .na
469 \fB\fBW\fR\fR
470 .ad
471 .RS 5n
472 write named attributes
473 .RE
474
475 .sp
476 .ne 2
477 .na
478 \fB\fBx\fR\fR
479 .ad
480 .RS 5n
481 execute
482 .RE
483
484 .sp
485 .LP
486 This format allows compact permissions to be represented as, for example:
487 \fBrw--d-a-------\fR
488 .sp
489 .LP
490 The fourth field is optional when \fBACL_COMPACT_FMT\fR is not specified, in
491 which case the field will be present only when the ACL entry has inheritance
492 flags set. The following is the list of inheritance flags separated by a slash
493 (/) character.
494 .sp
495 .ne 2
496 .na
497 \fB\fBdir_inherit\fR\fR
498 .ad
499 .RS 16n
500 \fBACE_DIRECTORY_INHERIT_ACE\fR
501 .RE
502
503 .sp
504 .ne 2
505 .na
506 \fB\fBfile_inherit\fR\fR
507 .ad
508 .RS 16n
509 \fBACE_FILE_INHERIT_ACE\fR
510 .RE
511
512 .sp
513 .ne 2
514 .na
515 \fB\fBinherit_only\fR\fR
516 .ad
517 .RS 16n
518 \fBACE_INHERIT_ONLY_ACE\fR
519 .RE
520
521 .sp
522 .ne 2
523 .na
524 \fB\fBno_propagate\fR\fR
525 .ad
526 .RS 16n
527 \fBACE_NO_PROPAGATE_INHERIT_ACE\fR
528 .RE
529
530 .sp
531 .LP
532 When \fBACL_COMPACT_FMT\fR is specified the inheritance will always be present
533 and is represented as positional arguments. A hyphen (-) character is used to
534 indicate that the inheritance flag at that position is not specified.
535 .sp
536 .ne 2
537 .na
538 \fB\fBd\fR\fR
539 .ad
540 .RS 5n
541 \fBdir_inherit\fR
542 .RE
543
544 .sp
545 .ne 2
546 .na
547 \fB\fBf\fR\fR
548 .ad
549 .RS 5n
550 \fBfile_inherit\fR
551 .RE
552
553 .sp
554 .ne 2
555 .na
556 \fB\fBF\fR\fR
557 .ad
558 .RS 5n
559 failed access (not currently supported)
560 .RE
561
562 .sp
563 .ne 2
564 .na
565 \fB\fBi\fR\fR
566 .ad
567 .RS 5n
568 \fBinherit_only\fR
569 .RE
570
571 .sp
572 .ne 2
573 .na
574 \fB\fBn\fR\fR
575 .ad
576 .RS 5n
577 \fBno_propagate\fR
578 .RE
579
580 .sp
581 .ne 2
582 .na
583 \fB\fBS\fR\fR
584 .ad
585 .RS 5n
586 successful access (not currently supported)
587 .RE
588
589 .sp
590 .LP
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
631 .RS 28n
632 An invalid ACL flag was specified.
633 .RE
634
635 .sp
636 .ne 2
637 .na
638 \fB\fBEACL_INHERIT_ERROR\fR\fR
639 .ad
640 .RS 28n
641 An invalid inheritance field was specified.
642 .RE
643
644 .sp
645 .ne 2
646 .na
647 \fB\fBEACL_INVALID_ACCESS_TYPE\fR\fR
648 .ad
649 .RS 28n
650 An invalid access type was specified.
651 .RE
652
653 .sp
654 .ne 2
655 .na
656 \fB\fBEACL_INVALID_STR\fR\fR
657 .ad
658 .RS 28n
659 The string is \fINULL\fR.
660 .RE
661
662 .sp
663 .ne 2
664 .na
665 \fB\fBEACL_INVALID_USER_GROUP\fR\fR
666 .ad
667 .RS 28n
668 The required user or group name not found.
669 .RE
670
671 .sp
672 .ne 2
673 .na
674 \fB\fBEACL_MISSING_FIELDS\fR\fR
675 .ad
676 .RS 28n
677 The ACL needs more fields to be specified.
678 .RE
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)
--- EOF ---