4mARCHIVE_ENTRY_ACL24m(3)	 Library Functions Manual      4mARCHIVE_ENTRY_ACL24m(3)

1mNAME0m
       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

1mLIBRARY0m
       Streaming Archive Library (libarchive, -larchive)

1mSYNOPSIS0m
       1m#include <archive_entry.h>0m

       4mvoid0m
       1marchive_entry_acl_add_entry22m(4mstruct24m 4marchive_entry24m 4m*a24m,		 4mint24m 4mtype24m,
	   4mint24m 4mpermset24m, 4mint24m 4mtag24m, 4mint24m 4mqualifier24m, 4mconst24m 4mchar24m 4m*name24m);

       4mvoid0m
       1marchive_entry_acl_add_entry_w22m(4mstruct24m 4marchive_entry24m 4m*a24m,	 4mint24m 4mtype24m,
	   4mint24m 4mpermset24m, 4mint24m 4mtag24m, 4mint24m 4mqualifier24m, 4mconst24m 4mwchar_t24m 4m*name24m);

       4mvoid0m
       1marchive_entry_acl_clear22m(4mstruct24m 4marchive_entry24m 4m*a24m);

       4mint0m
       1marchive_entry_acl_count22m(4mstruct24m 4marchive_entry24m 4m*a24m, 4mint24m 4mtype24m);

       4mint0m
       1marchive_entry_acl_from_text22m(4mstruct24m 4marchive_entry24m 4m*a24m,	 4mconst24m 4mchar24m 4m*text24m,
	   4mint24m 4mtype24m);

       4mint0m
       1marchive_entry_acl_from_text_w22m(4mstruct24m 4marchive_entry24m 4m*a24m,
	   4mconst24m 4mwchar_t24m 4m*text24m, 4mint24m 4mtype24m);

       4mint0m
       1marchive_entry_acl_next22m(4mstruct24m 4marchive_entry24m 4m*a24m,		 4mint24m 4mtype24m,
	   4mint24m 4m*ret_type24m,   4mint24m 4m*ret_permset24m,   4mint24m 4m*ret_tag24m,   4mint24m 4m*ret_qual24m,
	   4mconst24m 4mchar24m 4m**ret_name24m);

       4mint0m
       1marchive_entry_acl_reset22m(4mstruct24m 4marchive_entry24m 4m*a24m, 4mint24m 4mtype24m);

       4mchar24m 4m*0m
       1marchive_entry_acl_to_text22m(4mstruct24m 4marchive_entry24m 4m*a24m,	   4mssize_t24m 4m*len_p24m,
	   4mint24m 4mflags24m);

       4mwchar_t24m 4m*0m
       1marchive_entry_acl_to_text_w22m(4mstruct24m 4marchive_entry24m 4m*a24m,	   4mssize_t24m 4m*len_p24m,
	   4mint24m 4mflags24m);

       4mint0m
       1marchive_entry_acl_types22m(4mstruct24m 4marchive_entry24m 4m*a24m);

1mDESCRIPTION0m
       The “Access Control Lists (ACLs)” extend the standard  Unix  permission
       model.	The  ACL  interface  of	 1mlibarchive 22msupports 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.

   1mPOSIX.1e Access Control Lists0m
       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 4mpermset24m are:
	     ARCHIVE_ENTRY_ACL_READ (1mr22m)
	     ARCHIVE_ENTRY_ACL_WRITE (1mw22m)
	     ARCHIVE_ENTRY_ACL_EXECUTE (1mx22m)
       The permissions correspond to the normal Unix permissions.

       The 4mtag24m 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  ob‐
					  tained 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
       specifies the permissions required for access to the file itself.   Di‐
       rectories  have	an  additional	ACL  (ARCHIVE_ENTRY_ACL_TYPE_DEFAULT),
       which controls the initial access ACL for newly-created	directory  en‐
       tries.

   1mNFSv4 Access Control Lists0m
       A  NFSv4 ACL consists of multiple individual entries called Access Con‐
       trol Entries (ACEs).

       There are four possible types of a NFSv4 ACE:
	     ARCHIVE_ENTRY_ACL_TYPE_ALLOW Allow principal to  perform  actions
					  requiring given permissions.
	     ARCHIVE_ENTRY_ACL_TYPE_DENY  Prevent  principal  from  performing
					  actions 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 4mtag24m 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 4mname24m string and optionally the
       user or group ID in the 4mqualifier24m integer.

       NFSv4 ACE permissions and flags are stored in  the  same	 4mpermset24m  bit‐
       field.  Some permissions share the same constant and permission charac‐
       ter  but	 have different effect on directories than on files.  The fol‐
       lowing ACE permissions are supported:
	     ARCHIVE_ENTRY_ACL_READ_DATA (1mr22m)
		     Read data (file).
	     ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (1mr22m)
		     List entries (directory).
	     ARCHIVE_ENTRY_ACL_WRITE_DATA (1mw22m)
		     Write data (file).
	     ARCHIVE_ENTRY_ACL_ADD_FILE (1mw22m)
		     Create files (directory).
	     ARCHIVE_ENTRY_ACL_EXECUTE (1mx22m)
		     Execute file or change into a directory.
	     ARCHIVE_ENTRY_ACL_APPEND_DATA (1mp22m)
		     Append data (file).
	     ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (1mp22m)
		     Create subdirectories (directory).
	     ARCHIVE_ENTRY_ACL_DELETE_CHILD (1mD22m)
		     Remove files and subdirectories inside a directory.
	     ARCHIVE_ENTRY_ACL_DELETE (1md22m)
		     Remove file or directory.
	     ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (1ma22m)
		     Read file or directory attributes.
	     ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (1mA22m)
		     Write file or directory attributes.
	     ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (1mR22m)
		     Read named file or directory attributes.
	     ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (1mW22m)
		     Write named file or directory attributes.
	     ARCHIVE_ENTRY_ACL_READ_ACL (1mc22m)
		     Read file or directory ACL.
	     ARCHIVE_ENTRY_ACL_WRITE_ACL (1mC22m)
		     Write file or directory ACL.
	     ARCHIVE_ENTRY_ACL_WRITE_OWNER (1mo22m)
		     Change owner of a file or directory.
	     ARCHIVE_ENTRY_ACL_SYNCHRONIZE (1ms22m)
		     Use synchronous I/O.

       The following NFSv4 ACL inheritance flags are supported:
	     ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (1mf22m)
		     Inherit parent directory ACE to files.
	     ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (1md22m)
		     Inherit parent directory ACE to subdirectories.
	     ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (1mi22m)
		     Only inherit, do not apply the permission on  the	direc‐
		     tory itself.
	     ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (1mn22m)
		     Do not propagate inherit flags.  Only first-level entries
		     inherit ACLs.
	     ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (1mS22m)
		     Trigger alarm or audit on successful access.
	     ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (1mF22m)
		     Trigger alarm or audit on failed access.
	     ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (1mI22m)
		     Mark that ACE was inherited.

   1mFunctions0m
       1marchive_entry_acl_add_entry22m() and 1marchive_entry_acl_add_entry_w22m() 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.

       1marchive_entry_acl_clear22m()  removes	all ACL entries and resets the enu‐
       meration pointer.

       1marchive_entry_acl_count22m() counts the ACL entries that  have	 the  given
       type mask.  4mtype24m 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-
       extended ACLs are added.

       1marchive_entry_acl_from_text22m()  and	1marchive_entry_acl_from_text_w22m() add
       new (or merge with existing) ACL entries from (wide) text.   The	 argu‐
       ment 4mtype24m 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
       1marchive_entry_acl_to_text22m()		      or	       respectively
       1marchive_entry_acl_to_text_w22m().  Existing ACL entries are preserved.	 To
       get  a clean new ACL from text 1marchive_entry_acl_clear22m() must be called
       first.	 Entries   prefixed   with   “default:”	  are	 treated    as
       ARCHIVE_ENTRY_ACL_TYPE_DEFAULT	       unless	       4mtype24m	 is
       ARCHIVE_ENTRY_ACL_TYPE_NFS4.  Invalid entries,  non-parseable  ACL  en‐
       tries  and  entries  beginning  with  the  ‘#’ character (comments) are
       skipped.

       1marchive_entry_acl_next22m() return the next entry of the ACL  list.   This
       functions  may only be called after 1marchive_entry_acl_reset22m() has indi‐
       cated the presence of extended ACL entries.

       1marchive_entry_acl_reset22m() prepare reading the list of ACL entries  with
       1marchive_entry_acl_next22m().	The  function  returns 0 if no non-extended
       ACLs are found.	In this case, the access  permissions  should  be  ob‐
       tained  by 4marchive_entry_mode24m(3) or set using 4mchmod24m(2).  Otherwise, the
       function returns the same value as 1marchive_entry_acl_count22m().

       1marchive_entry_acl_to_text22m() and  1marchive_entry_acl_to_text_w22m()	 convert
       the  ACL entries for the given type into a (wide) string of ACL entries
       separated by newline.  If the pointer 4mlen_p24m is not NULL, then the func‐
       tion shall return the length of the  string  (not  including  the  NULL
       terminator)  in the location pointed to by 4mlen_p24m.  The 4mflag24m 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 effective 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
       returned.   It  the  entry contains POSIX.1e ACLs and none of the flags
       ARCHIVE_ENTRY_ACL_TYPE_ACCESS  or  ARCHIVE_ENTRY_ACL_TYPE_DEFAULT   are
       specified, both access and default entries are returned and default en‐
       tries are prefixed with “default:”.

       1marchive_entry_acl_types22m()  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.

1mRETURN VALUES0m
       1marchive_entry_acl_count22m()  and  1marchive_entry_acl_reset22m()  returns  the
       number  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 extended ACL entry exists, the three classic Unix permissions
       are counted.

       1marchive_entry_acl_from_text22m()  and	1marchive_entry_acl_from_text_w22m() re‐
       turn  ARCHIVE_OK	 if  all  entries   were   successfully	  parsed   and
       ARCHIVE_WARN if one or more entries were invalid or non-parseable.

       1marchive_entry_acl_next22m()  returns ARCHIVE_OK on success, ARCHIVE_EOF if
       no more ACL entries exist and ARCHIVE_WARN if 1marchive_entry_acl_reset22m()
       has not been called first.

       1marchive_entry_acl_to_text22m() returns a string representing the  ACL	en‐
       tries matching the given type and flags on success or NULL on error.

       1marchive_entry_acl_to_text_w22m()  returns  a  wide string representing the
       ACL entries matching the given type and flags on success or NULL on er‐
       ror.

       1marchive_entry_acl_types22m() returns a bitmask of ACL entry types or 0	 if
       archive entry has no ACL entries.

1mSEE ALSO0m
       4marchive_entry24m(3), 4mlibarchive24m(3)

Debian			       February 15, 2017	  4mARCHIVE_ENTRY_ACL24m(3)
