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
452 lines
13 KiB
Groff
452 lines
13 KiB
Groff
.TH ARCHIVE_ENTRY_ACL 3 "February 15, 2017" ""
|
|
.SH NAME
|
|
.ad l
|
|
\fB\%archive_entry_acl_add_entry\fP,
|
|
\fB\%archive_entry_acl_add_entry_w\fP,
|
|
\fB\%archive_entry_acl_clear\fP,
|
|
\fB\%archive_entry_acl_count\fP,
|
|
\fB\%archive_entry_acl_from_text\fP,
|
|
\fB\%archive_entry_acl_from_text_w\fP,
|
|
\fB\%archive_entry_acl_next\fP,
|
|
\fB\%archive_entry_acl_reset\fP,
|
|
\fB\%archive_entry_acl_to_text\fP,
|
|
\fB\%archive_entry_acl_to_text_w\fP,
|
|
\fB\%archive_entry_acl_types\fP
|
|
\- functions for manipulating Access Control Lists in archive entry descriptions
|
|
.SH LIBRARY
|
|
.ad l
|
|
Streaming Archive Library (libarchive, -larchive)
|
|
.SH SYNOPSIS
|
|
.ad l
|
|
\fB#include <archive_entry.h>\fP
|
|
.br
|
|
\fIvoid\fP
|
|
.br
|
|
\fB\%archive_entry_acl_add_entry\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qualifier\fP, \fI\%const\ char\ *name\fP);
|
|
.br
|
|
\fIvoid\fP
|
|
.br
|
|
\fB\%archive_entry_acl_add_entry_w\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qualifier\fP, \fI\%const\ wchar_t\ *name\fP);
|
|
.br
|
|
\fIvoid\fP
|
|
.br
|
|
\fB\%archive_entry_acl_clear\fP(\fI\%struct\ archive_entry\ *a\fP);
|
|
.br
|
|
\fIint\fP
|
|
.br
|
|
\fB\%archive_entry_acl_count\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ type\fP);
|
|
.br
|
|
\fIint\fP
|
|
.br
|
|
\fB\%archive_entry_acl_from_text\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%const\ char\ *text\fP, \fI\%int\ type\fP);
|
|
.br
|
|
\fIint\fP
|
|
.br
|
|
\fB\%archive_entry_acl_from_text_w\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%const\ wchar_t\ *text\fP, \fI\%int\ type\fP);
|
|
.br
|
|
\fIint\fP
|
|
.br
|
|
\fB\%archive_entry_acl_next\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ type\fP, \fI\%int\ *ret_type\fP, \fI\%int\ *ret_permset\fP, \fI\%int\ *ret_tag\fP, \fI\%int\ *ret_qual\fP, \fI\%const\ char\ **ret_name\fP);
|
|
.br
|
|
\fIint\fP
|
|
.br
|
|
\fB\%archive_entry_acl_reset\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ type\fP);
|
|
.br
|
|
\fIchar *\fP
|
|
.br
|
|
\fB\%archive_entry_acl_to_text\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%ssize_t\ *len_p\fP, \fI\%int\ flags\fP);
|
|
.br
|
|
\fIwchar_t *\fP
|
|
.br
|
|
\fB\%archive_entry_acl_to_text_w\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%ssize_t\ *len_p\fP, \fI\%int\ flags\fP);
|
|
.br
|
|
\fIint\fP
|
|
.br
|
|
\fB\%archive_entry_acl_types\fP(\fI\%struct\ archive_entry\ *a\fP);
|
|
.SH DESCRIPTION
|
|
.ad l
|
|
The
|
|
``Access Control Lists (ACLs)''
|
|
extend the standard Unix permission model.
|
|
The ACL interface of
|
|
\fB\%libarchive\fP
|
|
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.
|
|
.SS 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
|
|
are:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_READ (.B r )
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_WRITE (.B w )
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_EXECUTE (.B x )
|
|
.RE
|
|
The permissions correspond to the normal Unix permissions.
|
|
.PP
|
|
The
|
|
specifies the principal to which the permission applies.
|
|
Valid values are:
|
|
.RS 5
|
|
It .BR ARCHIVE_ENTRY_ACL_USER
|
|
The user specified by the name field.
|
|
It .BR ARCHIVE_ENTRY_ACL_USER_OBJ
|
|
The owner of the file.
|
|
It .BR ARCHIVE_ENTRY_ACL_GROUP
|
|
The group specified by the name field.
|
|
It .BR ARCHIVE_ENTRY_ACL_GROUP_OBJ
|
|
The group which owns the file.
|
|
It .BR ARCHIVE_ENTRY_ACL_MASK
|
|
The maximum permissions to be obtained via group permissions.
|
|
It .BR ARCHIVE_ENTRY_ACL_OTHER
|
|
Any principal who is not the file owner or a member of the owning group.
|
|
.RE
|
|
.PP
|
|
The principals
|
|
.BR ARCHIVE_ENTRY_ACL_USER_OBJ,
|
|
.BR ARCHIVE_ENTRY_ACL_GROUP_OBJ
|
|
and
|
|
.BR ARCHIVE_ENTRY_ACL_OTHER
|
|
are equivalent to user, group and other in the classic Unix permission
|
|
model and specify non-extended ACL entries.
|
|
.PP
|
|
All files have an access ACL
|
|
(.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS.)
|
|
This specifies the permissions required for access to the file itself.
|
|
Directories have an additional ACL
|
|
(.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT,)
|
|
which controls the initial access ACL for newly-created directory entries.
|
|
.SS NFSv4 Access Control Lists
|
|
A NFSv4 ACL consists of multiple individual entries called Access Control
|
|
Entries (ACEs).
|
|
.PP
|
|
There are four possible types of a NFSv4 ACE:
|
|
.RS 5
|
|
It .BR ARCHIVE_ENTRY_ACL_TYPE_ALLOW
|
|
Allow principal to perform actions requiring given permissions.
|
|
It .BR ARCHIVE_ENTRY_ACL_TYPE_DENY
|
|
Prevent principal from performing actions requiring given permissions.
|
|
It .BR ARCHIVE_ENTRY_ACL_TYPE_AUDIT
|
|
Log access attempts by principal which require given permissions.
|
|
It .BR ARCHIVE_ENTRY_ACL_TYPE_ALARM
|
|
Trigger a system alarm on access attempts by principal which require given
|
|
permissions.
|
|
.RE
|
|
.PP
|
|
The
|
|
specifies the principal to which the permission applies.
|
|
Valid values are:
|
|
.RS 5
|
|
It .BR ARCHIVE_ENTRY_ACL_USER
|
|
The user specified by the name field.
|
|
It .BR ARCHIVE_ENTRY_ACL_USER_OBJ
|
|
The owner of the file.
|
|
It .BR ARCHIVE_ENTRY_ACL_GROUP
|
|
The group specified by the name field.
|
|
It .BR ARCHIVE_ENTRY_ACL_GROUP_OBJ
|
|
The group which owns the file.
|
|
It .BR ARCHIVE_ENTRY_ACL_EVERYONE
|
|
Any principal who is not the file owner or a member of the owning group.
|
|
.RE
|
|
.PP
|
|
Entries with the
|
|
.BR ARCHIVE_ENTRY_ACL_USER
|
|
or
|
|
.BR ARCHIVE_ENTRY_ACL_GROUP
|
|
tag store the user and group name in the
|
|
string and optionally the user or group ID in the
|
|
integer.
|
|
.PP
|
|
NFSv4 ACE permissions and flags are stored in the same
|
|
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:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_READ_DATA (.B r )
|
|
Read data (file).
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (.B r )
|
|
List entries (directory).
|
|
.TP
|
|
ARCHIVE_ENTRY_ACL_WRITE_DATA (.B w )
|
|
Write data (file).
|
|
.TP
|
|
ARCHIVE_ENTRY_ACL_ADD_FILE (.B w )
|
|
Create files (directory).
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_EXECUTE (.B x )
|
|
Execute file or change into a directory.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_APPEND_DATA (.B p )
|
|
Append data (file).
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (.B p )
|
|
Create subdirectories (directory).
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_DELETE_CHILD (.B D )
|
|
Remove files and subdirectories inside a directory.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_DELETE (.B d )
|
|
Remove file or directory.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (.B a )
|
|
Read file or directory attributes.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (.B A )
|
|
Write file or directory attributes.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (.B R )
|
|
Read named file or directory attributes.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (.B W )
|
|
Write named file or directory attributes.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_READ_ACL (.B c )
|
|
Read file or directory ACL.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_WRITE_ACL (.B C )
|
|
Write file or directory ACL.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_WRITE_OWNER (.B o )
|
|
Change owner of a file or directory.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_SYNCHRONIZE (.B s )
|
|
Use synchronous I/O.
|
|
.RE
|
|
.PP
|
|
The following NFSv4 ACL inheritance flags are supported:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (.B f )
|
|
Inherit parent directory ACE to files.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (.B d )
|
|
Inherit parent directory ACE to subdirectories.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (.B i )
|
|
Only inherit, do not apply the permission on the directory itself.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (.B n )
|
|
Do not propagate inherit flags.
|
|
Only first-level entries inherit ACLs.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (.B S )
|
|
Trigger alarm or audit on successful access.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (.B F )
|
|
Trigger alarm or audit on failed access.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (.B I )
|
|
Mark that ACE was inherited.
|
|
.RE
|
|
.SS Functions
|
|
\fB\%archive_entry_acl_add_entry\fP()
|
|
and
|
|
\fB\%archive_entry_acl_add_entry_w\fP()
|
|
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.
|
|
.PP
|
|
\fB\%archive_entry_acl_clear\fP()
|
|
removes all ACL entries and resets the enumeration pointer.
|
|
.PP
|
|
\fB\%archive_entry_acl_count\fP()
|
|
counts the ACL entries that have the given type mask.
|
|
can be the bitwise-or of
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
|
.RE
|
|
for POSIX.1e ACLs and
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ALLOW
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_DENY
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_AUDIT
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ALARM
|
|
.RE
|
|
for NFSv4 ACLs.
|
|
For POSIX.1e ACLs if
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
|
is included and at least one extended ACL entry is found,
|
|
the three non-extended ACLs are added.
|
|
.PP
|
|
\fB\%archive_entry_acl_from_text\fP()
|
|
and
|
|
\fB\%archive_entry_acl_from_text_w\fP()
|
|
add new
|
|
(or merge with existing)
|
|
ACL entries from
|
|
(wide)
|
|
text.
|
|
The argument
|
|
may take one of the following values:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_NFS4
|
|
.RE
|
|
Supports all formats that can be created with
|
|
\fB\%archive_entry_acl_to_text\fP()
|
|
or respectively
|
|
\fB\%archive_entry_acl_to_text_w\fP().
|
|
Existing ACL entries are preserved.
|
|
To get a clean new ACL from text
|
|
\fB\%archive_entry_acl_clear\fP()
|
|
must be called first.
|
|
Entries prefixed with
|
|
``default:''
|
|
are treated as
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
|
unless
|
|
is
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_NFS4.
|
|
Invalid entries, non-parseable ACL entries and entries beginning with
|
|
the
|
|
Sq #
|
|
character
|
|
(comments)
|
|
are skipped.
|
|
.PP
|
|
\fB\%archive_entry_acl_next\fP()
|
|
return the next entry of the ACL list.
|
|
This functions may only be called after
|
|
\fB\%archive_entry_acl_reset\fP()
|
|
has indicated the presence of extended ACL entries.
|
|
.PP
|
|
\fB\%archive_entry_acl_reset\fP()
|
|
prepare reading the list of ACL entries with
|
|
\fB\%archive_entry_acl_next\fP().
|
|
The function returns 0 if no non-extended ACLs are found.
|
|
In this case, the access permissions should be obtained by
|
|
\fBarchive_entry_mode\fP(3)
|
|
or set using
|
|
\fBchmod\fP(2).
|
|
Otherwise, the function returns the same value as
|
|
\fB\%archive_entry_acl_count\fP().
|
|
.PP
|
|
\fB\%archive_entry_acl_to_text\fP()
|
|
and
|
|
\fB\%archive_entry_acl_to_text_w\fP()
|
|
convert the ACL entries for the given type into a
|
|
(wide)
|
|
string of ACL entries separated by newline.
|
|
If the pointer
|
|
is not NULL, then the function shall return the length of the string
|
|
(not including the NULL terminator)
|
|
in the location pointed to by
|
|
.
|
|
The
|
|
argument is a bitwise-or.
|
|
.PP
|
|
The following flags are effective only on POSIX.1e ACL:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
|
Output access ACLs.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
|
Output POSIX.1e default ACLs.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
|
|
Prefix each default ACL entry with the word
|
|
``default:''.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
|
|
The mask and other ACLs don not contain a double colon.
|
|
.RE
|
|
.PP
|
|
The following flags are effecive only on NFSv4 ACL:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_STYLE_COMPACT
|
|
Do not output minus characters for unset permissions and flags in NFSv4 ACL
|
|
permission and flag fields.
|
|
.RE
|
|
.PP
|
|
The following flags are effective on both POSIX.1e and NFSv4 ACL:
|
|
.RS 5
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
|
|
Add an additional colon-separated field containing the user or group id.
|
|
.TP
|
|
.BR ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA
|
|
Separate ACL entries with comma instead of newline.
|
|
.RE
|
|
.PP
|
|
If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are returned.
|
|
It the entry contains POSIX.1e ACLs and none of the flags
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
|
or
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
|
|
are specified, both access and default entries are returned and default entries
|
|
are prefixed with
|
|
``default:''.
|
|
.PP
|
|
\fB\%archive_entry_acl_types\fP()
|
|
get ACL entry types contained in an archive entry's ACL.
|
|
As POSIX.1e and NFSv4
|
|
ACL entries cannot be mixed, this function is a very efficient way to detect if
|
|
an ACL already contains POSIX.1e or NFSv4 ACL entries.
|
|
.SH RETURN VALUES
|
|
.ad l
|
|
\fB\%archive_entry_acl_count\fP()
|
|
and
|
|
\fB\%archive_entry_acl_reset\fP()
|
|
returns the number of ACL entries that match the given type mask.
|
|
For POSIX.1e ACLS if the type mask includes
|
|
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
|
|
and at least one extended ACL entry exists, the three classic Unix
|
|
permissions are counted.
|
|
.PP
|
|
\fB\%archive_entry_acl_from_text\fP()
|
|
and
|
|
\fB\%archive_entry_acl_from_text_w\fP()
|
|
return
|
|
.BR ARCHIVE_OK
|
|
if all entries were successfully parsed and
|
|
.BR ARCHIVE_WARN
|
|
if one or more entries were invalid or non-parseable.
|
|
.PP
|
|
\fB\%archive_entry_acl_next\fP()
|
|
returns
|
|
.BR ARCHIVE_OK
|
|
on success,
|
|
.BR ARCHIVE_EOF
|
|
if no more ACL entries exist
|
|
and
|
|
.BR ARCHIVE_WARN
|
|
if
|
|
\fB\%archive_entry_acl_reset\fP()
|
|
has not been called first.
|
|
.PP
|
|
\fB\%archive_entry_acl_to_text\fP()
|
|
returns a string representing the ACL entries matching the given type and
|
|
flags on success or NULL on error.
|
|
.PP
|
|
\fB\%archive_entry_acl_to_text_w\fP()
|
|
returns a wide string representing the ACL entries matching the given type
|
|
and flags on success or NULL on error.
|
|
.PP
|
|
\fB\%archive_entry_acl_types\fP()
|
|
returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries.
|
|
.SH SEE ALSO
|
|
.ad l
|
|
\fBarchive_entry\fP(3),
|
|
\fBlibarchive\fP(3)
|