doc/html/archive_read_disk.3.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!-- CreationDate: Sun Feb 19 09:11:16 2017 -->
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   4 "http://www.w3.org/TR/html4/loose.dtd">
   5 <html>
   6 <head>
   7 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   8 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   9 <meta name="Content-Style" content="text/css">
  10 <style type="text/css">
  11        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
  12        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
  13        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
  14        h1      { text-align: center }
  15 </style>
  16 <title></title>
  17 </head>
  18 <body>
  19
  20 <hr>
  21
  22
  23 <p>ARCHIVE_READ_DISK(3) BSD Library Functions Manual
  24 ARCHIVE_READ_DISK(3)</p>
  25
  26 <p style="margin-top: 1em"><b>NAME</b></p>
  27
  28 <p style="margin-left:6%;"><b>archive_read_disk_new</b>,
  29 <b>archive_read_disk_set_symlink_logical</b>,
  30 <b>archive_read_disk_set_symlink_physical</b>,
  31 <b>archive_read_disk_set_symlink_hybrid</b>,
  32 <b>archive_read_disk_entry_from_file</b>,
  33 <b>archive_read_disk_gname</b>,
  34 <b>archive_read_disk_uname</b>,
  35 <b>archive_read_disk_set_uname_lookup</b>,
  36 <b>archive_read_disk_set_gname_lookup</b>,
  37 <b>archive_read_disk_set_standard_lookup</b>,
  38 <b>archive_read_close</b>, <b>archive_read_finish</b>,
  39 <b>archive_read_free</b> &mdash; functions for reading
  40 objects from disk</p>
  41
  42 <p style="margin-top: 1em"><b>LIBRARY</b></p>
  43
  44 <p style="margin-left:6%;">Streaming Archive Library
  45 (libarchive, -larchive)</p>
  46
  47 <p style="margin-top: 1em"><b>SYNOPSIS</b></p>
  48
  49 <p style="margin-left:6%;"><b>#include
  50 &lt;archive.h&gt;</b></p>
  51
  52 <p style="margin-left:6%; margin-top: 1em"><i>struct
  53 archive *</i></p>
  54
  55
  56 <p style="margin-left:12%;"><b>archive_read_disk_new</b>(<i>void</i>);</p>
  57
  58 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  59
  60
  61 <p style="margin-left:12%;"><b>archive_read_disk_set_symlink_logical</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  62
  63 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  64
  65
  66 <p style="margin-left:12%;"><b>archive_read_disk_set_symlink_physical</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  67
  68 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  69
  70
  71 <p style="margin-left:12%;"><b>archive_read_disk_set_symlink_hybrid</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
  72
  73 <p style="margin-left:6%; margin-top: 1em"><i>const char
  74 *</i></p>
  75
  76
  77 <p style="margin-left:12%;"><b>archive_read_disk_gname</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  78 <i>gid_t</i>);</p>
  79
  80 <p style="margin-left:6%; margin-top: 1em"><i>const char
  81 *</i></p>
  82
  83
  84 <p style="margin-left:12%;"><b>archive_read_disk_uname</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  85 <i>uid_t</i>);</p>
  86
  87 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  88
  89
  90 <p><b>archive_read_disk_set_gname_lookup</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  91 <i>void&nbsp;*</i>,
  92 <i>const&nbsp;char&nbsp;*(*lookup)(void&nbsp;*,&nbsp;gid_t)</i>,
  93 <i>void&nbsp;(*cleanup)(void&nbsp;*)</i>);</p>
  94
  95 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  96
  97
  98 <p><b>archive_read_disk_set_uname_lookup</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  99 <i>void&nbsp;*</i>,
 100 <i>const&nbsp;char&nbsp;*(*lookup)(void&nbsp;*,&nbsp;uid_t)</i>,
 101 <i>void&nbsp;(*cleanup)(void&nbsp;*)</i>);</p>
 102
 103 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
 104
 105
 106 <p style="margin-left:12%;"><b>archive_read_disk_set_standard_lookup</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
 107
 108 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
 109
 110
 111 <p><b>archive_read_disk_entry_from_file</b>(<i>struct&nbsp;archive&nbsp;*</i>,
 112 <i>struct&nbsp;archive_entry&nbsp;*</i>, <i>int&nbsp;fd</i>,
 113 <i>const&nbsp;struct&nbsp;stat&nbsp;*</i>);</p>
 114
 115 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
 116
 117
 118 <p style="margin-left:12%;"><b>archive_read_close</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
 119
 120 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
 121
 122
 123 <p style="margin-left:12%;"><b>archive_read_finish</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
 124
 125 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
 126
 127
 128 <p style="margin-left:12%;"><b>archive_read_free</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>
 129
 130 <p style="margin-top: 1em"><b>DESCRIPTION</b></p>
 131
 132 <p style="margin-left:6%;">These functions provide an API
 133 for reading information about objects on disk. In
 134 particular, they provide an interface for populating struct
 135 archive_entry objects.</p>
 136
 137
 138 <p style="margin-top: 1em"><b>archive_read_disk_new</b>()</p>
 139
 140 <p style="margin-left:17%;">Allocates and initializes a
 141 struct archive object suitable for reading object
 142 information from disk.</p>
 143
 144
 145 <p style="margin-top: 1em"><b>archive_read_disk_set_symlink_logical</b>(),
 146 <b>archive_read_disk_set_symlink_physical</b>(),
 147 <b>archive_read_disk_set_symlink_hybrid</b>()</p>
 148
 149 <p style="margin-left:17%;">This sets the mode used for
 150 handling symbolic links. The
 151 &rsquo;&rsquo;logical&rsquo;&rsquo; mode follows all
 152 symbolic links. The &rsquo;&rsquo;physical&rsquo;&rsquo;
 153 mode does not follow any symbolic links. The
 154 &rsquo;&rsquo;hybrid&rsquo;&rsquo; mode currently behaves
 155 identically to the &rsquo;&rsquo;logical&rsquo;&rsquo;
 156 mode.</p>
 157
 158
 159 <p style="margin-top: 1em"><b>archive_read_disk_gname</b>(),
 160 <b>archive_read_disk_uname</b>()</p>
 161
 162 <p style="margin-left:17%;">Returns a user or group name
 163 given a gid or uid value. By default, these always return a
 164 NULL string.</p>
 165
 166
 167 <p style="margin-top: 1em"><b>archive_read_disk_set_gname_lookup</b>(),
 168 <b>archive_read_disk_set_uname_lookup</b>()</p>
 169
 170 <p style="margin-left:17%;">These allow you to override the
 171 functions used for user and group name lookups. You may also
 172 provide a void * pointer to a private data structure and a
 173 cleanup function for that data. The cleanup function will be
 174 invoked when the struct archive object is destroyed or when
 175 new lookup functions are registered.</p>
 176
 177
 178 <p style="margin-top: 1em"><b>archive_read_disk_set_standard_lookup</b>()</p>
 179
 180 <p style="margin-left:17%;">This convenience function
 181 installs a standard set of user and group name lookup
 182 functions. These functions use getpwuid(3) and getgrgid(3)
 183 to convert ids to names, defaulting to NULL if the names
 184 cannot be looked up. These functions also implement a simple
 185 memory cache to reduce the number of calls to getpwuid(3)
 186 and getgrgid(3).</p>
 187
 188
 189 <p style="margin-top: 1em"><b>archive_read_disk_entry_from_file</b>()</p>
 190
 191 <p style="margin-left:17%;">Populates a struct
 192 archive_entry object with information about a particular
 193 file. The archive_entry object must have already been
 194 created with archive_entry_new(3) and at least one of the
 195 source path or path fields must already be set. (If both are
 196 set, the source path will be used.)</p>
 197
 198 <p style="margin-left:17%; margin-top: 1em">Information is
 199 read from disk using the path name from the struct
 200 archive_entry object. If a file descriptor is provided, some
 201 information will be obtained using that file descriptor, on
 202 platforms that support the appropriate system calls.</p>
 203
 204 <p style="margin-left:17%; margin-top: 1em">If a pointer to
 205 a struct stat is provided, information from that structure
 206 will be used instead of reading from the disk where
 207 appropriate. This can provide performance benefits in
 208 scenarios where struct stat information has already been
 209 read from the disk as a side effect of some other operation.
 210 (For example, directory traversal libraries often provide
 211 this information.)</p>
 212
 213 <p style="margin-left:17%; margin-top: 1em">Where
 214 necessary, user and group ids are converted to user and
 215 group names using the currently registered lookup functions
 216 above. This affects the file ownership fields and ACL values
 217 in the struct archive_entry object.</p>
 218
 219 <p style="margin-top: 1em"><b>archive_read_close</b>()</p>
 220
 221 <p style="margin-left:17%;">Does nothing for
 222 archive_read_disk handles.</p>
 223
 224
 225 <p style="margin-top: 1em"><b>archive_read_finish</b>()</p>
 226
 227 <p style="margin-left:17%;">This is a deprecated synonym
 228 for <b>archive_read_free</b>().</p>
 229
 230 <p style="margin-top: 1em"><b>archive_read_free</b>()</p>
 231
 232 <p style="margin-left:17%;">Invokes
 233 <b>archive_read_close</b>() if it was not invoked manually,
 234 then releases all resources.</p>
 235
 236 <p style="margin-left:6%;">More information about the
 237 <i>struct archive</i> object and the overall design of the
 238 library can be found in the libarchive(3) overview.</p>
 239
 240 <p style="margin-top: 1em"><b>EXAMPLE</b></p>
 241
 242 <p style="margin-left:6%;">The following illustrates basic
 243 usage of the library by showing how to use it to copy an
 244 item on disk into an archive.</p>
 245
 246 <p style="margin-left:14%; margin-top: 1em">void <br>
 247 file_to_archive(struct archive *a, const char *name) <br>
 248 { <br>
 249 char buff[8192]; <br>
 250 size_t bytes_read; <br>
 251 struct archive *ard; <br>
 252 struct archive_entry *entry; <br>
 253 int fd;</p>
 254
 255 <p style="margin-left:14%; margin-top: 1em">ard =
 256 archive_read_disk_new(); <br>
 257 archive_read_disk_set_standard_lookup(ard); <br>
 258 entry = archive_entry_new(); <br>
 259 fd = open(name, O_RDONLY); <br>
 260 if (fd &lt; 0) <br>
 261 return; <br>
 262 archive_entry_copy_pathname(entry, name); <br>
 263 archive_read_disk_entry_from_file(ard, entry, fd, NULL);
 264 <br>
 265 archive_write_header(a, entry); <br>
 266 while ((bytes_read = read(fd, buff, sizeof(buff))) &gt; 0)
 267 <br>
 268 archive_write_data(a, buff, bytes_read); <br>
 269 archive_write_finish_entry(a); <br>
 270 archive_read_free(ard); <br>
 271 archive_entry_free(entry); <br>
 272 }</p>
 273
 274 <p style="margin-top: 1em"><b>RETURN VALUES</b></p>
 275
 276 <p style="margin-left:6%;">Most functions return
 277 <b>ARCHIVE_OK</b> (zero) on success, or one of several
 278 negative error codes for errors. Specific error codes
 279 include: <b>ARCHIVE_RETRY</b> for operations that might
 280 succeed if retried, <b>ARCHIVE_WARN</b> for unusual
 281 conditions that do not prevent further operations, and
 282 <b>ARCHIVE_FATAL</b> for serious errors that make remaining
 283 operations impossible.</p>
 284
 285
 286 <p style="margin-left:6%; margin-top: 1em"><b>archive_read_disk_new</b>()
 287 returns a pointer to a newly-allocated struct archive object
 288 or NULL if the allocation failed for any reason.</p>
 289
 290
 291 <p style="margin-left:6%; margin-top: 1em"><b>archive_read_disk_gname</b>()
 292 and <b>archive_read_disk_uname</b>() return const char *
 293 pointers to the textual name or NULL if the lookup failed
 294 for any reason. The returned pointer points to internal
 295 storage that may be reused on the next call to either of
 296 these functions; callers should copy the string if they need
 297 to continue accessing it.</p>
 298
 299 <p style="margin-top: 1em"><b>ERRORS</b></p>
 300
 301 <p style="margin-left:6%;">Detailed error codes and textual
 302 descriptions are available from the <b>archive_errno</b>()
 303 and <b>archive_error_string</b>() functions.</p>
 304
 305 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 306
 307 <p style="margin-left:6%;">archive_read(3),
 308 archive_util(3), archive_write(3), archive_write_disk(3),
 309 tar(1), libarchive(3)</p>
 310
 311 <p style="margin-top: 1em"><b>HISTORY</b></p>
 312
 313 <p style="margin-left:6%;">The <b>libarchive</b> library
 314 first appeared in FreeBSD&nbsp;5.3. The
 315 <b>archive_read_disk</b> interface was added to
 316 <b>libarchive 2.6</b> and first appeared in
 317 FreeBSD&nbsp;8.0.</p>
 318
 319 <p style="margin-top: 1em"><b>AUTHORS</b></p>
 320
 321 <p style="margin-left:6%;">The <b>libarchive</b> library
 322 was written by Tim Kientzle
 323 &lt;kientzle@FreeBSD.org&gt;.</p>
 324
 325 <p style="margin-top: 1em"><b>BUGS</b></p>
 326
 327 <p style="margin-left:6%;">The
 328 &rsquo;&rsquo;standard&rsquo;&rsquo; user name and group
 329 name lookup functions are not the defaults because
 330 getgrgid(3) and getpwuid(3) are sometimes too large for
 331 particular applications. The current design allows the
 332 application author to use a more compact implementation when
 333 appropriate.</p>
 334
 335 <p style="margin-left:6%; margin-top: 1em">The full list of
 336 metadata read from disk by
 337 <b>archive_read_disk_entry_from_file</b>() is necessarily
 338 system-dependent.</p>
 339
 340 <p style="margin-left:6%; margin-top: 1em">The
 341 <b>archive_read_disk_entry_from_file</b>() function reads as
 342 much information as it can from disk. Some method should be
 343 provided to limit this so that clients who do not need ACLs,
 344 for instance, can avoid the extra work needed to look up
 345 such information.</p>
 346
 347 <p style="margin-left:6%; margin-top: 1em">This API should
 348 provide a set of methods for walking a directory tree. That
 349 would make it a direct parallel of the archive_read(3) API.
 350 When such methods are implemented, the
 351 &rsquo;&rsquo;hybrid&rsquo;&rsquo; symbolic link mode will
 352 make sense.</p>
 353
 354 <p style="margin-left:6%; margin-top: 1em">BSD
 355 December&nbsp;30, 2016 BSD</p>
 356 <hr>
 357 </body>
 358 </html>