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_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
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_reset(struct archive_entry *a, int type);
47 char *
49 archive_entry_acl_to_text(struct archive_entry *a, ssize_t *len_p,
50 int flags);
51 wchar_t *
53 archive_entry_acl_to_text_w(struct archive_entry *a, ssize_t *len_p,
54 int flags);
55 int
57 archive_entry_acl_types(struct archive_entry *a);
58
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 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 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 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 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 NFSv4 Access Control Lists
95 A NFSv4 ACL consists of multiple individual entries called Access Control
96 Entries (ACEs).
97 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 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 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 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 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 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 archive_entry_acl_clear() removes all ACL entries and resets the enumera‐
186 tion pointer.
187 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 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 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 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 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 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 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 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 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 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
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 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 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 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 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 archive_entry_acl_types() returns a bitmask of ACL entry types or 0 if
286 archive entry has no ACL entries.
287
289 archive_entry(3), libarchive(3)
290BSD February 15, 2017 BSD