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