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