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