lib/libarchive/archive_entry.3

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