1ARCHIVE_ENTRY_ACL(3) BSD Library Functions Manual ARCHIVE_ENTRY_ACL(3)
2
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_next_w,
8 archive_entry_acl_reset, archive_entry_acl_to_text,
9 archive_entry_acl_to_text_w, archive_entry_acl_types — functions for
10 manipulating Access Control Lists in archive entry descriptions
11
13 Streaming Archive Library (libarchive, -larchive)
14
16 #include <archive_entry.h>
17 void
19 archive_entry_acl_add_entry(struct archive_entry *a, int type,
20 int permset, int tag, int qualifier, const char *name);
21 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 void
27 archive_entry_acl_clear(struct archive_entry *a);
28 int
30 archive_entry_acl_count(struct archive_entry *a, int type);
31 int
33 archive_entry_acl_from_text(struct archive_entry *a, const char *text,
34 int type);
35 int
37 archive_entry_acl_from_text_w(struct archive_entry *a,
38 const wchar_t *text, int type);
39 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 int
46 archive_entry_acl_next_w(struct archive_entry *a, int type,
47 int *ret_type, int *ret_permset, int *ret_tag, int *ret_qual,
48 const wchar_t **ret_name);
49 int
51 archive_entry_acl_reset(struct archive_entry *a, int type);
52 char *
54 archive_entry_acl_to_text(struct archive_entry *a, ssize_t *len_p,
55 int flags);
56 wchar_t *
58 archive_entry_acl_to_text_w(struct archive_entry *a, ssize_t *len_p,
59 int flags);
60 int
62 archive_entry_acl_types(struct archive_entry *a);
63
65 The “Access Control Lists (ACLs)” extend the standard Unix perssion
66 model. The ACL interface of libarchive supports both POSIX.1e and NFSv4
67 style ACLs. Use of ACLs is restricted by various levels of ACL support in
68 operating systems, file systems and archive formats.
69 POSIX.1e Access Control Lists
71 A POSIX.1e ACL consists of a number of independent entries. Each entry
72 specifies the permission set as bitmask of basic permissions. Valid per‐
73 missions in the permset are:
74 ARCHIVE_ENTRY_ACL_READ (r)
75 ARCHIVE_ENTRY_ACL_WRITE (w)
76 ARCHIVE_ENTRY_ACL_EXECUTE (x)
77 The permissions correspond to the normal Unix permissions.
78 The tag specifies the principal to which the permission applies. Valid
80 values are:
81 ARCHIVE_ENTRY_ACL_USER The user specified by the name field.
82 ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file.
83 ARCHIVE_ENTRY_ACL_GROUP The group specied by the name field.
84 ARCHIVE_ENTRY_ACL_GROUP_OBJ The group who owns the file.
85 ARCHIVE_ENTRY_ACL_MASK The maximum permissions to be obtained
86 via group permissions.
87 ARCHIVE_ENTRY_ACL_OTHER Any principal who is not file owner or
88 a member of the owning group.
89 The principals ARCHIVE_ENTRY_ACL_USER_OBJ, ARCHIVE_ENTRY_ACL_GROUP_OBJ
91 and ARCHIVE_ENTRY_ACL_OTHER are equivalent to user, group and other in
92 the classic Unix permission model and specify non-extended ACL entries.
93 All files with have an access ACL (ARCHIVE_ENTRY_ACL_TYPE_ACCESS). This
95 specifies the permissions required for access to the file itself. Direc‐
96 tories have an additional ACL (ARCHIVE_ENTRY_ACL_TYPE_DEFAULT), which
97 controls the initial access ACL for newly created directory entries.
98 NFSv4 Access Control Lists
100 A NFSv4 ACL consists of multiple individual entries called Access Control
101 Entries (ACEs).
102 There are four possible types of a NFSv4 ACE:
104 ARCHIVE_ENTRY_ACL_TYPE_ALLOW Allow principal to perform actions
105 requiring given permissions.
106 ARCHIVE_ENTRY_ACL_TYPE_DENY Prevent principal from performing
107 actions requiring given permissions.
108 ARCHIVE_ENTRY_ACL_TYPE_AUDIT Log access attempts by principal which
109 require given permissions.
110 ARCHIVE_ENTRY_ACL_TYPE_ALARM Trigger a system alarm on access
111 attempts by principal which require
112 given permissions.
113 The tag specifies the principal to which the permission applies. Valid
115 values are:
116 ARCHIVE_ENTRY_ACL_USER The user specified by the name field.
117 ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file.
118 ARCHIVE_ENTRY_ACL_GROUP The group specied by the name field.
119 ARCHIVE_ENTRY_ACL_GROUP_OBJ The group who owns the file.
120 ARCHIVE_ENTRY_ACL_EVERYONE Any principal who is not file owner or
121 a member of the owning group.
122 Entries with the ARCHIVE_ENTRY_ACL_USER or ARCHIVE_ENTRY_ACL_GROUP tag
124 store the user and group name in the name string and optionally the user
125 or group ID in the qualifier integer.
126 NFSv4 ACE permissions and flags are stored in the same permset bitfield.
128 Some permissions share the same constant and permission character but
129 have different effect on directories than on files. The following ACE
130 permissions are supported:
131 ARCHIVE_ENTRY_ACL_READ_DATA (r)
132 Read data (file).
133 ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (r)
134 List entries (directory).
135 ARCHIVE_ENTRY_ACL_WRITE_DATA (w)
136 Write data (file).
137 ARCHIVE_ENTRY_ACL_ADD_FILE (w)
138 Create files (directory).
139 ARCHIVE_ENTRY_ACL_EXECUTE (x)
140 Execute file or change into a directory.
141 ARCHIVE_ENTRY_ACL_APPEND_DATA (p)
142 Append data (file).
143 ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (p)
144 Create subdirectories (directory).
145 ARCHIVE_ENTRY_ACL_DELETE_CHILD (D)
146 Remove files and subdirectories inside a directory.
147 ARCHIVE_ENTRY_ACL_DELETE (d)
148 Remove file or directory.
149 ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (a)
150 Read file or directory attributes.
151 ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (A)
152 Write file or directory attributes.
153 ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (R)
154 Read named file or directory attributes.
155 ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (W)
156 Write named file or directory attributes.
157 ARCHIVE_ENTRY_ACL_READ_ACL (c)
158 Read file or directory ACL.
159 ARCHIVE_ENTRY_ACL_WRITE_ACL (C)
160 Write file or directory ACL.
161 ARCHIVE_ENTRY_ACL_WRITE_OWNER (o)
162 Change owner of a file or directory.
163 ARCHIVE_ENTRY_ACL_SYNCHRONIZE (s)
164 Use synchronous I/O.
165 The following NFSv4 ACL inheritance flags are supported:
167 ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (f)
168 Inherit parent directory ACE to files.
169 ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (d)
170 Inherit parent directory ACE to subdirectories.
171 ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (i)
172 Only inherit, do not apply the permission on the directory
173 itself.
174 ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (n)
175 Do not propagate inherit flags. Only first-level entries
176 inherit ACLs.
177 ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (S)
178 Trigger alarm or audit on successful access.
179 ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (F)
180 Trigger alarm or audit on failed access.
181 ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (I)
182 Mark that ACE was inherited.
183 Functions
185 archive_entry_acl_add_entry() and archive_entry_acl_add_entry_w() add a
186 single ACL entry. For the access ACL and non-extended principals, the
187 classic Unix permissions are updated. An archive entry cannot contain
188 both POSIX.1e and NFSv4 ACL entries.
189 archive_entry_acl_clear() removes all ACL entries and resets the enumera‐
191 tion pointer.
192 archive_entry_acl_count() counts the ACL entries that have the given type
194 mask. type can be the bitwise-or of
195 ARCHIVE_ENTRY_ACL_TYPE_ACCESS
196 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
197 for POSIX.1e ACLs and
198 ARCHIVE_ENTRY_ACL_TYPE_ALLOW
199 ARCHIVE_ENTRY_ACL_TYPE_DENY
200 ARCHIVE_ENTRY_ACL_TYPE_AUDIT
201 ARCHIVE_ENTRY_ACL_TYPE_ALARM
202 for NFSv4 ACLs. For POSIX.1e ACLs if ARCHIVE_ENTRY_ACL_TYPE_ACCESS is
203 included and at least one extended ACL entry is found, the three non-
204 extended ACLs are added.
205 archive_entry_acl_from_text() and archive_entry_acl_from_text_w() add new
207 (or merge with existing) ACL entries from (wide) text. The argument type
208 may take one of the following values:
209 ARCHIVE_ENTRY_ACL_TYPE_ACCESS
210 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
211 ARCHIVE_ENTRY_ACL_TYPE_NFS4
212 Supports all formats that can be created with archive_entry_acl_to_text()
213 or respective archive_entry_acl_to_text_w(). Existing ACL entries are
214 preserved. To get a clean new ACL from text archive_entry_acl_clear()
215 must be called first. Entries prefixed with “default:” are treated as
216 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT unless type is
217 ARCHIVE_ENTRY_ACL_TYPE_NFS4. Invalid entries, non-parseable ACL entries
218 and entries beginning with the ‘#’ character (comments) are skipped.
219 archive_entry_acl_next() and archive_entry_acl_next_w() return the next
221 entry of the ACL list. This functions may only be called after
222 archive_entry_acl_reset() has indicated the presence of extended ACL
223 entries.
224 archive_entry_acl_reset() prepare reading the list of ACL entries with
226 archive_entry_acl_next() or archive_entry_acl_next_w(). The function
227 returns either 0, if no non-extended ACLs are found. In this case, the
228 access permissions should be obtained by archive_entry_mode(3) or set
229 using chmod(2). Otherwise, the function returns the same value as
230 archive_entry_acl_count().
231 archive_entry_acl_to_text() and archive_entry_acl_to_text_w() convert the
233 ACL entries for the given type into a (wide) string of ACL entries sepa‐
234 rated by newline. If the pointer len_p is not NULL, then the function
235 shall return the length of the string (not including the NULL terminator)
236 in the location pointed to by len_p. The flag argument is a bitwise-or.
237 The following flags are effective only on POSIX.1e ACL:
239 ARCHIVE_ENTRY_ACL_TYPE_ACCESS
240 Output access ACLs.
241 ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
242 Output POSIX.1e default ACLs.
243 ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
244 Prefix each default ACL entry with the word “default:”.
245 ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
246 The mask and other ACLs don not contain a double colon.
247 The following flags are effecive only on NFSv4 ACL:
249 ARCHIVE_ENTRY_ACL_STYLE_COMPACT
250 Do not output minus characters for unset permissions and
251 flags in NFSv4 ACL permission and flag fields.
252 The following flags are effective on both POSIX.1e and NFSv4 ACL:
254 ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
255 Add an additional colon-separated field containing the user
256 or group id.
257 ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA
258 Separate ACL entries with comma instead of newline.
259 If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are
261 returned. It the entry contains POSIX.1e ACLs and none of the flags
262 ARCHIVE_ENTRY_ACL_TYPE_ACCESS or ARCHIVE_ENTRY_ACL_TYPE_DEFAULT are spec‐
263 ified, both access and default entries are returned and default entries
264 are prefixed with “default:”.
265 archive_entry_acl_types() get ACL entry types contained in an archive
267 entry's ACL. As POSIX.1e and NFSv4 ACL entries cannot be mixed, this
268 function is a very efficient way to detect if an ACL already contains
269 POSIX.1e or NFSv4 ACL entries.
270
272 archive_entry_acl_count() and archive_entry_acl_reset() returns the num‐
273 ber of ACL entries that match the given type mask. For POSIX.1e ACLS if
274 the type mask includes ARCHIVE_ENTRY_ACL_TYPE_ACCESS and at least one
275 extended ACL entry exists, the three classic Unix permissions are
276 counted.
277 archive_entry_acl_from_text() and archive_entry_acl_from_text_w() return
279 ARCHIVE_OK if all entries were successfully parsed and ARCHIVE_WARN if
280 one or more entries were invalid or non-parseable.
281 archive_entry_acl_next() and archive_entry_acl_next_w() return ARCHIVE_OK
283 on success, ARCHIVE_EOF if no more ACL entries exist and ARCHIVE_WARN if
284 archive_entry_acl_reset() has not been called first.
285 archive_entry_acl_to_text() returns a string representing the ACL entries
287 matching the given type and flags on success or NULL on error.
288 archive_entry_acl_to_text_w() returns a wide string representing the ACL
290 entries matching the given type and flags on success or NULL on error.
291 archive_entry_acl_types() returns a bitmask of ACL entry types or 0 if
293 archive entry has no ACL entries.
294
296 archive_entry(3), libarchive(3)
297BSD February 15, 2017 BSD