'\" te
.TH ARCHIVE_ENTRY_ACL 3 "February 2, 2012" ""
.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_next\fP,
\fB\%archive_entry_acl_next_w\fP,
\fB\%archive_entry_acl_reset\fP,
\fB\%archive_entry_acl_text_w\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_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_next_w\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\ wchar_t\ **ret_name\fP);
.br
\fIint\fP
.br
\fB\%archive_entry_acl_reset\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ type\fP);
.br
\fIconst wchar_t *\fP
.br
\fB\%archive_entry_acl_text_w\fP(\fI\%struct\ archive_entry\ *a\fP, \fI\%int\ flags\fP);
.SH DESCRIPTION
.ad l
An
``Access Control List''
is a generalisation of the classic Unix permission system.
The ACL interface of
\fB\%libarchive\fP
is derived from the POSIX.1e draft, but restricted to simplify dealing
with practical implementations in various Operating Systems and archive formats.
.PP
An ACL consists of a number of independent entries.
Each entry specifies the permission set as bitmask of basic permissions.
Valid permissions are:
.RS 5
.TP
.BR ARCHIVE_ENTRY_ACL_EXECUTE
.TP
.BR ARCHIVE_ENTRY_ACL_WRITE
.TP
.BR ARCHIVE_ENTRY_ACL_READ
.RE
The permissions correspond to the normal Unix permissions.
.PP
The tag specifies the principal to which the permission applies.
Valid values are:
.RS 5
.TP
.BR ARCHIVE_ENTRY_ACL_USER
The user specified by the name field.
.TP
.BR ARCHIVE_ENTRY_ACL_USER_OBJ
The owner of the file.
.TP
.BR ARCHIVE_ENTRY_ACL_GROUP
The group specied by the name field.
.TP
.BR ARCHIVE_ENTRY_ACL_GROUP_OBJ
The group who owns the file.
.TP
.BR ARCHIVE_ENTRY_ACL_MASK
The maximum permissions to be obtained via group permissions.
.TP
.BR ARCHIVE_ENTRY_ACL_OTHER
Any principal who doesn't have a user or group entry.
.RE
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.
.PP
\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.
.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
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
and
.BR ARCHIVE_ENTRY_ACL_TYPE_DEFAULT.
If
.BR ARCHIVE_ENTRY_ACL_TYPE_ACCESS
is included and at least one extended ACL entry is found,
the three non-extened ACLs are added.
.PP
\fB\%archive_entry_acl_next\fP()
and
\fB\%archive_entry_acl_next_w\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()
or
\fB\%archive_entry_acl_next_w\fP().
The function returns either 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_text_w\fP()
converts the ACL entries for the given type mask into a wide string.
In addition to the normal type flags,
.BR ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
and
.BR ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
can be specified to further customize the result.
The returned long string is valid until the next call to
\fB\%archive_entry_acl_clear\fP(),
\fB\%archive_entry_acl_add_entry\fP(),
\fB\%archive_entry_acl_add_entry_w\fP()
or
\fB\%archive_entry_acl_text_w\fP().
.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.
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_next\fP()
and
\fB\%archive_entry_acl_next_w\fP()
return
.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_text_w\fP()
returns a wide string representation of the ACL entrise matching the
given type mask.
The returned long string is valid until the next call to
\fB\%archive_entry_acl_clear\fP(),
\fB\%archive_entry_acl_add_entry\fP(),
\fB\%archive_entry_acl_add_entry_w\fP()
or
\fB\%archive_entry_acl_text_w\fP().

.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	library/libarchive
=
Stability	Uncommitted
.TE 
.PP
.SH SEE ALSO
.ad l
\fBarchive\fP(3),
\fBarchive_entry\fP(3)
.SH BUGS
.ad l
.BR ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
and
.BR ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
are not documented.


.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  http://www.libarchive.org/downloads/libarchive-3.1.2.tar.gz

Further information about this software can be found on the open source community website at http://www.libarchive.org/.