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