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
       An NFSv4 ACL consists of multiple individual entries called Access Con‐
       trol Entries (ACEs).

       There are four possible types of an 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  permis‐
					   sions.
	     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
					   attempts 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() returns the next entry of the ACL list.   This
       function	 may  only be called after 1marchive_entry_acl_reset22m() has indi‐
       cated the presence of extended ACL entries.

       1marchive_entry_acl_reset22m() prepares 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 do 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.  If 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() gets 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() return 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  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)
