contrib/libarchive/libarchive/archive_entry_acl.3

   1 .\" Copyright (c) 2010 Joerg Sonnenberger
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd February 2, 2012
  26 .Dt ARCHIVE_ENTRY_ACL 3
  27 .Os
  28 .Sh NAME
  29 .Nm archive_entry_acl_add_entry ,
  30 .Nm archive_entry_acl_add_entry_w ,
  31 .Nm archive_entry_acl_clear ,
  32 .Nm archive_entry_acl_count ,
  33 .Nm archive_entry_acl_next ,
  34 .Nm archive_entry_acl_next_w ,
  35 .Nm archive_entry_acl_reset ,
  36 .Nm archive_entry_acl_text_w ,
  37 .Nm archive_entry_acl_types
  38 .Nd functions for manipulating Access Control Lists in archive entry descriptions
  39 .Sh LIBRARY
  40 Streaming Archive Library (libarchive, -larchive)
  41 .Sh SYNOPSIS
  42 .In archive_entry.h
  43 .Ft void
  44 .Fo archive_entry_acl_add_entry
  45 .Fa "struct archive_entry *a"
  46 .Fa "int type"
  47 .Fa "int permset"
  48 .Fa "int tag"
  49 .Fa "int qualifier"
  50 .Fa "const char *name"
  51 .Fc
  52 .Ft void
  53 .Fo archive_entry_acl_add_entry_w
  54 .Fa "struct archive_entry *a"
  55 .Fa "int type"
  56 .Fa "int permset"
  57 .Fa "int tag"
  58 .Fa "int qualifier"
  59 .Fa "const wchar_t *name"
  60 .Fc
  61 .Ft void
  62 .Fn archive_entry_acl_clear "struct archive_entry *a"
  63 .Ft int
  64 .Fn archive_entry_acl_count "struct archive_entry *a" "int type"
  65 .Ft int
  66 .Fo archive_entry_acl_next
  67 .Fa "struct archive_entry *a"
  68 .Fa "int type"
  69 .Fa "int *ret_type"
  70 .Fa "int *ret_permset"
  71 .Fa "int *ret_tag"
  72 .Fa "int *ret_qual"
  73 .Fa "const char **ret_name"
  74 .Fc
  75 .Ft int
  76 .Fo archive_entry_acl_next_w
  77 .Fa "struct archive_entry *a"
  78 .Fa "int type"
  79 .Fa "int *ret_type"
  80 .Fa "int *ret_permset"
  81 .Fa "int *ret_tag"
  82 .Fa "int *ret_qual"
  83 .Fa "const wchar_t **ret_name"
  84 .Fc
  85 .Ft int
  86 .Fn archive_entry_acl_reset "struct archive_entry *a" "int type"
  87 .Ft const wchar_t *
  88 .Fn archive_entry_acl_text_w "struct archive_entry *a" "int flags"
  89 .Ft int
  90 .Fn archive_entry_acl_types "struct archive_entry *a"
  91 .\" enum?
  92 .Sh DESCRIPTION
  93 An
  94 .Dq Access Control List
  95 is a generalisation of the classic Unix permission system.
  96 The ACL interface of
  97 .Nm libarchive
  98 is derived from the POSIX.1e draft, but restricted to simplify dealing
  99 with practical implementations in various Operating Systems and archive formats.
 100 .Pp
 101 An ACL consists of a number of independent entries.
 102 Each entry specifies the permission set as bitmask of basic permissions.
 103 Valid permissions are:
 104 .Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_EXECUTE"
 105 .It Dv ARCHIVE_ENTRY_ACL_EXECUTE
 106 .It Dv ARCHIVE_ENTRY_ACL_WRITE
 107 .It Dv ARCHIVE_ENTRY_ACL_READ
 108 .El
 109 The permissions correspond to the normal Unix permissions.
 110 .Pp
 111 The tag specifies the principal to which the permission applies.
 112 Valid values are:
 113 .Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ"
 114 .It Dv ARCHIVE_ENTRY_ACL_USER
 115 The user specified by the name field.
 116 .It Dv ARCHIVE_ENTRY_ACL_USER_OBJ
 117 The owner of the file.
 118 .It Dv ARCHIVE_ENTRY_ACL_GROUP
 119 The group specied by the name field.
 120 .It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ
 121 The group who owns the file.
 122 .It Dv ARCHIVE_ENTRY_ACL_MASK
 123 The maximum permissions to be obtained via group permissions.
 124 .It Dv ARCHIVE_ENTRY_ACL_OTHER
 125 Any principal who doesn't have a user or group entry.
 126 .El
 127 The principals
 128 .Dv ARCHIVE_ENTRY_ACL_USER_OBJ ,
 129 .Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ
 130 and
 131 .Dv ARCHIVE_ENTRY_ACL_OTHER
 132 are equivalent to user, group and other in the classic Unix permission
 133 model and specify non-extended ACL entries.
 134 .Pp
 135 All files have an access ACL
 136 .Pq Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS .
 137 This specifies the permissions required for access to the file itself.
 138 Directories have an additional ACL
 139 .Pq Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT ,
 140 which controls the initial access ACL for newly created directory entries.
 141 .Pp
 142 .Fn archive_entry_acl_add_entry
 143 and
 144 .Fn archive_entry_acl_add_entry_w
 145 add a single ACL entry.
 146 For the access ACL and non-extended principals, the classic Unix permissions
 147 are updated.
 148 .Pp
 149 .Fn archive_entry_acl_clear
 150 removes all ACL entries and resets the enumeration pointer.
 151 .Pp
 152 .Fn archive_entry_acl_count
 153 counts the ACL entries that have the given type mask.
 154 .Fa type
 155 can be the bitwise-or of
 156 .Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS
 157 and
 158 .Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT .
 159 If
 160 .Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS
 161 is included and at least one extended ACL entry is found,
 162 the three non-extened ACLs are added.
 163 .Pp
 164 .Fn archive_entry_acl_next
 165 and
 166 .Fn archive_entry_acl_next_w
 167 return the next entry of the ACL list.
 168 This functions may only be called after
 169 .Fn archive_entry_acl_reset
 170 has indicated the presence of extended ACL entries.
 171 .Pp
 172 .Fn archive_entry_acl_reset
 173 prepare reading the list of ACL entries with
 174 .Fn archive_entry_acl_next
 175 or
 176 .Fn archive_entry_acl_next_w .
 177 The function returns either 0, if no non-extended ACLs are found.
 178 In this case, the access permissions should be obtained by
 179 .Xr archive_entry_mode 3
 180 or set using
 181 .Xr chmod 2 .
 182 Otherwise, the function returns the same value as
 183 .Fn archive_entry_acl_count .
 184 .Pp
 185 .Fn archive_entry_acl_text_w
 186 converts the ACL entries for the given type mask into a wide string.
 187 In addition to the normal type flags,
 188 .Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
 189 and
 190 .Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
 191 can be specified to further customize the result.
 192 The returned long string is valid until the next call to
 193 .Fn archive_entry_acl_clear ,
 194 .Fn archive_entry_acl_add_entry ,
 195 .Fn archive_entry_acl_add_entry_w
 196 or
 197 .Fn archive_entry_acl_text_w .
 198 .Pp
 199 .Fn archive_entry_acl_types
 200 get ACL entry types contained in an archive entry's ACL. As POSIX.1e and NFSv4
 201 ACL entries cannot be mixed, this function is a very efficient way to detect if
 202 an ACL already contains POSIX.1e or NFSv4 ACL entries.
 203 .Sh RETURN VALUES
 204 .Fn archive_entry_acl_count
 205 and
 206 .Fn archive_entry_acl_reset
 207 returns the number of ACL entries that match the given type mask.
 208 If the type mask includes
 209 .Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS
 210 and at least one extended ACL entry exists, the three classic Unix
 211 permissions are counted.
 212 .Pp
 213 .Fn archive_entry_acl_next
 214 and
 215 .Fn archive_entry_acl_next_w
 216 return
 217 .Dv ARCHIVE_OK
 218 on success,
 219 .Dv ARCHIVE_EOF
 220 if no more ACL entries exist
 221 and
 222 .Dv ARCHIVE_WARN
 223 if
 224 .Fn archive_entry_acl_reset
 225 has not been called first.
 226 .Pp
 227 .Fn archive_entry_text_w
 228 returns a wide string representation of the ACL entrise matching the
 229 given type mask.
 230 The returned long string is valid until the next call to
 231 .Fn archive_entry_acl_clear ,
 232 .Fn archive_entry_acl_add_entry ,
 233 .Fn archive_entry_acl_add_entry_w
 234 or
 235 .Fn archive_entry_acl_text_w .
 236 .Pp
 237 .Fn archive_entry_acl_types
 238 returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries.
 239 .Sh SEE ALSO
 240 .Xr archive_entry 3
 241 .Xr libarchive 3 ,
 242 .Sh BUGS
 243 .Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
 244 and
 245 .Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
 246 are not documented.