| blob | 6e55c2323c0f8d364ad5c3e42df2b1edca5ec75e |
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 .LP
12 .nf
13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lsec\fR [ \fIlibrary\fR\&.\|.\|. ]
14 #include <sys/acl.h>
16 \fBchar *\fR\fBacl_totext\fR(\fBacl_t *\fR\fIaclp\fR, \fBint\fR \fIflags\fR);
17 .fi
19 .LP
20 .nf
21 \fBint\fR \fBacl_fromtext\fR(\fBchar *\fR\fIacltextp\fR, \fBacl_t **\fR\fIaclp\fR);
22 .fi
24 .SH DESCRIPTION
25 .sp
26 .LP
27 The \fBacl_totext()\fR function converts an internal ACL representation pointed
28 to by \fIaclp\fR into an external ACL representation. The memory for the
29 external text string is obtained using \fBmalloc\fR(3C). The caller is
30 responsible for freeing the memory upon completion.
31 .sp
32 .LP
33 The format of the external ACL is controlled by the \fIflags\fR argument.
34 Values for \fIflags\fR are constructed by a bitwise-inclusive-OR of \fIflags\fR
35 from the following list, defined in <\fBsys/acl.h\fR>.
36 .sp
37 .ne 2
38 .na
39 \fB\fBACL_COMPACT_FMT\fR\fR
40 .ad
41 .RS 19n
42 For NFSv4 ACLs, the ACL entries will be formatted using the compact ACL format
43 detailed in \fBls\fR(1) for the \fB-V\fR option.
44 .RE
46 .sp
47 .ne 2
48 .na
49 \fB\fBACL_APPEND_ID\fR\fR
50 .ad
51 .RS 19n
52 Append the \fBuid\fR or \fBgid\fR for additional user or group entries. This
53 flag is used to construt ACL entries in a manner that is suitable for archive
54 utilities such as \fBtar\fR(1). When the ACL is translated from the external
55 format to internal representation using \fBacl_fromtext()\fR, the appended ID
56 will be used to populate the \fBuid\fR or \fBgid\fR field of the ACL entry when
57 the user or group name does not exist on the host system. The appended id will
58 be ignored when the user or group name does exist on the system.
59 .RE
61 .sp
62 .ne 2
63 .na
64 \fB\fBACL_SID_FMT\fR\fR
65 .ad
66 .RS 19n
67 For NFSv4 ACLs, the ACL entries for user or group entries will use the
68 \fBusersid\fR or \fBgroupsid\fR format when the "id" field in the ACL entry is
69 an ephemeral \fBuid\fR or \fBgid\fR. The raw \fBsid\fR format will only be
70 used when the "id" cannot be resolved to a windows name.
71 .RE
73 .sp
74 .LP
75 The \fBacl_fromtext()\fR function converts an external ACL representation
76 pointed to by \fIacltextp\fR into an internal ACL representation. The memory
77 for the list of ACL entries is obtained using \fBmalloc\fR(3C). The caller is
78 responsible for freeing the memory upon completion. Depending on type of ACLs a
79 file system supports, one of two external external representations are
80 possible. For POSIX draft file systems such as ufs, the external representation
81 is described in \fBacltotext\fR(3SEC). The external ACL representation For
82 NFSv4-style ACLs is detailed as follows.
83 .sp
84 .LP
85 Each \fBacl_entry\fR contains one ACL entry. The external representation of an
86 ACL entry contains three, four or five colon separated fields. The first field
87 contains the ACL entry type. The entry type keywords are defined as:
88 .sp
89 .ne 2
90 .na
91 \fB\fBeveryone@\fR\fR
92 .ad
93 .RS 13n
94 This ACL entry specifies the access granted to any user or group that does not
95 match any previous ACL entry.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fBgroup\fR\fR
102 .ad
103 .RS 13n
104 This ACL entry with a GID specifies the access granted to a additional group of
105 the object.
106 .RE
108 .sp
109 .ne 2
110 .na
111 \fB\fBgroup@\fR\fR
112 .ad
113 .RS 13n
114 This ACL entry with no GID specified in the ACL entry field specifies the
115 access granted to the owning group of the object.
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB\fBgroupsid\fR\fR
122 .ad
123 .RS 13n
124 This ACL entry with a SID or Windows name specifies the access granted to a
125 Windows group. This type of entry is for a CIFS server created file.
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB\fBowner@\fR\fR
132 .ad
133 .RS 13n
134 This ACL entry with no UID specified in the ACL entry field specifies the
135 access granted to the owner of the object.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBsid\fR\fR
142 .ad
143 .RS 13n
144 This ACL entry with a SID or Windows name when the entry could be either a
145 group or a user.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fBuser\fR\fR
152 .ad
153 .RS 13n
154 This ACL entry with a UID specifies the access granted to a additional user of
155 the object.
156 .RE
158 .sp
159 .ne 2
160 .na
161 \fB\fBusersid\fR\fR
162 .ad
163 .RS 13n
164 This ACL entry with a SID or Windows name specifies the access granted to a
165 Windows user. This type of entry is for a CIFS server created file.
166 .RE
168 .sp
169 .LP
170 The second field contains the ACL entry ID, and is used only for user or group
171 ACL entries. This field is not used for \fBowner@\fR, \fBgroup@\fR, or
172 \fBeveryone@\fR entries.
173 .sp
174 .ne 2
175 .na
176 \fB\fBuid\fR\fR
177 .ad
178 .RS 7n
179 This field contains a user-name or user-ID. If the user-name cannot be resolved
180 to a UID, then the entry is assumed to be a numeric UID.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fBgid\fR\fR
187 .ad
188 .RS 7n
189 This field contains a group-name or group-ID. If the group-name can't be
190 resolved to a GID, then the entry is assumed to be a numeric GID.
191 .RE
193 .sp
194 .LP
195 The third field contains the discretionary access permissions. The format of
196 the permissions depends on whether \fBACL_COMPACT_FMT\fR is specified. When the
197 \fIflags\fR field does not request \fBACL_COMPACT_FMT\fR, the following format
198 is used with a forward slash (/) separating the permissions.
199 .sp
200 .ne 2
201 .na
202 \fB\fBadd_file\fR\fR
203 .ad
204 .RS 20n
205 Add a file to a directory.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fBadd_subdirectory\fR\fR
212 .ad
213 .RS 20n
214 Add a subdirectory.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBappend\fR\fR
221 .ad
222 .RS 20n
223 Append data.
224 .RE
226 .sp
227 .ne 2
228 .na
229 \fB\fBdelete\fR\fR
230 .ad
231 .RS 20n
232 Delete.
233 .RE
235 .sp
236 .ne 2
237 .na
238 \fB\fBdelete_child\fR\fR
239 .ad
240 .RS 20n
241 Delete child.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fBexecute\fR\fR
248 .ad
249 .RS 20n
250 Execute permission.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBlist_directory\fR\fR
257 .ad
258 .RS 20n
259 List a directory.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBread_acl\fR\fR
266 .ad
267 .RS 20n
268 Read ACL.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBread_data\fR\fR
275 .ad
276 .RS 20n
277 Read permission.
278 .RE
280 .sp
281 .ne 2
282 .na
283 \fB\fBread_attributes\fR\fR
284 .ad
285 .RS 20n
286 Read attributes.
287 .RE
289 .sp
290 .ne 2
291 .na
292 \fB\fBread_xattr\fR\fR
293 .ad
294 .RS 20n
295 Read named attributes.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fBsynchronize\fR\fR
302 .ad
303 .RS 20n
304 Synchronize.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fBwrite_acl\fR\fR
311 .ad
312 .RS 20n
313 Write ACL.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fBwrite_attributes\fR\fR
320 .ad
321 .RS 20n
322 Write attributes.
323 .RE
325 .sp
326 .ne 2
327 .na
328 \fB\fBwrite_data\fR\fR
329 .ad
330 .RS 20n
331 Write permission.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fBwrite_owner\fR\fR
338 .ad
339 .RS 20n
340 Write owner.
341 .RE
343 .sp
344 .ne 2
345 .na
346 \fB\fBwrite_xattr\fR\fR
347 .ad
348 .RS 20n
349 Write named attributes.
350 .RE
352 .sp
353 .LP
354 This format allows permissions to be specified as, for example:
355 \fBread_data\fR/\fBread_xattr\fR/\fBread_attributes\fR.
356 .sp
357 .LP
358 When \fBACL_COMPACT_FMT\fR is specified, the permissions consist of 14 unique
359 letters. A hyphen (-) character is used to indicate that the permission at
360 that position is not specified.
361 .sp
362 .ne 2
363 .na
364 \fB\fBa\fR\fR
365 .ad
366 .RS 5n
367 read attributes
368 .RE
370 .sp
371 .ne 2
372 .na
373 \fB\fBA\fR\fR
374 .ad
375 .RS 5n
376 write attributes
377 .RE
379 .sp
380 .ne 2
381 .na
382 \fB\fBc\fR\fR
383 .ad
384 .RS 5n
385 read ACL
386 .RE
388 .sp
389 .ne 2
390 .na
391 \fB\fBC\fR\fR
392 .ad
393 .RS 5n
394 write ACL
395 .RE
397 .sp
398 .ne 2
399 .na
400 \fB\fBd\fR\fR
401 .ad
402 .RS 5n
403 delete
404 .RE
406 .sp
407 .ne 2
408 .na
409 \fB\fBD\fR\fR
410 .ad
411 .RS 5n
412 delete child
413 .RE
415 .sp
416 .ne 2
417 .na
418 \fB\fBo\fR\fR
419 .ad
420 .RS 5n
421 write owner
422 .RE
424 .sp
425 .ne 2
426 .na
427 \fB\fBp\fR\fR
428 .ad
429 .RS 5n
430 append
431 .RE
433 .sp
434 .ne 2
435 .na
436 \fB\fBr\fR\fR
437 .ad
438 .RS 5n
439 read_data
440 .RE
442 .sp
443 .ne 2
444 .na
445 \fB\fBR\fR\fR
446 .ad
447 .RS 5n
448 read named attributes
449 .RE
451 .sp
452 .ne 2
453 .na
454 \fB\fBs\fR\fR
455 .ad
456 .RS 5n
457 synchronize
458 .RE
460 .sp
461 .ne 2
462 .na
463 \fB\fBw\fR\fR
464 .ad
465 .RS 5n
466 write_data
467 .RE
469 .sp
470 .ne 2
471 .na
472 \fB\fBW\fR\fR
473 .ad
474 .RS 5n
475 write named attributes
476 .RE
478 .sp
479 .ne 2
480 .na
481 \fB\fBx\fR\fR
482 .ad
483 .RS 5n
484 execute
485 .RE
487 .sp
488 .LP
489 This format allows compact permissions to be represented as, for example:
490 \fBrw--d-a-------\fR
491 .sp
492 .LP
493 The fourth field is optional when \fBACL_COMPACT_FMT\fR is not specified, in
494 which case the field will be present only when the ACL entry has inheritance
495 flags set. The following is the list of inheritance flags separated by a slash
496 (/) character.
497 .sp
498 .ne 2
499 .na
500 \fB\fBdir_inherit\fR\fR
501 .ad
502 .RS 16n
503 \fBACE_DIRECTORY_INHERIT_ACE\fR
504 .RE
506 .sp
507 .ne 2
508 .na
509 \fB\fBfile_inherit\fR\fR
510 .ad
511 .RS 16n
512 \fBACE_FILE_INHERIT_ACE\fR
513 .RE
515 .sp
516 .ne 2
517 .na
518 \fB\fBinherit_only\fR\fR
519 .ad
520 .RS 16n
521 \fBACE_INHERIT_ONLY_ACE\fR
522 .RE
524 .sp
525 .ne 2
526 .na
527 \fB\fBno_propagate\fR\fR
528 .ad
529 .RS 16n
530 \fBACE_NO_PROPAGATE_INHERIT_ACE\fR
531 .RE
533 .sp
534 .LP
535 When \fBACL_COMPACT_FMT\fR is specified the inheritance will always be present
536 and is represented as positional arguments. A hyphen (-) character is used to
537 indicate that the inheritance flag at that position is not specified.
538 .sp
539 .ne 2
540 .na
541 \fB\fBd\fR\fR
542 .ad
543 .RS 5n
544 \fBdir_inherit\fR
545 .RE
547 .sp
548 .ne 2
549 .na
550 \fB\fBf\fR\fR
551 .ad
552 .RS 5n
553 \fBfile_inherit\fR
554 .RE
556 .sp
557 .ne 2
558 .na
559 \fB\fBF\fR\fR
560 .ad
561 .RS 5n
562 failed access (not currently supported)
563 .RE
565 .sp
566 .ne 2
567 .na
568 \fB\fBi\fR\fR
569 .ad
570 .RS 5n
571 \fBinherit_only\fR
572 .RE
574 .sp
575 .ne 2
576 .na
577 \fB\fBn\fR\fR
578 .ad
579 .RS 5n
580 \fBno_propagate\fR
581 .RE
583 .sp
584 .ne 2
585 .na
586 \fB\fBS\fR\fR
587 .ad
588 .RS 5n
589 successful access (not currently supported)
590 .RE
592 .sp
593 .LP
594 The fifth field contains the type of the ACE (\fBallow\fR or \fBdeny\fR):
595 .sp
596 .ne 2
597 .na
598 \fB\fBallow\fR\fR
599 .ad
600 .RS 9n
601 The mask specified in field three should be allowed.
602 .RE
604 .sp
605 .ne 2
606 .na
607 \fB\fBdeny\fR\fR
608 .ad
609 .RS 9n
610 The mask specified in field three should be denied.
611 .RE
613 .SH RETURN VALUES
614 .sp
615 .LP
616 Upon successful completion, the \fBacl_totext()\fR function returns a pointer
617 to a text string. Otherwise, it returns \fINULL\fR.
618 .sp
619 .LP
620 Upon successful completion, the \fBacl_fromtext()\fR function returns 0.
621 Otherwise, the return value is set to one of the following:
622 .sp
623 .ne 2
624 .na
625 \fB\fBEACL_FIELD_NOT_BLANK\fR\fR
626 .ad
627 .RS 28n
628 A field that should be blank is not blank.
629 .RE
631 .sp
632 .ne 2
633 .na
634 \fB\fBEACL_FLAGS_ERROR\fR\fR
635 .ad
636 .RS 28n
637 An invalid ACL flag was specified.
638 .RE
640 .sp
641 .ne 2
642 .na
643 \fB\fBEACL_INHERIT_ERROR\fR\fR
644 .ad
645 .RS 28n
646 An invalid inheritance field was specified.
647 .RE
649 .sp
650 .ne 2
651 .na
652 \fB\fBEACL_INVALID_ACCESS_TYPE\fR\fR
653 .ad
654 .RS 28n
655 An invalid access type was specified.
656 .RE
658 .sp
659 .ne 2
660 .na
661 \fB\fBEACL_INVALID_STR\fR\fR
662 .ad
663 .RS 28n
664 The string is \fINULL\fR.
665 .RE
667 .sp
668 .ne 2
669 .na
670 \fB\fBEACL_INVALID_USER_GROUP\fR\fR
671 .ad
672 .RS 28n
673 The required user or group name not found.
674 .RE
676 .sp
677 .ne 2
678 .na
679 \fB\fBEACL_MISSING_FIELDS\fR\fR
680 .ad
681 .RS 28n
682 The ACL needs more fields to be specified.
683 .RE
685 .sp
686 .ne 2
687 .na
688 \fB\fBEACL_PERM_MASK_ERROR\fR\fR
689 .ad
690 .RS 28n
691 The permission mask is invalid.
692 .RE
694 .sp
695 .ne 2
696 .na
697 \fB\fBEACL_UNKNOWN_DATA\fR\fR
698 .ad
699 .RS 28n
700 Unknown data was found in the ACL.
701 .RE
703 .SH EXAMPLES
704 .LP
705 \fBExample 1 \fRExamples of permissions when \fBACL_COMPACT_FMT\fR is not
706 specified.
707 .sp
708 .in +2
709 .nf
710 user:joe:read_data/write_data:file_inherit/dir_inherit:allow
711 .fi
712 .in -2
713 .sp
715 .sp
716 .in +2
717 .nf
718 owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny
719 .fi
720 .in -2
721 .sp
723 .LP
724 \fBExample 2 \fRExamples of permissions when \fBACL_COMPACT_FMT\fR is
725 specified.
726 .sp
727 .in +2
728 .nf
729 user:joe:rw------------:fd----:allow
730 .fi
731 .in -2
732 .sp
734 .sp
735 .in +2
736 .nf
737 owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny
738 .fi
739 .in -2
740 .sp
742 .SH ATTRIBUTES
743 .sp
744 .LP
745 See \fBattributes\fR(5) for descriptions of the following attributes:
746 .sp
748 .sp
749 .TS
750 box;
751 c | c
752 l | l .
753 ATTRIBUTE TYPE ATTRIBUTE VALUE
754 _
755 Interface Stability Committed
756 _
757 MT-Level Safe
758 .TE
760 .SH SEE ALSO
761 .sp
762 .LP
763 \fBls\fR(1), \fBtar\fR(1), \fBacl\fR(2), \fBmalloc\fR(3C),
764 \fBaclfromtext\fR(3SEC), \fBacl\fR(5), \fBattributes\fR(5)