mirror of
https://github.com/cmclark00/retro-imager.git
synced 2025-05-19 08:25:21 +01:00
67618a2eac
- Update bunlded libarchive version used on Windows/Mac - Enable requested zstd support while we are at it. Closes #211
290 lines
12 KiB
Text
290 lines
12 KiB
Text
ARCHIVE_ENTRY_ACL(3) BSD Library Functions Manual ARCHIVE_ENTRY_ACL(3)
|
||
|
||
NAME
|
||
archive_entry_acl_add_entry, archive_entry_acl_add_entry_w,
|
||
archive_entry_acl_clear, archive_entry_acl_count,
|
||
archive_entry_acl_from_text, archive_entry_acl_from_text_w,
|
||
archive_entry_acl_next, archive_entry_acl_reset,
|
||
archive_entry_acl_to_text, archive_entry_acl_to_text_w,
|
||
archive_entry_acl_types — functions for manipulating Access Control Lists
|
||
in archive entry descriptions
|
||
|
||
LIBRARY
|
||
Streaming Archive Library (libarchive, -larchive)
|
||
|
||
SYNOPSIS
|
||
#include <archive_entry.h>
|
||
|
||
void
|
||
archive_entry_acl_add_entry(struct archive_entry *a, int type,
|
||
int permset, int tag, int qualifier, const char *name);
|
||
|
||
void
|
||
archive_entry_acl_add_entry_w(struct archive_entry *a, int type,
|
||
int permset, int tag, int qualifier, const wchar_t *name);
|
||
|
||
void
|
||
archive_entry_acl_clear(struct archive_entry *a);
|
||
|
||
int
|
||
archive_entry_acl_count(struct archive_entry *a, int type);
|
||
|
||
int
|
||
archive_entry_acl_from_text(struct archive_entry *a, const char *text,
|
||
int type);
|
||
|
||
int
|
||
archive_entry_acl_from_text_w(struct archive_entry *a,
|
||
const wchar_t *text, int type);
|
||
|
||
int
|
||
archive_entry_acl_next(struct archive_entry *a, int type, int *ret_type,
|
||
int *ret_permset, int *ret_tag, int *ret_qual,
|
||
const char **ret_name);
|
||
|
||
int
|
||
archive_entry_acl_reset(struct archive_entry *a, int type);
|
||
|
||
char *
|
||
archive_entry_acl_to_text(struct archive_entry *a, ssize_t *len_p,
|
||
int flags);
|
||
|
||
wchar_t *
|
||
archive_entry_acl_to_text_w(struct archive_entry *a, ssize_t *len_p,
|
||
int flags);
|
||
|
||
int
|
||
archive_entry_acl_types(struct archive_entry *a);
|
||
|
||
DESCRIPTION
|
||
The “Access Control Lists (ACLs)” extend the standard Unix permission
|
||
model. The ACL interface of libarchive supports both POSIX.1e and NFSv4
|
||
style ACLs. Use of ACLs is restricted by various levels of ACL support
|
||
in operating systems, file systems and archive formats.
|
||
|
||
POSIX.1e Access Control Lists
|
||
A POSIX.1e ACL consists of a number of independent entries. Each entry
|
||
specifies the permission set as a bitmask of basic permissions. Valid
|
||
permissions in the permset are:
|
||
ARCHIVE_ENTRY_ACL_READ (r)
|
||
ARCHIVE_ENTRY_ACL_WRITE (w)
|
||
ARCHIVE_ENTRY_ACL_EXECUTE (x)
|
||
The permissions correspond to the normal Unix permissions.
|
||
|
||
The tag specifies the principal to which the permission applies. Valid
|
||
values are:
|
||
ARCHIVE_ENTRY_ACL_USER The user specified by the name field.
|
||
ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file.
|
||
ARCHIVE_ENTRY_ACL_GROUP The group specified by the name field.
|
||
ARCHIVE_ENTRY_ACL_GROUP_OBJ The group which owns the file.
|
||
ARCHIVE_ENTRY_ACL_MASK The maximum permissions to be obtained
|
||
via group permissions.
|
||
ARCHIVE_ENTRY_ACL_OTHER Any principal who is not the file
|
||
owner or a member of the owning group.
|
||
|
||
The principals ARCHIVE_ENTRY_ACL_USER_OBJ, ARCHIVE_ENTRY_ACL_GROUP_OBJ
|
||
and ARCHIVE_ENTRY_ACL_OTHER are equivalent to user, group and other in
|
||
the classic Unix permission model and specify non-extended ACL entries.
|
||
|
||
All files have an access ACL (ARCHIVE_ENTRY_ACL_TYPE_ACCESS). This spec‐
|
||
ifies the permissions required for access to the file itself. Directo‐
|
||
ries have an additional ACL (ARCHIVE_ENTRY_ACL_TYPE_DEFAULT), which con‐
|
||
trols the initial access ACL for newly-created directory entries.
|
||
|
||
NFSv4 Access Control Lists
|
||
A NFSv4 ACL consists of multiple individual entries called Access Control
|
||
Entries (ACEs).
|
||
|
||
There are four possible types of a NFSv4 ACE:
|
||
ARCHIVE_ENTRY_ACL_TYPE_ALLOW Allow principal to perform actions re‐
|
||
quiring given permissions.
|
||
ARCHIVE_ENTRY_ACL_TYPE_DENY Prevent principal from performing ac‐
|
||
tions requiring given permissions.
|
||
ARCHIVE_ENTRY_ACL_TYPE_AUDIT Log access attempts by principal which
|
||
require given permissions.
|
||
ARCHIVE_ENTRY_ACL_TYPE_ALARM Trigger a system alarm on access at‐
|
||
tempts by principal which require
|
||
given permissions.
|
||
|
||
The tag specifies the principal to which the permission applies. Valid
|
||
values are:
|
||
ARCHIVE_ENTRY_ACL_USER The user specified by the name field.
|
||
ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file.
|
||
ARCHIVE_ENTRY_ACL_GROUP The group specified by the name field.
|
||
ARCHIVE_ENTRY_ACL_GROUP_OBJ The group which owns the file.
|
||
ARCHIVE_ENTRY_ACL_EVERYONE Any principal who is not the file
|
||
owner or a member of the owning group.
|
||
|
||
Entries with the ARCHIVE_ENTRY_ACL_USER or ARCHIVE_ENTRY_ACL_GROUP tag
|
||
store the user and group name in the name string and optionally the user
|
||
or group ID in the qualifier integer.
|
||
|
||
NFSv4 ACE permissions and flags are stored in the same permset bitfield.
|
||
Some permissions share the same constant and permission character but
|
||
have different effect on directories than on files. The following ACE
|
||
permissions are supported:
|
||
ARCHIVE_ENTRY_ACL_READ_DATA (r)
|
||
Read data (file).
|
||
ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (r)
|
||
List entries (directory).
|
||
ARCHIVE_ENTRY_ACL_WRITE_DATA (w)
|
||
Write data (file).
|
||
ARCHIVE_ENTRY_ACL_ADD_FILE (w)
|
||
Create files (directory).
|
||
ARCHIVE_ENTRY_ACL_EXECUTE (x)
|
||
Execute file or change into a directory.
|
||
ARCHIVE_ENTRY_ACL_APPEND_DATA (p)
|
||
Append data (file).
|
||
ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (p)
|
||
Create subdirectories (directory).
|
||
ARCHIVE_ENTRY_ACL_DELETE_CHILD (D)
|
||
Remove files and subdirectories inside a directory.
|
||
ARCHIVE_ENTRY_ACL_DELETE (d)
|
||
Remove file or directory.
|
||
ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (a)
|
||
Read file or directory attributes.
|
||
ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (A)
|
||
Write file or directory attributes.
|
||
ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (R)
|
||
Read named file or directory attributes.
|
||
ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (W)
|
||
Write named file or directory attributes.
|
||
ARCHIVE_ENTRY_ACL_READ_ACL (c)
|
||
Read file or directory ACL.
|
||
ARCHIVE_ENTRY_ACL_WRITE_ACL (C)
|
||
Write file or directory ACL.
|
||
ARCHIVE_ENTRY_ACL_WRITE_OWNER (o)
|
||
Change owner of a file or directory.
|
||
ARCHIVE_ENTRY_ACL_SYNCHRONIZE (s)
|
||
Use synchronous I/O.
|
||
|
||
The following NFSv4 ACL inheritance flags are supported:
|
||
ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (f)
|
||
Inherit parent directory ACE to files.
|
||
ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (d)
|
||
Inherit parent directory ACE to subdirectories.
|
||
ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (i)
|
||
Only inherit, do not apply the permission on the directory
|
||
itself.
|
||
ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (n)
|
||
Do not propagate inherit flags. Only first-level entries
|
||
inherit ACLs.
|
||
ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (S)
|
||
Trigger alarm or audit on successful access.
|
||
ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (F)
|
||
Trigger alarm or audit on failed access.
|
||
ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (I)
|
||
Mark that ACE was inherited.
|
||
|
||
Functions
|
||
archive_entry_acl_add_entry() and archive_entry_acl_add_entry_w() add a
|
||
single ACL entry. For the access ACL and non-extended principals, the
|
||
classic Unix permissions are updated. An archive entry cannot contain
|
||
both POSIX.1e and NFSv4 ACL entries.
|
||
|
||
archive_entry_acl_clear() removes all ACL entries and resets the enumera‐
|
||
tion pointer.
|
||
|
||
archive_entry_acl_count() counts the ACL entries that have the given type
|
||
mask. type can be the bitwise-or of
|
||
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
||
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
||
for POSIX.1e ACLs and
|
||
ARCHIVE_ENTRY_ACL_TYPE_ALLOW
|
||
ARCHIVE_ENTRY_ACL_TYPE_DENY
|
||
ARCHIVE_ENTRY_ACL_TYPE_AUDIT
|
||
ARCHIVE_ENTRY_ACL_TYPE_ALARM
|
||
for NFSv4 ACLs. For POSIX.1e ACLs if ARCHIVE_ENTRY_ACL_TYPE_ACCESS is
|
||
included and at least one extended ACL entry is found, the three non-ex‐
|
||
tended ACLs are added.
|
||
|
||
archive_entry_acl_from_text() and archive_entry_acl_from_text_w() add new
|
||
(or merge with existing) ACL entries from (wide) text. The argument type
|
||
may take one of the following values:
|
||
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
||
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
||
ARCHIVE_ENTRY_ACL_TYPE_NFS4
|
||
Supports all formats that can be created with archive_entry_acl_to_text()
|
||
or respectively archive_entry_acl_to_text_w(). Existing ACL entries are
|
||
preserved. To get a clean new ACL from text archive_entry_acl_clear()
|
||
must be called first. Entries prefixed with “default:” are treated as
|
||
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT unless type is
|
||
ARCHIVE_ENTRY_ACL_TYPE_NFS4. Invalid entries, non-parseable ACL entries
|
||
and entries beginning with the ‘#’ character (comments) are skipped.
|
||
|
||
archive_entry_acl_next() return the next entry of the ACL list. This
|
||
functions may only be called after archive_entry_acl_reset() has indi‐
|
||
cated the presence of extended ACL entries.
|
||
|
||
archive_entry_acl_reset() prepare reading the list of ACL entries with
|
||
archive_entry_acl_next(). The function returns 0 if no non-extended ACLs
|
||
are found. In this case, the access permissions should be obtained by
|
||
archive_entry_mode(3) or set using chmod(2). Otherwise, the function re‐
|
||
turns the same value as archive_entry_acl_count().
|
||
|
||
archive_entry_acl_to_text() and archive_entry_acl_to_text_w() convert the
|
||
ACL entries for the given type into a (wide) string of ACL entries sepa‐
|
||
rated by newline. If the pointer len_p is not NULL, then the function
|
||
shall return the length of the string (not including the NULL terminator)
|
||
in the location pointed to by len_p. The flag argument is a bitwise-or.
|
||
|
||
The following flags are effective only on POSIX.1e ACL:
|
||
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
||
Output access ACLs.
|
||
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
||
Output POSIX.1e default ACLs.
|
||
ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
|
||
Prefix each default ACL entry with the word “default:”.
|
||
ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
|
||
The mask and other ACLs don not contain a double colon.
|
||
|
||
The following flags are effecive only on NFSv4 ACL:
|
||
ARCHIVE_ENTRY_ACL_STYLE_COMPACT
|
||
Do not output minus characters for unset permissions and
|
||
flags in NFSv4 ACL permission and flag fields.
|
||
|
||
The following flags are effective on both POSIX.1e and NFSv4 ACL:
|
||
ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
|
||
Add an additional colon-separated field containing the user
|
||
or group id.
|
||
ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA
|
||
Separate ACL entries with comma instead of newline.
|
||
|
||
If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are re‐
|
||
turned. It the entry contains POSIX.1e ACLs and none of the flags
|
||
ARCHIVE_ENTRY_ACL_TYPE_ACCESS or ARCHIVE_ENTRY_ACL_TYPE_DEFAULT are spec‐
|
||
ified, both access and default entries are returned and default entries
|
||
are prefixed with “default:”.
|
||
|
||
archive_entry_acl_types() get ACL entry types contained in an archive en‐
|
||
try's ACL. As POSIX.1e and NFSv4 ACL entries cannot be mixed, this func‐
|
||
tion is a very efficient way to detect if an ACL already contains
|
||
POSIX.1e or NFSv4 ACL entries.
|
||
|
||
RETURN VALUES
|
||
archive_entry_acl_count() and archive_entry_acl_reset() returns the num‐
|
||
ber of ACL entries that match the given type mask. For POSIX.1e ACLS if
|
||
the type mask includes ARCHIVE_ENTRY_ACL_TYPE_ACCESS and at least one ex‐
|
||
tended ACL entry exists, the three classic Unix permissions are counted.
|
||
|
||
archive_entry_acl_from_text() and archive_entry_acl_from_text_w() return
|
||
ARCHIVE_OK if all entries were successfully parsed and ARCHIVE_WARN if
|
||
one or more entries were invalid or non-parseable.
|
||
|
||
archive_entry_acl_next() returns ARCHIVE_OK on success, ARCHIVE_EOF if no
|
||
more ACL entries exist and ARCHIVE_WARN if archive_entry_acl_reset() has
|
||
not been called first.
|
||
|
||
archive_entry_acl_to_text() returns a string representing the ACL entries
|
||
matching the given type and flags on success or NULL on error.
|
||
|
||
archive_entry_acl_to_text_w() returns a wide string representing the ACL
|
||
entries matching the given type and flags on success or NULL on error.
|
||
|
||
archive_entry_acl_types() returns a bitmask of ACL entry types or 0 if
|
||
archive entry has no ACL entries.
|
||
|
||
SEE ALSO
|
||
archive_entry(3), libarchive(3)
|
||
|
||
BSD February 15, 2017 BSD
|