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