contrib/libarchive/libarchive/archive_read_disk.3

   1 .\" Copyright (c) 2003-2009 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 April 3, 2017
  28 .Dt ARCHIVE_READ_DISK 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_read_disk_new ,
  32 .Nm archive_read_disk_set_behavior ,
  33 .Nm archive_read_disk_set_symlink_logical ,
  34 .Nm archive_read_disk_set_symlink_physical ,
  35 .Nm archive_read_disk_set_symlink_hybrid ,
  36 .Nm archive_read_disk_entry_from_file ,
  37 .Nm archive_read_disk_gname ,
  38 .Nm archive_read_disk_uname ,
  39 .Nm archive_read_disk_set_uname_lookup ,
  40 .Nm archive_read_disk_set_gname_lookup ,
  41 .Nm archive_read_disk_set_standard_lookup
  42 .Nd functions for reading objects from disk
  43 .Sh LIBRARY
  44 Streaming Archive Library (libarchive, -larchive)
  45 .Sh SYNOPSIS
  46 .In archive.h
  47 .Ft struct archive *
  48 .Fn archive_read_disk_new "void"
  49 .Ft int
  50 .Fn archive_read_disk_set_behavior "struct archive *" "int"
  51 .Ft int
  52 .Fn archive_read_disk_set_symlink_logical "struct archive *"
  53 .Ft int
  54 .Fn archive_read_disk_set_symlink_physical "struct archive *"
  55 .Ft int
  56 .Fn archive_read_disk_set_symlink_hybrid "struct archive *"
  57 .Ft const char *
  58 .Fn archive_read_disk_gname "struct archive *" "gid_t"
  59 .Ft const char *
  60 .Fn archive_read_disk_uname "struct archive *" "uid_t"
  61 .Ft int
  62 .Fo archive_read_disk_set_gname_lookup
  63 .Fa "struct archive *"
  64 .Fa "void *"
  65 .Fa "const char *(*lookup)(void *, gid_t)"
  66 .Fa "void (*cleanup)(void *)"
  67 .Fc
  68 .Ft int
  69 .Fo archive_read_disk_set_uname_lookup
  70 .Fa "struct archive *"
  71 .Fa "void *"
  72 .Fa "const char *(*lookup)(void *, uid_t)"
  73 .Fa "void (*cleanup)(void *)"
  74 .Fc
  75 .Ft int
  76 .Fn archive_read_disk_set_standard_lookup "struct archive *"
  77 .Ft int
  78 .Fo archive_read_disk_entry_from_file
  79 .Fa "struct archive *"
  80 .Fa "struct archive_entry *"
  81 .Fa "int fd"
  82 .Fa "const struct stat *"
  83 .Fc
  84 .Sh DESCRIPTION
  85 These functions provide an API for reading information about
  86 objects on disk.
  87 In particular, they provide an interface for populating
  88 .Tn struct archive_entry
  89 objects.
  90 .Bl -tag -width indent
  91 .It Fn archive_read_disk_new
  92 Allocates and initializes a
  93 .Tn struct archive
  94 object suitable for reading object information from disk.
  95 .It Fn archive_read_disk_set_behavior
  96 Configures various behavior options when reading entries from disk.
  97 The flags field consists of a bitwise OR of one or more of the
  98 following values:
  99 .Bl -tag -compact -width "indent"
 100 .It Cm ARCHIVE_READDISK_HONOR_NODUMP
 101 Skip files and directories with the nodump file attribute (file flag) set.
 102 By default, the nodump file attribute is ignored.
 103 .It Cm ARCHIVE_READDISK_MAC_COPYFILE
 104 Mac OS X specific.
 105 Read metadata (ACLs and extended attributes) with
 106 .Xr copyfile 3 .
 107 By default, metadata is read using
 108 .Xr copyfile 3 .
 109 .It Cm ARCHIVE_READDISK_NO_ACL
 110 Do not read Access Control Lists.
 111 By default, ACLs are read from disk.
 112 .It Cm ARCHIVE_READDISK_NO_FFLAGS
 113 Do not read file attributes (file flags).
 114 By default, file attributes are read from disk.
 115 See
 116 .Xr chattr 1
 117 .Pq Linux
 118 or
 119 .Xr chflags 1
 120 .Pq FreeBSD, Mac OS X
 121 for more information on file attributes.
 122 .It Cm ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
 123 Do not traverse mount points.
 124 By default, mount points are traversed.
 125 .It Cm ARCHIVE_READDISK_NO_XATTR
 126 Do not read extended file attributes (xattrs).
 127 By default, extended file attributes are read from disk.
 128 See
 129 .Xr xattr 7
 130 .Pq Linux ,
 131 .Xr xattr 2
 132 .Pq Mac OS X ,
 133 or
 134 .Xr getextattr 8
 135 .Pq FreeBSD
 136 for more information on extended file attributes.
 137 .It Cm ARCHIVE_READDISK_RESTORE_ATIME
 138 Restore access time of traversed files.
 139 By default, access time of traversed files is not restored.
 140 .El
 141 .It Xo
 142 .Fn archive_read_disk_set_symlink_logical ,
 143 .Fn archive_read_disk_set_symlink_physical ,
 144 .Fn archive_read_disk_set_symlink_hybrid
 145 .Xc
 146 This sets the mode used for handling symbolic links.
 147 The
 148 .Dq logical
 149 mode follows all symbolic links.
 150 The
 151 .Dq physical
 152 mode does not follow any symbolic links.
 153 The
 154 .Dq hybrid
 155 mode currently behaves identically to the
 156 .Dq logical
 157 mode.
 158 .It Xo
 159 .Fn archive_read_disk_gname ,
 160 .Fn archive_read_disk_uname
 161 .Xc
 162 Returns a user or group name given a gid or uid value.
 163 By default, these always return a NULL string.
 164 .It Xo
 165 .Fn archive_read_disk_set_gname_lookup ,
 166 .Fn archive_read_disk_set_uname_lookup
 167 .Xc
 168 These allow you to override the functions used for
 169 user and group name lookups.
 170 You may also provide a
 171 .Tn void *
 172 pointer to a private data structure and a cleanup function for
 173 that data.
 174 The cleanup function will be invoked when the
 175 .Tn struct archive
 176 object is destroyed or when new lookup functions are registered.
 177 .It Fn archive_read_disk_set_standard_lookup
 178 This convenience function installs a standard set of user
 179 and group name lookup functions.
 180 These functions use
 181 .Xr getpwuid 3
 182 and
 183 .Xr getgrgid 3
 184 to convert ids to names, defaulting to NULL if the names cannot
 185 be looked up.
 186 These functions also implement a simple memory cache to reduce
 187 the number of calls to
 188 .Xr getpwuid 3
 189 and
 190 .Xr getgrgid 3 .
 191 .It Fn archive_read_disk_entry_from_file
 192 Populates a
 193 .Tn struct archive_entry
 194 object with information about a particular file.
 195 The
 196 .Tn archive_entry
 197 object must have already been created with
 198 .Xr archive_entry_new 3
 199 and at least one of the source path or path fields must already be set.
 200 (If both are set, the source path will be used.)
 201 .Pp
 202 Information is read from disk using the path name from the
 203 .Tn struct archive_entry
 204 object.
 205 If a file descriptor is provided, some information will be obtained using
 206 that file descriptor, on platforms that support the appropriate
 207 system calls.
 208 .Pp
 209 If a pointer to a
 210 .Tn struct stat
 211 is provided, information from that structure will be used instead
 212 of reading from the disk where appropriate.
 213 This can provide performance benefits in scenarios where
 214 .Tn struct stat
 215 information has already been read from the disk as a side effect
 216 of some other operation.
 217 (For example, directory traversal libraries often provide this information.)
 218 .Pp
 219 Where necessary, user and group ids are converted to user and group names
 220 using the currently-registered lookup functions above.
 221 This affects the file ownership fields and ACL values in the
 222 .Tn struct archive_entry
 223 object.
 224 .El
 225 More information about the
 226 .Va struct archive
 227 object and the overall design of the library can be found in the
 228 .Xr libarchive 3
 229 overview.
 230 .Sh EXAMPLES
 231 The following illustrates basic usage of the library by
 232 showing how to use it to copy an item on disk into an archive.
 233 .Bd -literal -offset indent
 234 void
 235 file_to_archive(struct archive *a, const char *name)
 236 {
 237   char buff[8192];
 238   size_t bytes_read;
 239   struct archive *ard;
 240   struct archive_entry *entry;
 241   int fd;
 242
 243   ard = archive_read_disk_new();
 244   archive_read_disk_set_standard_lookup(ard);
 245   entry = archive_entry_new();
 246   fd = open(name, O_RDONLY);
 247   if (fd < 0)
 248      return;
 249   archive_entry_copy_pathname(entry, name);
 250   archive_read_disk_entry_from_file(ard, entry, fd, NULL);
 251   archive_write_header(a, entry);
 252   while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
 253     archive_write_data(a, buff, bytes_read);
 254   archive_write_finish_entry(a);
 255   archive_read_free(ard);
 256   archive_entry_free(entry);
 257 }
 258 .Ed
 259 .Sh RETURN VALUES
 260 Most functions return
 261 .Cm ARCHIVE_OK
 262 (zero) on success, or one of several negative
 263 error codes for errors.
 264 Specific error codes include:
 265 .Cm ARCHIVE_RETRY
 266 for operations that might succeed if retried,
 267 .Cm ARCHIVE_WARN
 268 for unusual conditions that do not prevent further operations, and
 269 .Cm ARCHIVE_FATAL
 270 for serious errors that make remaining operations impossible.
 271 .Pp
 272 .Fn archive_read_disk_new
 273 returns a pointer to a newly-allocated
 274 .Tn struct archive
 275 object or NULL if the allocation failed for any reason.
 276 .Pp
 277 .Fn archive_read_disk_gname
 278 and
 279 .Fn archive_read_disk_uname
 280 return
 281 .Tn const char *
 282 pointers to the textual name or NULL if the lookup failed for any reason.
 283 The returned pointer points to internal storage that
 284 may be reused on the next call to either of these functions;
 285 callers should copy the string if they need to continue accessing it.
 286 .\"
 287 .Sh ERRORS
 288 Detailed error codes and textual descriptions are available from the
 289 .Fn archive_errno
 290 and
 291 .Fn archive_error_string
 292 functions.
 293 .\"
 294 .Sh SEE ALSO
 295 .Xr tar 1 ,
 296 .Xr archive_read 3 ,
 297 .Xr archive_util 3 ,
 298 .Xr archive_write 3 ,
 299 .Xr archive_write_disk 3 ,
 300 .Xr libarchive 3
 301 .Sh HISTORY
 302 The
 303 .Nm libarchive
 304 library first appeared in
 305 .Fx 5.3 .
 306 The
 307 .Nm archive_read_disk
 308 interface was added to
 309 .Nm libarchive 2.6
 310 and first appeared in
 311 .Fx 8.0 .
 312 .Sh AUTHORS
 313 .An -nosplit
 314 The
 315 .Nm libarchive
 316 library was written by
 317 .An Tim Kientzle Aq kientzle@FreeBSD.org .
 318 .Sh BUGS
 319 The
 320 .Dq standard
 321 user name and group name lookup functions are not the defaults because
 322 .Xr getgrgid 3
 323 and
 324 .Xr getpwuid 3
 325 are sometimes too large for particular applications.
 326 The current design allows the application author to use a more
 327 compact implementation when appropriate.
 328 .Pp
 329 The full list of metadata read from disk by
 330 .Fn archive_read_disk_entry_from_file
 331 is necessarily system-dependent.
 332 .Pp
 333 The
 334 .Fn archive_read_disk_entry_from_file
 335 function reads as much information as it can from disk.
 336 Some method should be provided to limit this so that clients who
 337 do not need ACLs, for instance, can avoid the extra work needed
 338 to look up such information.
 339 .Pp
 340 This API should provide a set of methods for walking a directory tree.
 341 That would make it a direct parallel of the
 342 .Xr archive_read 3
 343 API.
 344 When such methods are implemented, the
 345 .Dq hybrid
 346 symbolic link mode will make sense.