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