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