contrib/libarchive/archive_entry.3

   1 .\" Copyright (c) 2003-2004 Tim Kientzle
   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 .\" $FreeBSD: src/lib/libarchive/archive_entry.3,v 1.9 2004/08/08 07:39:19 kientzle Exp $
  26 .\"
  27 .Dd December 15, 2003
  28 .Dt archive_entry 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_entry_acl_add_entry ,
  32 .Nm archive_entry_acl_add_entry_w ,
  33 .Nm archive_entry_acl_clear ,
  34 .Nm archive_entry_acl_count ,
  35 .Nm archive_entry_acl_next ,
  36 .Nm archive_entry_acl_next_w ,
  37 .Nm archive_entry_acl_reset ,
  38 .Nm archive_entry_acl_text_w ,
  39 .Nm archive_entry_atime ,
  40 .Nm archive_entry_atime_nsec ,
  41 .Nm archive_entry_clear ,
  42 .Nm archive_entry_clone ,
  43 .Nm archive_entry_copy_fflags_text_w ,
  44 .Nm archive_entry_copy_gname_w ,
  45 .Nm archive_entry_copy_hardlink ,
  46 .Nm archive_entry_copy_hardlink_w ,
  47 .Nm archive_entry_copy_pathname_w ,
  48 .Nm archive_entry_copy_stat ,
  49 .Nm archive_entry_copy_symlink_w ,
  50 .Nm archive_entry_copy_uname_w ,
  51 .Nm archive_entry_dev ,
  52 .Nm archive_entry_fflags ,
  53 .Nm archive_entry_fflags_text ,
  54 .Nm archive_entry_free ,
  55 .Nm archive_entry_gid ,
  56 .Nm archive_entry_gname ,
  57 .Nm archive_entry_hardlink ,
  58 .Nm archive_entry_ino ,
  59 .Nm archive_entry_mode ,
  60 .Nm archive_entry_mtime ,
  61 .Nm archive_entry_mtime_nsec ,
  62 .Nm archive_entry_new ,
  63 .Nm archive_entry_pathname ,
  64 .Nm archive_entry_pathname_w ,
  65 .Nm archive_entry_rdev ,
  66 .Nm archive_entry_rdevmajor ,
  67 .Nm archive_entry_rdevminor ,
  68 .Nm archive_entry_set_fflags ,
  69 .Nm archive_entry_set_gid ,
  70 .Nm archive_entry_set_gname ,
  71 .Nm archive_entry_set_hardlink ,
  72 .Nm archive_entry_set_link ,
  73 .Nm archive_entry_set_mode ,
  74 .Nm archive_entry_set_mtime ,
  75 .Nm archive_entry_set_pathname ,
  76 .Nm archive_entry_set_rdevmajor ,
  77 .Nm archive_entry_set_rdevminor ,
  78 .Nm archive_entry_set_size ,
  79 .Nm archive_entry_set_symlink ,
  80 .Nm archive_entry_set_uid ,
  81 .Nm archive_entry_set_uname ,
  82 .Nm archive_entry_size ,
  83 .Nm archive_entry_stat ,
  84 .Nm archive_entry_symlink ,
  85 .Nm archive_entry_uid ,
  86 .Nm archive_entry_uname
  87 .Nd functions for manipulating archive entry descriptions
  88 .Sh SYNOPSIS
  89 .In archive_entry.h
  90 .Ft void
  91 .Fn archive_entry_acl_add_entry "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const char *name"
  92 .Ft void
  93 .Fn archive_entry_acl_add_entry_w "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const wchar_t *name"
  94 .Ft void
  95 .Fn archive_entry_acl_clear "struct archive_entry *"
  96 .Ft int
  97 .Fn archive_entry_acl_count "struct archive_entry *" "int type"
  98 .Ft int
  99 .Fn archive_entry_acl_next "struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const char **name"
 100 .Ft int
 101 .Fn archive_entry_acl_next_w "struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const wchar_t **name"
 102 .Ft void
 103 .Fn archive_entry_acl_reset "struct archive_entry *"
 104 .Ft const wchar_t *
 105 .Fn archive_entry_acl_text_w "struct archive_entry *" "int flags"
 106 .Ft time_t
 107 .Fn archive_entry_atime "struct archive_entry *"
 108 .Ft long
 109 .Fn archive_entry_atime_nsec "struct archive_entry *"
 110 .Ft void
 111 .Fn archive_entry_clear "struct archive_entry *"
 112 .Ft struct archive_entry *
 113 .Fn archive_entry_clone "struct archive_entry *"
 114 .Ft const wchar_t *
 115 .Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const wchar_t *"
 116 .Ft void
 117 .Fn archive_entry_copy_gname_w "struct archive_entry *" "const wchar_t *"
 118 .Ft void
 119 .Fn archive_entry_copy_hardlink "struct archive_entry *" "const char *"
 120 .Ft void
 121 .Fn archive_entry_copy_hardlink_w "struct archive_entry *" "const wchar_t *"
 122 .Ft void
 123 .Fn archive_entry_copy_pathname_w "struct archive_entry *" "const wchar_t *"
 124 .Ft void
 125 .Fn archive_entry_copy_stat "struct archive_entry *" "struct stat *"
 126 .Ft void
 127 .Fn archive_entry_copy_symlink_w "struct archive_entry *" "const wchar_t *"
 128 .Ft void
 129 .Fn archive_entry_copy_uname_w "struct archive_entry *" "const wchar_t *"
 130 .Ft dev_t
 131 .Fn archive_entry_dev "struct archive_entry *"
 132 .Ft void
 133 .Fn archive_entry_fflags "struct archive_entry *" "unsigned long *set" "unsigned long *clear"
 134 .Ft const char *
 135 .Fn archive_entry_fflags_text "struct archive_entry *"
 136 .Ft void
 137 .Fn archive_entry_free "struct archive_entry *"
 138 .Ft const char *
 139 .Fn archive_entry_gname "struct archive_entry *"
 140 .Ft const char *
 141 .Fn archive_entry_hardlink "struct archive_entry *"
 142 .Ft ino_t
 143 .Fn archive_entry_ino "struct archive_entry *"
 144 .Ft mode_t
 145 .Fn archive_entry_mode "struct archive_entry *"
 146 .Ft time_t
 147 .Fn archive_entry_mtime "struct archive_entry *"
 148 .Ft long
 149 .Fn archive_entry_mtime_nsec "struct archive_entry *"
 150 .Ft struct archive_entry *
 151 .Fn archive_entry_new "void"
 152 .Ft const char *
 153 .Fn archive_entry_pathname "struct archive_entry *"
 154 .Ft const wchar_t *
 155 .Fn archive_entry_pathname_w "struct archive_entry *"
 156 .Ft dev_t
 157 .Fn archive_entry_rdev "struct archive_entry *"
 158 .Ft dev_t
 159 .Fn archive_entry_rdevmajor "struct archive_entry *"
 160 .Ft dev_t
 161 .Fn archive_entry_rdevminor "struct archive_entry *"
 162 .Ft void
 163 .Fn archive_entry_set_fflags "struct archive_entry *" "unsigned long set" "unsigned long clear"
 164 .Ft void
 165 .Fn archive_entry_set_gid "struct archive_entry *" "gid_t"
 166 .Ft void
 167 .Fn archive_entry_set_gname "struct archive_entry *" "const char *"
 168 .Ft void
 169 .Fn archive_entry_set_hardlink "struct archive_entry *" "const char *"
 170 .Ft void
 171 .Fn archive_entry_set_link "struct archive_entry *" "const char *"
 172 .Ft void
 173 .Fn archive_entry_set_mode "struct archive_entry *" "mode_t"
 174 .Ft void
 175 .Fn archive_entry_set_mtime "struct archive_entry *" "time_t" "long nanos"
 176 .Ft void
 177 .Fn archive_entry_set_pathname "struct archive_entry *" "const char *"
 178 .Ft void
 179 .Fn archive_entry_set_rdevmajor "struct archive_entry *" "dev_t"
 180 .Ft void
 181 .Fn archive_entry_set_rdevminor "struct archive_entry *" "dev_t"
 182 .Ft void
 183 .Fn archive_entry_set_size "struct archive_entry *" "int64_t"
 184 .Ft void
 185 .Fn archive_entry_set_symlink "struct archive_entry *" "const char *"
 186 .Ft void
 187 .Fn archive_entry_set_uid "struct archive_entry *" "uid_t"
 188 .Ft void
 189 .Fn archive_entry_set_uname "struct archive_entry *" "const char *"
 190 .Ft int64_t
 191 .Fn archive_entry_size "struct archive_entry *"
 192 .Ft const struct stat *
 193 .Fn archive_entry_stat "struct archive_entry *"
 194 .Ft const char *
 195 .Fn archive_entry_symlink "struct archive_entry *"
 196 .Ft const char *
 197 .Fn archive_entry_uname "struct archive_entry *"
 198 .Sh DESCRIPTION
 199 These functions create and manipulate data objects that
 200 represent entries within an archive.
 201 You can think of a
 202 .Tn struct archive_entry
 203 as a heavy-duty version of
 204 .Tn struct stat :
 205 it includes everything from
 206 .Tn struct stat
 207 plus associated pathname, textual group and user names, etc.
 208 These objects are used by
 209 .Xr libarchive 3
 210 to represent the metadata associated with a particular
 211 entry in an archive.
 212 .Ss Create and Destroy
 213 There are functions to allocate, destroy, clear, and copy
 214 .Va archive_entry
 215 objects:
 216 .Bl -tag -compact -width indent
 217 .It Fn archive_entry_clear
 218 Erases the object, resetting all internal fields to the
 219 same state as a newly-created object.
 220 This is provided to allow you to quickly recycle objects
 221 without thrashing the heap.
 222 .It Fn archive_entry_clone
 223 A deep copy operation; all text fields are duplicated.
 224 .It Fn archive_entry_free
 225 Releases the
 226 .Tn struct archive_entry
 227 object.
 228 .It Fn archive_entry_new
 229 Allocate and return a blank
 230 .Tn struct archive_entry
 231 object.
 232 .El
 233 .Ss Set and Get Functions
 234 Most of the functions here set or read entries in an object.
 235 Such functions have one of the following forms:
 236 .Bl -tag -compact -width indent
 237 .It Fn archive_entry_set_XXXX
 238 Stores the provided data in the object.
 239 In particular, for strings, the pointer is stored,
 240 not the referenced string.
 241 .It Fn archive_entry_copy_XXXX
 242 As above, except that the referenced data is copied
 243 into the object.
 244 .It Fn archive_entry_XXXX
 245 Returns the specified data.
 246 In the case of strings, a const-qualified pointer to
 247 the string is returned.
 248 .El
 249 String data can be set or accessed as wide character strings
 250 or normal
 251 .Va char
 252 strings.
 253 The funtions that use wide character strings are suffixed with
 254 .Cm _w .
 255 Note that these are different representations of the same data:
 256 For example, if you store a narrow string and read the corresponding
 257 wide string, the object will transparently convert formats
 258 using the current locale.
 259 Similarly, if you store a wide string and then store a
 260 narrow string for the same data, the previously-set wide string will
 261 be discarded in favor of the new data.
 262 .Pp
 263 There are a few set/get functions that merit additional description:
 264 .Bl -tag -compact -width indent
 265 .It Fn archive_entry_set_link
 266 This function sets the symlink field if it is already set.
 267 Otherwise, it sets the hardlink field.
 268 .El
 269 .Ss File Flags
 270 File flags are transparently converted between a bitmap
 271 representation and a textual format.
 272 For example, if you set the bitmap and ask for text, the library
 273 will build a canonical text format.
 274 However, if you set a text format and request a text format,
 275 you will get back the same text, even if it is ill-formed.
 276 If you need to canonicalize a textual flags string, you should first set the
 277 text form, then request the bitmap form, then use that to set the bitmap form.
 278 Setting the bitmap format will clear the internal text representation
 279 and force it to be reconstructed when you next request the text form.
 280 .Pp
 281 The bitmap format consists of two integers, one containing bits
 282 that should be set, the other specifying bits that should be
 283 cleared.
 284 Bits not mentioned in either bitmap will be ignored.
 285 Usually, the bitmap of bits to be cleared will be set to zero.
 286 In unusual circumstances, you can force a fully-specified set
 287 of file flags by setting the bitmap of flags to clear to the complement
 288 of the bitmap of flags to set.
 289 (This differs from
 290 .Xr fflagstostr 3 ,
 291 which only includes names for set bits.)
 292 Converting a bitmap to a textual string is a platform-specific
 293 operation; bits that are not meaningful on the current platform
 294 will be ignored.
 295 .Pp
 296 The canonical text format is a comma-separated list of flag names.
 297 The
 298 .Fn archive_entry_copy_fflags_text_w
 299 function parses the provided text and sets the internal bitmap values.
 300 This is a platform-specific operation; names that are not meaningful
 301 on the current platform will be ignored.
 302 The function returns a pointer to the start of the first name that was not
 303 recognized, or NULL if every name was recognized.
 304 Note that every name--including names that follow an unrecognized name--will
 305 be evaluated, and the bitmaps will be set to reflect every name that is
 306 recognized.
 307 (In particular, this differs from
 308 .Xr strtofflags 3 ,
 309 which stops parsing at the first unrecognized name.)
 310 .Ss ACL Handling
 311 XXX This needs serious help.
 312 XXX
 313 .Pp
 314 An
 315 .Dq Access Control List
 316 (ACL) is a list of permissions that grant access to particular users or
 317 groups beyond what would normally be provided by standard POSIX mode bits.
 318 The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL
 319 specification.
 320 In particular, POSIX.1e draft 17 specifies several different formats, but
 321 none of those formats include both textual user/group names and numeric
 322 UIDs/GIDs.
 323 .Pp
 324 XXX explain ACL stuff XXX
 325 .\" .Sh EXAMPLE
 326 .\" .Sh RETURN VALUES
 327 .\" .Sh ERRORS
 328 .Sh SEE ALSO
 329 .Xr archive 3
 330 .Sh HISTORY
 331 The
 332 .Nm libarchive
 333 library first appeared in
 334 .Fx 5.3 .
 335 .Sh AUTHORS
 336 .An -nosplit
 337 The
 338 .Nm libarchive
 339 library was written by
 340 .An Tim Kientzle Aq kientzle@acm.org .
 341 .\" .Sh BUGS