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