1ARCHIVE_ENTRY_ACL(3)     BSD Library Functions Manual     ARCHIVE_ENTRY_ACL(3)
2

NAME

4     archive_entry_acl_add_entry, archive_entry_acl_add_entry_w,
5     archive_entry_acl_clear, archive_entry_acl_count,
6     archive_entry_acl_from_text, archive_entry_acl_from_text_w,
7     archive_entry_acl_next, archive_entry_acl_reset,
8     archive_entry_acl_to_text, archive_entry_acl_to_text_w,
9     archive_entry_acl_types — functions for manipulating Access Control Lists
10     in archive entry descriptions
11

LIBRARY

13     Streaming Archive Library (libarchive, -larchive)
14

SYNOPSIS

16     #include <archive_entry.h>
17
18     void
19     archive_entry_acl_add_entry(struct archive_entry *a, int type,
20         int permset, int tag, int qualifier, const char *name);
21
22     void
23     archive_entry_acl_add_entry_w(struct archive_entry *a, int type,
24         int permset, int tag, int qualifier, const wchar_t *name);
25
26     void
27     archive_entry_acl_clear(struct archive_entry *a);
28
29     int
30     archive_entry_acl_count(struct archive_entry *a, int type);
31
32     int
33     archive_entry_acl_from_text(struct archive_entry *a, const char *text,
34         int type);
35
36     int
37     archive_entry_acl_from_text_w(struct archive_entry *a,
38         const wchar_t *text, int type);
39
40     int
41     archive_entry_acl_next(struct archive_entry *a, int type, int *ret_type,
42         int *ret_permset, int *ret_tag, int *ret_qual,
43         const char **ret_name);
44
45     int
46     archive_entry_acl_reset(struct archive_entry *a, int type);
47
48     char *
49     archive_entry_acl_to_text(struct archive_entry *a, ssize_t *len_p,
50         int flags);
51
52     wchar_t *
53     archive_entry_acl_to_text_w(struct archive_entry *a, ssize_t *len_p,
54         int flags);
55
56     int
57     archive_entry_acl_types(struct archive_entry *a);
58

DESCRIPTION

60     The “Access Control Lists (ACLs)” extend the standard Unix permission
61     model.  The ACL interface of libarchive supports both POSIX.1e and NFSv4
62     style ACLs.  Use of ACLs is restricted by various levels of ACL support
63     in operating systems, file systems and archive formats.
64
65   POSIX.1e Access Control Lists
66     A POSIX.1e ACL consists of a number of independent entries.  Each entry
67     specifies the permission set as a bitmask of basic permissions.  Valid
68     permissions in the permset are:
69           ARCHIVE_ENTRY_ACL_READ (r)
70           ARCHIVE_ENTRY_ACL_WRITE (w)
71           ARCHIVE_ENTRY_ACL_EXECUTE (x)
72     The permissions correspond to the normal Unix permissions.
73
74     The tag specifies the principal to which the permission applies.  Valid
75     values are:
76           ARCHIVE_ENTRY_ACL_USER       The user specified by the name field.
77           ARCHIVE_ENTRY_ACL_USER_OBJ   The owner of the file.
78           ARCHIVE_ENTRY_ACL_GROUP      The group specified by the name field.
79           ARCHIVE_ENTRY_ACL_GROUP_OBJ  The group which owns the file.
80           ARCHIVE_ENTRY_ACL_MASK       The maximum permissions to be obtained
81                                        via group permissions.
82           ARCHIVE_ENTRY_ACL_OTHER      Any principal who is not the file
83                                        owner or a member of the owning group.
84
85     The principals ARCHIVE_ENTRY_ACL_USER_OBJ, ARCHIVE_ENTRY_ACL_GROUP_OBJ
86     and ARCHIVE_ENTRY_ACL_OTHER are equivalent to user, group and other in
87     the classic Unix permission model and specify non-extended ACL entries.
88
89     All files have an access ACL (ARCHIVE_ENTRY_ACL_TYPE_ACCESS).  This spec‐
90     ifies the permissions required for access to the file itself.  Directo‐
91     ries have an additional ACL (ARCHIVE_ENTRY_ACL_TYPE_DEFAULT), which con‐
92     trols the initial access ACL for newly-created directory entries.
93
94   NFSv4 Access Control Lists
95     A NFSv4 ACL consists of multiple individual entries called Access Control
96     Entries (ACEs).
97
98     There are four possible types of a NFSv4 ACE:
99           ARCHIVE_ENTRY_ACL_TYPE_ALLOW Allow principal to perform actions
100                                        requiring given permissions.
101           ARCHIVE_ENTRY_ACL_TYPE_DENY  Prevent principal from performing
102                                        actions requiring given permissions.
103           ARCHIVE_ENTRY_ACL_TYPE_AUDIT Log access attempts by principal which
104                                        require given permissions.
105           ARCHIVE_ENTRY_ACL_TYPE_ALARM Trigger a system alarm on access
106                                        attempts by principal which require
107                                        given permissions.
108
109     The tag specifies the principal to which the permission applies.  Valid
110     values are:
111           ARCHIVE_ENTRY_ACL_USER       The user specified by the name field.
112           ARCHIVE_ENTRY_ACL_USER_OBJ   The owner of the file.
113           ARCHIVE_ENTRY_ACL_GROUP      The group specified by the name field.
114           ARCHIVE_ENTRY_ACL_GROUP_OBJ  The group which owns the file.
115           ARCHIVE_ENTRY_ACL_EVERYONE   Any principal who is not the file
116                                        owner or a member of the owning group.
117
118     Entries with the ARCHIVE_ENTRY_ACL_USER or ARCHIVE_ENTRY_ACL_GROUP tag
119     store the user and group name in the name string and optionally the user
120     or group ID in the qualifier integer.
121
122     NFSv4 ACE permissions and flags are stored in the same permset bitfield.
123     Some permissions share the same constant and permission character but
124     have different effect on directories than on files.  The following ACE
125     permissions are supported:
126           ARCHIVE_ENTRY_ACL_READ_DATA (r)
127                   Read data (file).
128           ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (r)
129                   List entries (directory).
130           ARCHIVE_ENTRY_ACL_WRITE_DATA (w)
131                   Write data (file).
132           ARCHIVE_ENTRY_ACL_ADD_FILE (w)
133                   Create files (directory).
134           ARCHIVE_ENTRY_ACL_EXECUTE (x)
135                   Execute file or change into a directory.
136           ARCHIVE_ENTRY_ACL_APPEND_DATA (p)
137                   Append data (file).
138           ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (p)
139                   Create subdirectories (directory).
140           ARCHIVE_ENTRY_ACL_DELETE_CHILD (D)
141                   Remove files and subdirectories inside a directory.
142           ARCHIVE_ENTRY_ACL_DELETE (d)
143                   Remove file or directory.
144           ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (a)
145                   Read file or directory attributes.
146           ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (A)
147                   Write file or directory attributes.
148           ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (R)
149                   Read named file or directory attributes.
150           ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (W)
151                   Write named file or directory attributes.
152           ARCHIVE_ENTRY_ACL_READ_ACL (c)
153                   Read file or directory ACL.
154           ARCHIVE_ENTRY_ACL_WRITE_ACL (C)
155                   Write file or directory ACL.
156           ARCHIVE_ENTRY_ACL_WRITE_OWNER (o)
157                   Change owner of a file or directory.
158           ARCHIVE_ENTRY_ACL_SYNCHRONIZE (s)
159                   Use synchronous I/O.
160
161     The following NFSv4 ACL inheritance flags are supported:
162           ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (f)
163                   Inherit parent directory ACE to files.
164           ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (d)
165                   Inherit parent directory ACE to subdirectories.
166           ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (i)
167                   Only inherit, do not apply the permission on the directory
168                   itself.
169           ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (n)
170                   Do not propagate inherit flags.  Only first-level entries
171                   inherit ACLs.
172           ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (S)
173                   Trigger alarm or audit on successful access.
174           ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (F)
175                   Trigger alarm or audit on failed access.
176           ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (I)
177                   Mark that ACE was inherited.
178
179   Functions
180     archive_entry_acl_add_entry() and archive_entry_acl_add_entry_w() add a
181     single ACL entry.  For the access ACL and non-extended principals, the
182     classic Unix permissions are updated.  An archive entry cannot contain
183     both POSIX.1e and NFSv4 ACL entries.
184
185     archive_entry_acl_clear() removes all ACL entries and resets the enumera‐
186     tion pointer.
187
188     archive_entry_acl_count() counts the ACL entries that have the given type
189     mask.  type can be the bitwise-or of
190           ARCHIVE_ENTRY_ACL_TYPE_ACCESS
191           ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
192     for POSIX.1e ACLs and
193           ARCHIVE_ENTRY_ACL_TYPE_ALLOW
194           ARCHIVE_ENTRY_ACL_TYPE_DENY
195           ARCHIVE_ENTRY_ACL_TYPE_AUDIT
196           ARCHIVE_ENTRY_ACL_TYPE_ALARM
197     for NFSv4 ACLs.  For POSIX.1e ACLs if ARCHIVE_ENTRY_ACL_TYPE_ACCESS is
198     included and at least one extended ACL entry is found, the three non-
199     extended ACLs are added.
200
201     archive_entry_acl_from_text() and archive_entry_acl_from_text_w() add new
202     (or merge with existing) ACL entries from (wide) text.  The argument type
203     may take one of the following values:
204           ARCHIVE_ENTRY_ACL_TYPE_ACCESS
205           ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
206           ARCHIVE_ENTRY_ACL_TYPE_NFS4
207     Supports all formats that can be created with archive_entry_acl_to_text()
208     or respectively archive_entry_acl_to_text_w().  Existing ACL entries are
209     preserved.  To get a clean new ACL from text archive_entry_acl_clear()
210     must be called first.  Entries prefixed with “default:” are treated as
211     ARCHIVE_ENTRY_ACL_TYPE_DEFAULT unless type is
212     ARCHIVE_ENTRY_ACL_TYPE_NFS4.  Invalid entries, non-parseable ACL entries
213     and entries beginning with the ‘#’ character (comments) are skipped.
214
215     archive_entry_acl_next() return the next entry of the ACL list.  This
216     functions may only be called after archive_entry_acl_reset() has indi‐
217     cated the presence of extended ACL entries.
218
219     archive_entry_acl_reset() prepare reading the list of ACL entries with
220     archive_entry_acl_next().  The function returns 0 if no non-extended ACLs
221     are found.  In this case, the access permissions should be obtained by
222     archive_entry_mode(3) or set using chmod(2).  Otherwise, the function
223     returns the same value as archive_entry_acl_count().
224
225     archive_entry_acl_to_text() and archive_entry_acl_to_text_w() convert the
226     ACL entries for the given type into a (wide) string of ACL entries sepa‐
227     rated by newline.  If the pointer len_p is not NULL, then the function
228     shall return the length of the string (not including the NULL terminator)
229     in the location pointed to by len_p.  The flag argument is a bitwise-or.
230
231     The following flags are effective only on POSIX.1e ACL:
232           ARCHIVE_ENTRY_ACL_TYPE_ACCESS
233                   Output access ACLs.
234           ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
235                   Output POSIX.1e default ACLs.
236           ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
237                   Prefix each default ACL entry with the word “default:”.
238           ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
239                   The mask and other ACLs don not contain a double colon.
240
241     The following flags are effecive only on NFSv4 ACL:
242           ARCHIVE_ENTRY_ACL_STYLE_COMPACT
243                   Do not output minus characters for unset permissions and
244                   flags in NFSv4 ACL permission and flag fields.
245
246     The following flags are effective on both POSIX.1e and NFSv4 ACL:
247           ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
248                   Add an additional colon-separated field containing the user
249                   or group id.
250           ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA
251                   Separate ACL entries with comma instead of newline.
252
253     If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are
254     returned.  It the entry contains POSIX.1e ACLs and none of the flags
255     ARCHIVE_ENTRY_ACL_TYPE_ACCESS or ARCHIVE_ENTRY_ACL_TYPE_DEFAULT are spec‐
256     ified, both access and default entries are returned and default entries
257     are prefixed with “default:”.
258
259     archive_entry_acl_types() get ACL entry types contained in an archive
260     entry's ACL.  As POSIX.1e and NFSv4 ACL entries cannot be mixed, this
261     function is a very efficient way to detect if an ACL already contains
262     POSIX.1e or NFSv4 ACL entries.
263

RETURN VALUES

265     archive_entry_acl_count() and archive_entry_acl_reset() returns the num‐
266     ber of ACL entries that match the given type mask.  For POSIX.1e ACLS if
267     the type mask includes ARCHIVE_ENTRY_ACL_TYPE_ACCESS and at least one
268     extended ACL entry exists, the three classic Unix permissions are
269     counted.
270
271     archive_entry_acl_from_text() and archive_entry_acl_from_text_w() return
272     ARCHIVE_OK if all entries were successfully parsed and ARCHIVE_WARN if
273     one or more entries were invalid or non-parseable.
274
275     archive_entry_acl_next() returns ARCHIVE_OK on success, ARCHIVE_EOF if no
276     more ACL entries exist and ARCHIVE_WARN if archive_entry_acl_reset() has
277     not been called first.
278
279     archive_entry_acl_to_text() returns a string representing the ACL entries
280     matching the given type and flags on success or NULL on error.
281
282     archive_entry_acl_to_text_w() returns a wide string representing the ACL
283     entries matching the given type and flags on success or NULL on error.
284
285     archive_entry_acl_types() returns a bitmask of ACL entry types or 0 if
286     archive entry has no ACL entries.
287

SEE ALSO

289     archive_entry(3), libarchive(3)
290
291BSD                            February 15, 2017                           BSD
Impressum